Guest API per agenti AI

API pubblico di cenaly.com, tramite il quale gli assistenti e gli agenti AI agiscono per conto dell'ospite: consultano il menù del ristorante, cercano nel catalogo, compongono il carrello, effettuano l'ordine e prenotano un tavolo. Per tutto questo non serve l'autorizzazione: sono le stesse operazioni disponibili all'ospite sul sito del menù.

Indirizzamento del ristorante#

Il ristorante è identificato da un codice di sede: è il segmento dell'URL del menù in maiuscolo. Se il menù si apre su cenaly.com/MYCAFE, il codice è MYCAFE. Lo stesso codice è incorporato nei codici QR dei tavoli.

Avvio rapido (REST)#

# Cosa sa fare l'API
curl https://api.cenaly.com/llm/v1

# Menù del ristorante in russo
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Effettuare un ordine da asporto
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": "…"}

# Stato dell'ordine (orderId — token di accesso segreto)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Specifica completa: OpenAPI 3.1 · documentazione interattiva (nella lingua del brand; ?lang=en|ka|ru|tr|sq).

Endpoint#

Carrello: comporre l'ordine passo dopo passo#

L'agente non deve indovinare la composizione dell'ordine in un colpo solo: può gestire il carrello sul server, come farebbe una persona nel carrello web:

1. POST /carts con le prime righe → cartId
2. PATCH /carts/{cartId} — aggiungere, modificare la quantità, rimuovere (quantity: 0)
3. POST /orders con cartId — effettuare l'ordine

I prezzi nel carrello vengono sempre ricalcolati sul menù in tempo reale, quindi non può mostrare un importo obsoleto. Il carrello dura 7 giorni. In ogni risposta è presente checkoutUrl: il link può essere semplicemente consegnato alla persona, perché completi l'ordine nel normale checkout.

Alla creazione dell'ordine si può passare una idempotencyKey (8–64 caratteri): una ripetizione con la stessa chiave entro 48 ore restituirà l'ordine originale, senza crearne un secondo. Lo stesso vale per le prenotazioni: una ripetizione nella stessa finestra restituirà la prenotazione originale, senza occupare un secondo tavolo.

Connessione tramite MCP#

Server: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Gli strumenti per gli ospiti funzionano senza autorizzazione; l'accesso tramite OAuth vi aggiunge gli strumenti del proprio account.

Configurazione per Claude Desktop / Claude Code e client compatibili:

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

Strumenti per gli ospiti (13, senza autorizzazione):

Scenari tipici:

• Ordine rapido: get_menu → create_order → get_order_status (il numero a 4 cifre compare dopo un paio di secondi).
• Ordine in conversazione: search_products → update_cart (un articolo alla volta, come in una conversazione) → get_cart → create_order, oppure consegnare all'ospite il checkoutUrl e lasciargli completare l'ordine da solo.
• Domanda sulla struttura: get_store_info (indirizzo, orari, contatti) oppure search_policies_and_faqs (condizioni di consegna, reso, regole).
• Prenotazione del tavolo: check_table_availability (tavoli dalla piantina della sala, libero/occupato per l'orario scelto) → create_reservation con tableId → get_reservation_status (il ristorante conferma la richiesta) → se necessario cancel_reservation.

Accesso ai propri dati#

Se sei il titolare di una sede o un collaboratore, ai medesimi 13 strumenti guest si aggiungono 12 strumenti per lavorare con il proprio account — in due gruppi.

Dati dell'account (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Aprono non solo menu e ordini, ma anche CRM, magazzino, personale, impostazioni della cassa e dello schermo cucina, documenti e quasi tutte le altre sezioni.

Sito client della sede (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

L'accesso avviene con il normale OAuth 2.1 sotto il proprio account cenaly.com: il client MCP (Claude, ChatGPT, CLI) si registra da solo e apre la finestra di login. Non serve incollare nulla a mano.

• Metadati della risorsa: https://api.cenaly.com/.well-known/oauth-protected-resource
• Metadati del server di autorizzazione: https://api.cenaly.com/.well-known/oauth-authorization-server
• Registrazione dinamica del client (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Finché non c'è un token, tools/list mostra solo gli strumenti guest — quelli autorizzati semplicemente non sono visibili.

Regole e garanzie#

• L'ordine viene validato sul menu live: un piatto, una variante o un extra inesistente dà errore 400 con l'elenco dei problemi; prezzi e totale li calcola il server, l'agente non ha modo di «assegnare» un prezzo.
• Per l'asporto e la consegna sono obbligatori nome e telefono dell'ospite; per la consegna anche l'indirizzo.
• orderId / reservationId — token segreti: con questi si verifica lo stato e si annulla la prenotazione. Non pubblicarli.
• Ordini e prenotazioni arrivano al ristorante in tempo reale — nell'area di amministrazione, sullo schermo cucina e nelle notifiche, come i normali ordini dal sito.
• Le prenotazioni dell'ospite hanno stato pending finché il ristorante non le conferma nell'area di amministrazione.
• In Russia non è possibile ordinare alcolici tramite il canale dell'agente. La vendita a distanza di prodotti alcolici è vietata per legge (sott. 14 comma 2 art. 16 171-ФЗ), perciò per le sedi con paese «Russia» un ordine con un articolo alcolico non supera la validazione: nella risposta 400 arriva una riga con il nome di quell'articolo e la spiegazione che lo si può ordinare solo dal cameriere in sala. L'ordine va ricomposto senza alcolici.

Rilevamento machine-readable#

• https://cenaly.com/llms.txt — mappa sintetica dell'API per gli LLM;
• GET https://api.cenaly.com/llm/v1 — documento di discovery: elenco completo degli endpoint, esempi di ordine, prenotazione e uso del carrello, link ai metadati OAuth.