REST API map — các service cho cloud applications

Tất cả API đều do chính website Next.js phục vụ (cùng origin, /api/...), trừ phần proxy ghi chú riêng. Quy ước chung:

• Auth: hầu hết endpoint yêu cầu session cookie cdms_session (đăng nhập qua /api/auth/signin, /api/auth/signup hoặc Google). Các route health và auth/* của engine là ngoại lệ (công khai).
• Credits: mỗi POST hành động trừ 1 credit (trừ auth/health); GET không trừ. Hết credit → 402.
• Không key LLM vẫn chạy: các engine có fallback rule-based/retrieval; set key để bật phần LLM.

1. Tài khoản & thanh toán

Method	Endpoint	Auth	Ghi chú
POST	/api/auth/signup	–	Tạo account, tặng 50 credits
POST	/api/auth/signin	–	Trả session cookie
POST	/api/auth/signout	session	Xoá session
POST	/api/auth/google	Google ID token	Đăng nhập/đăng ký Google
GET	/api/auth/me	session	Hồ sơ + số dư credits
POST	/api/credits/topup	session	Nạp credits (license/PayPal)
POST	/api/credits/paypal/create-order	session	Tạo đơn PayPal
POST	/api/credits/paypal/capture	session	Capture đơn PayPal
POST	/api/licenses/redeem	session	Đổi license key
POST	/api/support	–	Form hỗ trợ

2. Cloud engine — Chat2Data / Chat2Docs / Chat2Video

Ba console dùng chung một engine trong website. Gọi qua bất kỳ prefix nào: /api/chat2data/*, /api/chat2docs/*, /api/chat2video/* (endpoint giống hệt nhau; prefix chỉ để phân console).

Method	Endpoint	Ghi chú
GET	/api/chat2docs/health	Trạng thái engine + cấu hình
POST	…/auth/login	Đăng nhập engine (token riêng)
POST	…/auth/register	Đăng ký engine user
GET/POST	…/auth/session	Cấp/đổi engine token
GET	…/me (…/auth/me)	Thông tin user engine
POST	…/query (…/chat/query)	Hỏi đáp grounded-RAG (1 credit)
POST	…/ingest/upload (…/ingest/file)	Upload PDF/Office/ảnh/audio/video (1 credit)
POST	…/ingest/url	Nạp tài liệu từ URL an toàn (1 credit)
GET	…/knowledge (…/documents)	Danh sách collection/tài liệu
POST	…/knowledge/delete (…/documents/delete)	Xoá tài liệu khỏi collection
POST	…/memory/clear	Xoá memory hội thoại
GET	…/video/tracks	Track video (transcript)
GET	…/chat/collections (…/collections)	Danh sách collection

Env: POSTGRES_URL/DATABASE_URL (Neon — bắt buộc để dữ liệu bền), PINECONE_API_KEY (vector store, bật nếu có), AI_GATEWAY_API_KEY hoặc OPENROUTER_API_KEY (trả lời tổng hợp bằng LLM).

3. EbookMaker Cloud

Method	Endpoint	Ghi chú
GET	/api/ebookmaker/health	Công khai
GET	/api/ebookmaker/jobs	Danh sách job của user
POST	/api/ebookmaker/jobs	Tạo job dựng ebook (1 credit)
GET	/api/ebookmaker/jobs/{id}	Trạng thái job
DELETE	/api/ebookmaker/jobs/{id}	Xoá job (chỉ khi xong/lỗi)
GET	/api/ebookmaker/jobs/{id}/result/{kind}	Tải epub/pdf/htmlz/mobi…

4. Legal Cloud (25 tool native)

Method	Endpoint	Ghi chú
GET	/api/legalsuite/v1/legal/search?query=&limit=&domains=	Tra cứu corpus 600 văn bản (BM25); mỗi kết quả kèm freshness (tình trạng hiệu lực + văn bản mới hơn) khi lớp HF bật
POST	/api/legalsuite/v1/contracts/clause	Sinh điều khoản theo mẫu (1 credit)
POST	/api/legalsuite/v1/chat	Hỏi đáp vòng lặp evaluate-refine (Legal-Query-RAG): generate → LLM-judge RAG triad → refine query khi dưới ngưỡng; trả verified/withheld/scores/attempts, không key trả đoạn luật (1 credit)
GET	/api/legalsuite/v1/tools	Catalogue 25 tool (shape giống engine)
POST	/api/legalsuite/v1/tools/execute	Chạy 1 trong 25 tool: tài liệu, thư mục, rà soát hợp đồng, bộ nhớ công ty, crawl văn bản (1 credit)
GET	/api/legalsuite/v1/utilities/fees/search?query=&region=&limit=	Tiện ích — tra 22.800 mức phí/lệ phí kèm căn cứ pháp lý + meta (phạm vi đến 2024) (không credit)
GET	/api/legalsuite/v1/utilities/land/provinces	Tiện ích — danh sách 34 tỉnh thuộc bảng giá đất 2026 kèm số dòng + meta (nguồn, ngày tải, VT1–VT7)
GET	/api/legalsuite/v1/utilities/land/search?province=&district=&street=&limit=	Tiện ích — tra giá đất theo đường/đoạn, VT1–VT7, 199.558 dòng (không credit)
GET	/api/legalsuite/v1/utilities/case-law/search?q=&field=&limit=	Án lệ — tra 72 án lệ (số hiệu, từ khoá, tình huống/giải pháp, toàn văn) + meta; nguồn luatvietnam.vn (không credit)
GET	/api/legalsuite/v1/utilities/case-law/get?id=	Án lệ — chi tiết + toàn văn theo số hiệu (72/2024/AL) (không credit)
GET	/api/legalsuite/v1/mode	native hoặc engine

Khi set LEGALSUITE_API_URL, mọi path khác (vd v1/chat LangGraph, sessions) được proxy sang engine; /v1/tools + /v1/tools/execute vẫn chạy native để schema catalogue khớp executor.

5. WBS Cloud (pipeline)

Method	Endpoint	Ghi chú
GET	/api/wbs/health	Trạng thái pipeline + Neon
GET/POST	/api/wbs/runs	Liệt kê/tạo run
GET	/api/wbs/runs/{id}	Chi tiết run (các stage, artifact)
GET/POST	/api/wbs/schedules	Liệt kê/tạo lịch chạy
GET/DELETE	/api/wbs/schedules/{id}	Sửa/hoãn lịch
POST	/api/wbs/uploads	Upload file đầu vào
POST	/api/wbs/worker	Tick worker xử lý hàng đợi

Env: POSTGRES_URL (Neon, bắt buộc — WBS không có SQLite fallback), NEO4J_URI + NEO4J_USERNAME + NEO4J_PASSWORD (lineage graph AuraDB, fail-soft).

6. Games & Publish

Method	Endpoint	Ghi chú
POST	/api/games/score	Ghi điểm minigame
GET	/api/games/leaderboard?book=&category=	Bảng xếp hạng
GET/POST	/api/publish/{platform}/connect	Kết nối kênh (facebook, youtube, tiktok, shopee, lazada, tiki)
GET	/api/publish/{platform}/callback	OAuth callback
POST	/api/publish/{platform}/upload	Đăng nội dung lên kênh (1 credit)
POST	/api/publish/upload-file	Upload media dùng chung

Env Publish: FACEBOOK_*, YOUTUBE_*, TIKTOK_*, SHOPEE_*, LAZADA_*, TIKI_*, BLOB_READ_WRITE_TOKEN (Vercel Blob, fallback lưu file).

7. Ma trận service ↔ biến môi trường

Service	Bắt buộc	Tuỳ chọn (bật thêm)
Account/Credits/Games	AUTH_SECRET; POSTGRES_URL (bền)	BOOTSTRAP_ACCOUNTS, SUPER_USER_EMAILS
Cloud engine (3 console)	POSTGRES_URL	PINECONE_API_KEY, AI_GATEWAY_API_KEY / OPENROUTER_API_KEY
EbookMaker	POSTGRES_URL	–
Legal Cloud	– (corpus đi kèm repo)	AI_GATEWAY_API_KEY (chat/review LLM), LEGALSUITE_API_URL (engine LangGraph)
WBS	POSTGRES_URL (Neon)	NEO4J_URI/NEO4J_USERNAME/NEO4J_PASSWORD
Publish	credentials từng kênh	BLOB_READ_WRITE_TOKEN