Guest API pentru agenți AI

API public cenaly.com, prin care asistenții și agenții AI acționează în numele oaspetelui: citesc meniul restaurantului, caută în catalog, adună coșul, plasează comanda și rezervă o masă. Pentru toate acestea nu este nevoie de autorizare — sunt aceleași operațiuni disponibile oaspetelui pe site-ul meniului.

Adresarea restaurantului#

Restaurantul este adresat prin codul locației — acesta este segmentul URL-ului meniului scris cu majuscule. Dacă meniul se deschide la cenaly.com/MYCAFE, codul este MYCAFE. Același cod este încorporat în codurile QR ale meselor.

Start rapid (REST)#

# Ce poate face API-ul
curl https://api.cenaly.com/llm/v1

# Meniul restaurantului în rusă
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Plasarea unei comenzi pentru ridicare
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": "…"}

# Starea comenzii (orderId — token secret de acces)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Specificația completă: OpenAPI 3.1 · documentație interactivă (în limba brandului; ?lang=en|ka|ru|tr|sq).

Endpointuri#

Coșul: adunați comanda pas cu pas#

Agentul nu trebuie să ghicească conținutul comenzii dintr-o singură încercare — poate ține coșul pe server, așa cum face o persoană în coșul web:

1. POST /carts cu primele articole → cartId
2. PATCH /carts/{cartId} — adăugare, modificare cantitate, eliminare (quantity: 0)
3. POST /orders cu cartId — plasare

Prețurile din coș sunt întotdeauna recalculate după meniul live, astfel încât coșul nu poate afișa o sumă învechită. Coșul există 7 zile. În fiecare răspuns există checkoutUrl — linkul poate fi pur și simplu transmis unei persoane, ca să finalizeze comanda în checkout-ul obișnuit.

La crearea comenzii se poate transmite idempotencyKey (8–64 de caractere): repetarea cu același cheie în interval de 48 de ore va returna comanda inițială, fără a crea una nouă. Același lucru funcționează și pentru rezervări — repetarea în același interval va returna rezervarea inițială, fără a ocupa o a doua masă.

Conectare prin MCP#

Server: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Instrumentele pentru oaspeți funcționează fără autorizare; autentificarea prin OAuth adaugă la ele instrumentele contului dumneavoastră.

Configurație pentru Claude Desktop / Claude Code și clienți compatibili:

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

Instrumente pentru oaspeți (13, fără autorizare):

Scenarii tipice:

• Comandă rapidă: get_menu → create_order → get_order_status (numărul din 4 cifre apare după câteva secunde).
• Comandă în dialog: search_products → update_cart (articol cu articol, ca într-o conversație) → get_cart → create_order, sau transmiteți oaspetelui checkoutUrl și lăsați-l să finalizeze comanda singur.
• Întrebare despre unitate: get_store_info (adresă, ore, contacte) sau search_policies_and_faqs (condiții de livrare, returnare, reguli).
• Rezervare masă: check_table_availability (mesele din schema sălii, liberă/ocupată la ora aleasă) → create_reservation cu tableId → get_reservation_status (restaurantul confirmă cererea) → la nevoie cancel_reservation.

Accesul la propriile date#

Dacă sunteți proprietarul localului sau angajat, la aceleași 13 instrumente pentru oaspeți se adaugă 12 instrumente pentru lucrul cu propriul cont — în două grupuri.

Datele contului (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Acestea deschid nu doar meniul și comenzile, ci și CRM, depozitul, personalul, setările casei de marcat și ale ecranului de bucătărie, documentele și aproape toate celelalte secțiuni.

Site-ul client al punctului de lucru (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

Autentificarea este un OAuth 2.1 obișnuit sub contul dumneavoastră cenaly.com: clientul MCP (Claude, ChatGPT, CLI) se înregistrează singur și deschide fereastra de login. Nu trebuie să inserați nimic manual.

• Metadatele resursei: https://api.cenaly.com/.well-known/oauth-protected-resource
• Metadatele serverului de autorizare: https://api.cenaly.com/.well-known/oauth-authorization-server
• Înregistrarea dinamică a clientului (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Cât timp nu există token, tools/list arată doar instrumentele pentru oaspeți — cele autorizate pur și simplu nu sunt vizibile.

Reguli și garanții#

• Comanda este validată după meniul live: un preparat, o variantă sau un supliment inexistent — eroare 400 cu lista problemelor; prețurile și totalul sunt calculate de server, agentul nu are nicio modalitate de a „atribui” un preț.
• Pentru ridicarea personală și livrare sunt obligatorii numele și telefonul oaspetelui; pentru livrare — adresa.
• orderId / reservationId — tokenuri secrete: după ele se verifică statusul și se anulează rezervarea. Nu le publicați.
• Comenzile și rezervările ajung la restaurant în timp real — în panoul de administrare, pe ecranul de bucătărie și în notificări, ca comenzile obișnuite de pe site.
• Rezervările oaspetelui au statusul pending până când restaurantul le confirmă în panoul de administrare.
• În Rusia, alcoolul nu poate fi comandat prin canalul de agent. Vânzarea la distanță a producției alcoolice este interzisă prin lege (pp. 14 p. 2 st. 16 171-FZ), de aceea la punctele de lucru cu țara „Rusia” o comandă cu un articol alcoolic nu trece validarea: în răspunsul 400 vine un rând cu denumirea acestui articol și explicația că poate fi comandat doar de la ospătar în sală. Comanda trebuie reasamblată fără alcool.

Detectare citibilă de mașini#

• https://cenaly.com/llms.txt — harta concisă a API-ului pentru LLM;
• GET https://api.cenaly.com/llm/v1 — documentul de discovery: lista completă a endpoint-urilor, exemple de comandă, rezervare și lucru cu coșul, linkuri către metadatele OAuth.