Guest API voor AI-agenten

De publieke API van cenaly.com, waarmee AI-assistenten en agenten namens de gast handelen: ze lezen het menu van een restaurant, zoeken in de catalogus, vullen een winkelmandje, plaatsen een Bestelling en Reserveren een Tafel. Voor dit alles is geen autorisatie nodig — het zijn dezelfde handelingen die een gast op de menusite kan uitvoeren.

Adressering van het restaurant#

Een restaurant wordt geadresseerd met de locatiecode — dat is het URL-segment van het menu in hoofdletters. Als het menu opent via cenaly.com/MYCAFE, is de code MYCAFE. Dezelfde code zit ook in de QR-codes van de Tafels.

Snel starten (REST)#

# Wat de API kan
curl https://api.cenaly.com/llm/v1

# Menu van het restaurant in het Russisch
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Een Bestelling voor afhalen plaatsen
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 van de Bestelling (orderId — een geheime toegangstoken)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Volledige specificatie: OpenAPI 3.1 · interactieve documentatie (in de taal van het merk; ?lang=en|ka|ru|tr|sq).

Endpoints#

Winkelmandje: een Bestelling stap voor stap samenstellen#

Een agent hoeft de samenstelling van de Bestelling niet in één keer te raden — het winkelmandje kan op de server worden bijgehouden, zoals een mens dat in het webwinkelmandje doet:

1. POST /carts met de eerste regels → cartId
2. PATCH /carts/{cartId} — toevoegen, aantal wijzigen, verwijderen (quantity: 0)
3. POST /orders met cartId — plaatsen

Prijzen in het winkelmandje worden altijd opnieuw berekend op basis van het actuele menu, dus een verouderd bedrag kan het niet tonen. Het winkelmandje blijft 7 dagen bestaan. In elk antwoord staat checkoutUrl — u kunt de link gewoon aan een persoon geven, zodat die de Bestelling in de gewone checkout afrondt.

Bij het aanmaken van een Bestelling kunt u idempotencyKey meegeven (8–64 tekens): een herhaling met dezelfde sleutel binnen 48 uur geeft de oorspronkelijke Bestelling terug in plaats van een tweede aan te maken. Hetzelfde werkt voor Reserveringen — een herhaling in hetzelfde venster geeft de oorspronkelijke Reservering terug in plaats van een tweede Tafel te bezetten.

Verbinden via MCP#

Server: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. De gasttools werken zonder autorisatie; inloggen via OAuth voegt de tools van uw Account toe.

Configuratie voor Claude Desktop / Claude Code en compatibele clients:

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

Gasttools (13, zonder autorisatie):

Typische scenario's:

• Snel bestellen: get_menu → create_order → get_order_status (het Nummer van 4 cijfers verschijnt na een paar seconden).
• Bestellen in een gesprek: search_products → update_cart (Artikel voor Artikel, zoals in een gesprek) → get_cart → create_order, of geef de gast checkoutUrl en laat hem de Bestelling zelf afronden.
• Vraag over de Vestiging: get_store_info (adres, openingstijden, contactgegevens) of search_policies_and_faqs (bezorgvoorwaarden, retournering, regels).
• Tafelreservering: check_table_availability (Tafels van de zaalplattegrond, vrij/bezet op het gekozen tijdstip) → create_reservation met tableId → get_reservation_status (het restaurant bevestigt de aanvraag) → indien nodig cancel_reservation.

Toegang tot uw eigen gegevens#

Als u eigenaar van een vestiging of medewerker bent, komen bij dezelfde 13 gasttools 12 tools voor het werken met uw eigen account — in twee groepen.

Accountgegevens (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Ze ontsluiten niet alleen het menu en bestellingen, maar ook CRM, voorraad, personeel, instellingen van de kassa en het keukenscherm, documenten en bijna alle andere secties.

Klantsite van de vestiging (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

Inloggen gaat via gewone OAuth 2.1 onder uw cenaly.com-account: de MCP-client (Claude, ChatGPT, CLI) registreert zichzelf en opent een loginvenster. U hoeft niets handmatig te plakken.

• Metadata van de resource: https://api.cenaly.com/.well-known/oauth-protected-resource
• Metadata van de autorisatieserver: https://api.cenaly.com/.well-known/oauth-authorization-server
• Dynamische clientregistratie (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Zolang er geen token is, toont tools/list alleen de gasttools — de geautoriseerde tools zijn eenvoudigweg niet zichtbaar.

Regels en garanties#

• De bestelling wordt gevalideerd tegen het live menu: een niet-bestaand gerecht, variant of extra is een fout 400 met een lijst van problemen; prijzen en het totaal worden door de server berekend, de agent heeft geen manier om een prijs te „bepalen”.
• Voor afhalen en bezorging zijn de naam en het telefoonnummer van de gast verplicht; voor bezorging — het adres.
• orderId / reservationId — geheime tokens: daarmee wordt de status gecontroleerd en een reservering geannuleerd. Publiceer ze niet.
• Bestellingen en reserveringen komen in realtime bij het restaurant binnen — in de admin, op het keukenscherm en in de meldingen, net als gewone bestellingen via de site.
• Reserveringen van gasten hebben de status pending totdat het restaurant ze in de admin bevestigt.
• In Rusland kan alcohol niet via het agentkanaal worden besteld. Verkoop op afstand van alcoholhoudende producten is bij wet verboden (pp. 14 p. 2 art. 16 171-ФЗ), daarom slaagt bij vestigingen met het land „Rusland” een bestelling met een alcoholartikel niet door de validatie: in het antwoord 400 komt een regel met de naam van dat artikel en de uitleg dat u het alleen bij een ober in de zaal kunt bestellen. De bestelling moet opnieuw worden samengesteld zonder alcohol.

Machineleesbare detectie#

• https://cenaly.com/llms.txt — beknopte API-kaart voor LLM's;
• GET https://api.cenaly.com/llm/v1 — discovery-document: volledige lijst van endpoints, voorbeelden van een bestelling, reservering en werken met de winkelmand, links naar OAuth-metadata.