Hướng dẫn sử dụng NaturaOS

NaturaOS là công cụ số hóa khiêm tốn, kế thừa thuật toán âm lịch của TS. Hồ Ngọc Đức và học hỏi từ các bậc học giả tiền nhân (Cụ Phan Bội Châu, Học giả Nguyễn Hiến Lê, BS. Nhân Tử Nguyễn Văn Thọ). Đồng thời, nhằm bảo đảm tính khách quan và tuân thủ bản quyền nghiêm ngặt, hệ thống được dịch thuật và đối chiếu độc lập từ nguyên tác Hán văn cổ cùng các tài liệu học thuật quốc tế (Wilhelm, Legge). Chúng tôi cung cấp dữ liệu JSON tất định 100% cho việc tra cứu và tính toán, nói không với mê tín hay bói toán.

① Lấy API Key

Mọi request đến engine (trừ các endpoint khám phá và tài liệu) đều cần API key. Key được liên kết với tổ chức của bạn.

Đăng nhập để lấy key →

② Gọi thử

Truyền key qua header Authorization: Bearer <key> hoặc X-API-Key: <key>:

curl -H "Authorization: Bearer <api-key>" \
  https://naturaos.mza.vn/api/v1/calendar/day?date=2026-09-05

Phản hồi mẫu chuẩn (envelope):

{
  "ok": true,
  "data": {
    "solar": { "year": 2026, "month": 9, "day": 5 },
    "lunar": { "year": 2026, "month": 7, "day": 24, "leap": false }
  },
  "meta": { "cached": false }
}

③ Cắm vào công cụ

Mỗi công cụ nhận credential theo cách riêng. Dưới đây là bảng cấu hình cho từng ứng dụng:

Công cụ	Loại tích hợp	Cách cấu hình
Claude Code	MCP CLI	`claude mcp add naturaos https://naturaos.mza.vn/mcp --header "Authorization: Bearer <api-key>"`
Gemini CLI / Desktop	MCP Header	Thêm MCP server tại `https://naturaos.mza.vn/mcp` với header Bearer token.
ChatGPT	OAuth 2.0	Không nhận header — đăng nhập qua OAuth khi kết nối, chỉ cần điền URL: `https://naturaos.mza.vn/mcp`
n8n / Scripts	REST API	Gọi REST trực tiếp với header `Authorization: Bearer` hoặc `X-API-Key`.

④ Danh sách Operation

Danh sách các thao tác khả dụng được sinh động từ registry của engine:

Tên Operation	Mô tả	REST Endpoint	MCP Tool Name	Chi phí
calendar.dayInfo	Xem ngày: âm lịch, can chi ngày/tháng/năm, giờ đầu ngày, tiết khí, giờ hoàng đạo.	/api/v1/calendar/day	calendar_dayInfo	1
calendar.convertSolarToLunar	Đổi ngày dương sang ngày âm lịch Việt Nam.	/api/v1/calendar/lunar-date	calendar_convertSolarToLunar	1
ganzhi.calendarPillars	Can chi năm/tháng/ngày/giờ theo lịch (năm đổi ở Tết) — không phải bát tự.	/api/v1/ganzhi/calendar-pillars	ganzhi_calendarPillars	1
wuxing.relations	Quan hệ sinh/khắc ngũ hành của một hành, và giữa hai hành.	/api/v1/wuxing/relations	wuxing_relations	1
iching.cast	Gieo quẻ kinh dịch theo số Thượng–Hạ–Động hoặc theo thời điểm.	/api/v1/iching/cast	iching_cast	1
iching.hexagram	Tra một quẻ kinh dịch: hai quái, sáu hào, quan hệ, kinh văn và luận quẻ.	/api/v1/iching/hexagram	iching_hexagram	3

Xem tham số đầy đủ, ví dụ copy-chạy-được (curl, JavaScript) và response thật cho từng op tại /docs.

⑤ Hạn mức

Hạn mức được tính theo chi phí (cost) của từng operation chứ không tính thuần theo số lượt request:

Gói Free: 200 lượt / ngày, reset vào 00:00 (Asia/Ho_Chi_Minh).
Gói Pro: 5000 lượt / tháng.
Kiểm tra hạn mức còn lại bất kỳ lúc nào qua endpoint: /api/v1/usage (hoàn toàn miễn phí, không tốn quota).

⑥ Mất key / Thu hồi key

Nếu nghi ngờ lộ key, hãy truy cập Dashboard để thu hồi ngay lập tức.

Lưu ý: Do cơ chế phân tán bộ nhớ đệm (isolate cache) để tối ưu hiệu năng đọc D1, key bị thu hồi có thể tiếp tục có hiệu lực tối đa 60 giây trước khi bị từ chối hoàn toàn trên mọi khu vực.

⑦ Bảng mã lỗi

Khi request không thành công, engine trả về mã trạng thái HTTP tương ứng cùng envelope chứa mã lỗi cố định:

Mã lỗi	Ý nghĩa	Hướng xử lý
UNAUTHORIZED	Thiếu hoặc sai API key	Kiểm tra header gửi kèm. Key mới tạo cần tối đa 60 giây để đồng bộ toàn mạng.
QUOTA_EXCEEDED	Hết lượt trong kỳ	Chờ đến thời điểm reset, hoặc bớt gọi các operation có chi phí cao.
RATE_LIMITED	Gọi quá dày trong một phút	Vượt ngưỡng burst limit. Tạm dừng và thử lại sau 1 phút.
PLAN_REQUIRED	Yêu cầu gói nâng cao	Op thuộc gói trả phí. Hiện toàn bộ op công khai thuộc gói free; nếu gặp mã này, hãy liên hệ hỗ trợ.
BAD_INPUT	Tham số đầu vào không đúng	Xem chi tiết trường `message` trong JSON để sửa tham số.
METER_UNAVAILABLE	Không đếm được usage	Hệ thống đo đếm tạm gián đoạn. API từ chối thay vì phục vụ không tính lượt. Thử lại sau vài giây.