Guest API untuk agen AI

API publik cenaly.com yang melaluinya asisten dan agen AI bertindak atas nama tamu: membaca menu restoran, mencari di katalog, menyusun keranjang, membuat Pesanan, dan memesan Meja. Untuk semua ini tidak diperlukan otorisasi — ini adalah operasi yang sama yang tersedia bagi tamu di situs menu.

Penomoran restoran#

Restoran diidentifikasi dengan kode lokasi — ini adalah segmen URL menu dalam huruf kapital. Jika menu terbuka di cenaly.com/MYCAFE, kodenya adalah MYCAFE. Kode yang sama tertanam di kode QR Meja.

Mulai cepat (REST)#

# Apa yang bisa dilakukan API
curl https://api.cenaly.com/llm/v1

# Menu restoran dalam bahasa Rusia
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Membuat Pesanan bawa pulang
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": "…"}

# Status Pesanan (orderId — token akses rahasia)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Spesifikasi lengkap: OpenAPI 3.1 · dokumentasi interaktif (dalam bahasa merek; ?lang=en|ka|ru|tr|sq).

Endpoint#

Keranjang: menyusun Pesanan langkah demi langkah#

Agen tidak harus menebak isi Pesanan dalam satu kali tembakan — keranjang dapat dikelola di server, seperti yang dilakukan orang di keranjang web:

1. POST /carts dengan baris pertama → cartId
2. PATCH /carts/{cartId} — menambah, mengubah jumlah, menghapus (quantity: 0)
3. POST /orders dengan cartId — membuat Pesanan

Harga di keranjang selalu dihitung ulang berdasarkan menu langsung, sehingga keranjang tidak dapat menampilkan jumlah yang sudah usang. Keranjang berlaku 7 hari. Di setiap respons ada checkoutUrl — tautan ini bisa langsung diberikan kepada orang agar ia menyelesaikan Pesanan di checkout biasa.

Saat membuat Pesanan dapat dikirimkan idempotencyKey (8–64 karakter): pengulangan dengan kunci yang sama dalam 48 jam akan mengembalikan Pesanan awal, bukan membuat yang kedua. Hal yang sama berlaku untuk Reservasi — pengulangan dalam jendela yang sama akan mengembalikan Reservasi awal, bukan menempati Meja kedua.

Koneksi melalui MCP#

Server: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Alat tamu bekerja tanpa otorisasi; masuk dengan OAuth menambahkan alat Akun Anda ke dalamnya.

Konfigurasi untuk Claude Desktop / Claude Code dan klien yang kompatibel:

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

Alat tamu (13, tanpa otorisasi):

Skenario umum:

• Pesanan cepat: get_menu → create_order → get_order_status (Nomor 4 digit muncul setelah beberapa detik).
• Pesanan dalam dialog: search_products → update_cart (satu Item demi satu, seperti dalam percakapan) → get_cart → create_order, atau berikan checkoutUrl kepada tamu dan biarkan ia menyelesaikan Pesanan sendiri.
• Pertanyaan tentang tempat usaha: get_store_info (alamat, jam, kontak) atau search_policies_and_faqs (ketentuan pengiriman, pengembalian, aturan).
• Reservasi Meja: check_table_availability (Meja dari denah ruangan, kosong/terisi pada waktu yang dipilih) → create_reservation dengan tableId → get_reservation_status (restoran mengonfirmasi permintaan) → bila perlu cancel_reservation.

Akses ke data Anda#

Jika Anda pemilik tempat usaha atau karyawan, 13 alat tamu yang sama ditambah dengan 12 alat untuk bekerja dengan akun Anda sendiri — dalam dua kelompok.

Data akun (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Alat-alat ini membuka tidak hanya menu dan pesanan, tetapi juga CRM, inventaris, personel, pengaturan kasir dan layar dapur, dokumen, dan hampir semua bagian lainnya.

Situs klien lokasi (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

Masuk — OAuth 2.1 biasa dengan akun cenaly.com Anda: klien MCP (Claude, ChatGPT, CLI) mendaftar sendiri dan membuka jendela login. Tidak perlu menempelkan apa pun secara manual.

• Metadata sumber daya: https://api.cenaly.com/.well-known/oauth-protected-resource
• Metadata server otorisasi: https://api.cenaly.com/.well-known/oauth-authorization-server
• Pendaftaran klien dinamis (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Selama belum ada token, tools/list hanya menampilkan alat tamu — alat terautorisasi tidak terlihat.

Aturan dan jaminan#

• Pesanan divalidasi terhadap menu langsung: hidangan, varian, atau tambahan yang tidak ada — kesalahan 400 dengan daftar masalah; harga dan total dihitung oleh server, agen tidak memiliki cara untuk "menetapkan" harga.
• Untuk ambil sendiri dan pengiriman, nama dan telepon tamu wajib diisi; untuk pengiriman — alamat.
• orderId / reservationId — token rahasia: dengannya status diperiksa dan reservasi dibatalkan. Jangan publikasikan.
• Pesanan dan reservasi masuk ke restoran secara real time — ke panel admin, layar dapur, dan notifikasi, seperti pesanan biasa dari situs.
• Reservasi tamu berstatus pending sampai restoran mengonfirmasinya di panel admin.
• Di Rusia, alkohol tidak dapat dipesan melalui kanal pesanan agen. Penjualan alkohol secara jarak jauh dilarang oleh undang-undang (pp. 14 p. 2 st. 16 171-FZ), oleh karena itu pada lokasi dengan negara "Rusia" pesanan dengan item alkohol tidak lolos validasi: dalam respons 400 dikirim baris dengan nama item tersebut dan penjelasan bahwa item itu hanya dapat dipesan dari pelayan di ruang makan. Pesanan harus disusun ulang tanpa alkohol.

Deteksi yang dapat dibaca mesin#

• https://cenaly.com/llms.txt — peta singkat API untuk LLM;
• GET https://api.cenaly.com/llm/v1 — dokumen discovery: daftar lengkap endpoint, contoh pesanan, reservasi, dan pengelolaan keranjang, tautan ke metadata OAuth.