Guest API cho AI-agent

API công khai của cenaly.com, qua đó trợ lý AI và agent hành động thay mặt khách: đọc thực đơn của nhà hàng, tìm kiếm trong danh mục, lập giỏ hàng, đặt hàng và đặt bàn. Tất cả những việc này đều không cần xác thực — đây chính là những thao tác mà khách có thể thực hiện trên trang thực đơn.

Định địa chỉ nhà hàng#

Nhà hàng được định địa chỉ bằng mã chi nhánh — đây là phân đoạn URL của thực đơn viết bằng chữ in hoa. Nếu thực đơn mở tại cenaly.com/MYCAFE, mã là MYCAFE. Mã này cũng được ghi trong mã QR của Bàn.

Bắt đầu nhanh (REST)#

# API có thể làm gì
curl https://api.cenaly.com/llm/v1

# Thực đơn nhà hàng bằng tiếng Nga
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Đặt hàng mang về
curl -X POST https://api.cenaly.com/llm/v1/locations/MYCAFE/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [{"itemId": "abc123", "quantity": 2}],
    "orderType": "pickup",
    "customer": {"name": "Гость", "phone": "+995555123456"},
    "language": "ru"
  }'
# → {"accepted": true, "orderId": "…", "total": 24, "statusUrl": "…"}

# Trạng thái Đơn hàng (orderId — token truy cập bí mật)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Đặc tả đầy đủ: OpenAPI 3.1 · tài liệu tương tác (theo ngôn ngữ thương hiệu; ?lang=en|ka|ru|tr|sq).

Các endpoint#

Giỏ hàng: lập Đơn hàng theo từng bước#

Agent không nhất thiết phải đoán thành phần Đơn hàng trong một lần — có thể duy trì giỏ hàng trên máy chủ, giống như cách một người làm trong giỏ hàng trên web:

1. POST /carts với các dòng đầu tiên → cartId
2. PATCH /carts/{cartId} — thêm, đổi số lượng, bỏ (quantity: 0)
3. POST /orders với cartId — đặt hàng

Giá trong giỏ hàng luôn được tính lại theo thực đơn trực tiếp, nên giỏ hàng không thể hiển thị số tiền cũ. Giỏ hàng tồn tại 7 ngày. Trong mỗi phản hồi đều có checkoutUrl — có thể đưa liên kết này cho người dùng để họ hoàn tất Đơn hàng trong trang thanh toán thông thường.

Khi tạo Đơn hàng, có thể truyền idempotencyKey (8–64 ký tự): lặp lại với cùng khóa trong vòng 48 giờ sẽ trả về Đơn hàng ban đầu, chứ không tạo Đơn hàng thứ hai. Điều này cũng áp dụng cho Đặt bàn — lặp lại trong cùng khoảng thời gian sẽ trả về Đặt bàn ban đầu, chứ không chiếm Bàn thứ hai.

Kết nối qua MCP#

Máy chủ: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Các công cụ dành cho khách hoạt động không cần xác thực; đăng nhập bằng OAuth sẽ thêm vào đó các công cụ của Tài khoản bạn.

Cấu hình cho Claude Desktop / Claude Code và các ứng dụng tương thích:

{
  "mcpServers": {
    "meni-guest": {
      "type": "http",
      "url": "https://api.cenaly.com/llm/mcp"
    }
  }
}

Các công cụ dành cho khách (13, không cần xác thực):

Các kịch bản điển hình:

• Đặt hàng nhanh: get_menu → create_order → get_order_status (số gồm 4 chữ số xuất hiện sau vài giây).
• Đặt hàng trong hội thoại: search_products → update_cart (từng Mặt hàng một, như trong cuộc trò chuyện) → get_cart → create_order, hoặc đưa cho khách checkoutUrl để khách tự hoàn tất Đơn hàng.
• Câu hỏi về cơ sở: get_store_info (địa chỉ, giờ, liên hệ) hoặc search_policies_and_faqs (điều kiện giao hàng, hoàn trả, quy tắc).
• Đặt bàn: check_table_availability (Bàn theo sơ đồ phòng, trống/đã có khách vào thời gian đã chọn) → create_reservation với tableId → get_reservation_status (nhà hàng xác nhận yêu cầu) → khi cần thì cancel_reservation.

Truy cập dữ liệu của riêng bạn#

Nếu bạn là chủ cơ sở hoặc nhân viên, thì bên cạnh 13 công cụ dành cho khách sẽ có thêm 12 công cụ làm việc với Tài khoản của bạn — chia thành hai nhóm.

Dữ liệu Tài khoản (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Chúng mở ra không chỉ thực đơn và Đơn hàng mà còn cả CRM, kho, nhân sự, cài đặt Thu ngân và màn hình bếp, tài liệu và gần như mọi mục khác.

Trang web khách hàng của Chi nhánh (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

Đăng nhập — OAuth 2.1 thông thường dưới Tài khoản cenaly.com của bạn: ứng dụng khách MCP (Claude, ChatGPT, CLI) tự đăng ký và mở cửa sổ đăng nhập. Không cần dán thủ công bất cứ thứ gì.

• Siêu dữ liệu tài nguyên: https://api.cenaly.com/.well-known/oauth-protected-resource
• Siêu dữ liệu máy chủ cấp quyền: https://api.cenaly.com/.well-known/oauth-authorization-server
• Đăng ký ứng dụng khách động (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Khi chưa có token, tools/list chỉ hiển thị các công cụ dành cho khách — các công cụ được cấp quyền đơn giản là không hiển thị.

Quy tắc và bảo đảm#

• Đơn hàng được xác thực theo thực đơn trực tiếp: món, biến thể hoặc món thêm không tồn tại — lỗi 400 kèm danh sách vấn đề; giá và tổng tiền do máy chủ tính, tác nhân không có cách nào “gán” giá.
• Với tự đến lấy và giao hàng, bắt buộc có tên và số điện thoại của khách; với giao hàng — địa chỉ.
• orderId / reservationId — token bí mật: dùng chúng để kiểm tra trạng thái và hủy Đặt bàn. Không công bố chúng.
• Đơn hàng và Đặt bàn đến nhà hàng theo thời gian thực — vào trang quản trị, màn hình bếp và thông báo, như các Đơn hàng thông thường từ trang web.
• Đặt bàn của khách có trạng thái pending cho đến khi nhà hàng xác nhận trong trang quản trị.
• Ở Nga không thể đặt đồ uống có cồn qua kênh đặt hàng của tác nhân. Bán đồ uống có cồn từ xa bị pháp luật cấm (điểm 14 khoản 2 Điều 16 171-FZ), vì vậy với các Chi nhánh có quốc gia “Nga”, Đơn hàng có Mặt hàng đồ uống có cồn không vượt qua xác thực: trong phản hồi 400 có dòng chứa tên Mặt hàng đó và giải thích rằng chỉ có thể đặt nó từ phục vụ trong phòng. Cần tạo lại Đơn hàng mà không có đồ uống có cồn.

Phát hiện dành cho máy#

• https://cenaly.com/llms.txt — bản đồ API ngắn gọn cho LLM;
• GET https://api.cenaly.com/llm/v1 — tài liệu discovery: danh sách đầy đủ các điểm cuối, ví dụ về Đơn hàng, Đặt bàn và thao tác với giỏ hàng, liên kết đến siêu dữ liệu OAuth.