studio.agentkit.best/docs/ standard
One platform. Human & AI Agent Ready
Đặc tả API, chu trình gọi món 3s, Bếp KDS và công cụ Browser WebMCP chuẩn 2027.
01 · Quickstart
Khởi đầu nhanh (B2C Thực khách & B2B Chủ quán)
02 · Operations
Nghiệp vụ cốt lõi (Thực đơn, Bếp KDS WebSocket & Loyalty)
03 · Billing & RBAC
Thanh toán MoMo v2, Gói cước SaaS & Phân quyền RBAC
04 · AI & WebMCP
Tích hợp AI Agent, AEO/GEO & Giao thức Browser WebMCP
01 · Quickstart
Khởi đầu nhanh (B2C Thực khách & B2B Chủ quán)
Quét mã QR đặt bia tươi tại bàn ở TP. Sa Đéc chỉ trong 3 giây hoặc khởi tạo quán F&B trực tuyến trong 5 phút với Setup Wizard 7 bước.
Điểm mấu chốt
- 1.Thực khách B2C tại 128 Nguyễn Tất Thành, TP. Sa Đéc quét QR đặt món trực tiếp trên trình duyệt, không cần cài ứng dụng.
- 2.Chủ quán B2B hoàn tất 7 bước: Thông tin quán -> Chủ quán -> Tải CSV Menu -> Thương hiệu -> MoMo/PayOS -> Xem trước -> Xuất bản QR.
- 3.Mọi mức giá trong D1 lưu theo price_cents và tự động chuẩn hóa sang VNĐ (Math.round(price_cents / 100)).
| Method | Path | Access & HITL | Mô tả |
|---|---|---|---|
| GET | /api/health | Read-Only | Kiểm tra kết nối Worker & D1 Edge |
| GET | /api/menu?venue_id=co-bong-sa-dec | Read-Only | Lấy thực đơn công khai theo nhóm món |
bash
# 1. Kiểm tra trạng thái hệ thống & lấy thực đơn Quán Bia Cô Bông Sa Đéc
curl -s "https://quan-bia-co-bong.agencyos-openclaw.workers.dev/api/health" | jq .
curl -s "https://quan-bia-co-bong.agencyos-openclaw.workers.dev/api/menu?venue_id=co-bong-sa-dec" | jq '.categories | keys'02 · Operations
Nghiệp vụ cốt lõi (Thực đơn, Bếp KDS WebSocket & Loyalty)
Chu trình khép kín từ lúc khách chọn món vào giỏ, xác thực giá từ D1, đẩy đơn thời gian thực vào KitchenDO đến tích điểm thành viên.
Điểm mấu chốt
- 1.Chống thao túng giá: POST /api/orders luôn truy vấn lại price_cents từ bảng menu_items trong D1 trước khi tính tổng tiền.
- 2.Màn hình Bếp KDS kết nối WebSocket qua Durable Object (KitchenDO), phát âm báo món mới và in nhiệt ESC/POS.
- 3.Khách hàng tích điểm tự động (1 điểm / 100 VNĐ) và thăng hạng Đồng (0), Bạc (500), Vàng (2.000 điểm).
| Method | Path | Access & HITL | Mô tả |
|---|---|---|---|
| POST | /api/orders | Human Confirmation Required | Tạo đơn hàng mới (bắt buộc người thật xác nhận) |
| PATCH | /api/orders/:id/status | Bearer Token | Chuyển trạng thái đơn một chiều (pending -> completed) |
| POST | /api/loyalty/earn | Bearer Token | Ghi nhận điểm thưởng khách hàng thân thiết |
json
{
"venue_id": "co-bong-sa-dec",
"table_number": "B08",
"customer_phone": "0907686868",
"items": [
{ "menu_item_id": "item-sadec-lager", "quantity": 4, "price_vnd": 35000 },
{ "menu_item_id": "item-kho-ca-loc", "quantity": 1, "price_vnd": 95000 }
],
"status_flow": ["pending", "preparing", "ready", "completed"]
}03 · Billing & RBAC
Thanh toán MoMo v2, Gói cước SaaS & Phân quyền RBAC
Xác thực chữ ký HMAC-SHA256 cho MoMo v2 IPN, chống xử lý trùng bằng Cloudflare KV và quản lý 4 gói thuê bao SaaS.
Điểm mấu chốt
- 1.Webhook IPN (/api/payments/momo/callback) kiểm tra chữ ký HMAC-SHA256 và khóa chống trùng KV (payments:ipn:{partnerCode}:{orderId}).
- 2.4 gói thuê bao B2B: Dùng thử 0đ (14 ngày), Cơ bản 299.000đ/tháng, Chuyên nghiệp 799.000đ/tháng, Doanh nghiệp.
- 3.RBAC 3 tầng (Admin, Venue Owner, Customer) kết hợp bộ đếm Rate Limit Fixed-Window trên KV chống spam.
| Method | Path | Access & HITL | Mô tả |
|---|---|---|---|
| POST | /api/payments/create | Human Confirmation Required | Tạo liên kết thanh toán MoMo v2 |
| POST | /api/payments/momo/callback | Read-Only | Nhận IPN webhook từ MoMo (HMAC-SHA256 + KV dedup) |
bash
# Khởi tạo thanh toán MoMo v2 và kiểm tra trạng thái gói thuê bao của quán
curl -X POST "https://quan-bia-co-bong.agencyos-openclaw.workers.dev/api/payments/create" -H "Content-Type: application/json" -d '{"orderId":"ORD-2027-88","amount":235000,"orderInfo":"Ban B08 - Quan Bia Co Bong Sa Dec"}'04 · AI & WebMCP
Tích hợp AI Agent, AEO/GEO & Giao thức Browser WebMCP
Truy vấn thực đơn dạng Markdown tiết kiệm 60% token, đồ thị JSON-LD @graph phân tách B2C/B2B và công cụ navigator.modelContext an toàn.
Điểm mấu chốt
- 1.AI Crawler đọc tự do qua /llms.txt, /llms-full.txt, GET /api/catalog?format=md và GET /api/schema (OpenAPI 3.1).
- 2.Trình duyệt hỗ trợ WebMCP (navigator.modelContext) với các công cụ search_catalog, get_venue_info, prepare_draft_cart.
- 3.Chốt chặn Human-in-the-loop: mọi hành động tạo đơn (POST /api/orders) hoặc gửi lead đều yêu cầu người dùng bấm xác nhận (event.isTrusted === true).
| Method | Path | Access & HITL | Mô tả |
|---|---|---|---|
| GET | /api/catalog?format=md | Read-Only | Xuất thực đơn & bảng giá dạng Markdown nén cho LLM |
| GET | /api/schema | Read-Only | Đặc tả OpenAPI 3.1.0 kèm cờ x-human-confirmation-required |
| GET | /api/llms.txt | Read-Only | Chỉ mục ngữ cảnh AI động từ D1 & Brand Sa Đéc |
bash
# Tải thực đơn chuẩn Markdown cho LLM hoặc khám phá OpenAPI 3.1 Schema
curl -s "https://quan-bia-co-bong.agencyos-openclaw.workers.dev/api/catalog?venue_id=co-bong-sa-dec&format=md"
curl -s "https://quan-bia-co-bong.agencyos-openclaw.workers.dev/api/schema" | jq '.paths'
curl -s "https://quan-bia-co-bong.pages.dev/llms.txt"