Guest API za AI agente

Javni API cenaly.com, preko kojeg AI asistenti i agenti deluju u ime gosta: čitaju meni restorana, pretražuju katalog, sastavljaju korpu, kreiraju porudžbinu i rezervišu sto. Za sve to autorizacija nije potrebna — to su iste operacije koje su dostupne gostu na sajtu menija.

Adresiranje restorana#

Restoran se adresira kodom lokacije — to je segment URL-a menija velikim slovima. Ako se meni otvara na cenaly.com/MYCAFE, kod je MYCAFE. Isti kod je ugrađen u QR kodove stolova.

Brzi start (REST)#

# Šta API ume
curl https://api.cenaly.com/llm/v1

# Cenaly restorana na ruskom
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Kreiraj porudžbinu za poneti
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 porudžbine (orderId — tajni pristupni token)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Puna specifikacija: OpenAPI 3.1 · interaktivna dokumentacija (na jeziku brenda; ?lang=en|ka|ru|tr|sq).

Endpointi#

Korpa: sastavi porudžbinu korak po korak#

Agent ne mora da pogodi sastav porudžbine iz jednog pokušaja — može da vodi korpu na serveru, kao što to čovek radi u veb-korpi:

1. POST /carts sa prvim stavkama → cartId
2. PATCH /carts/{cartId} — dodaj, izmeni količinu, ukloni (quantity: 0)
3. POST /orders sa cartId — kreiraj

Cene u korpi se uvek preračunavaju po živom meniju, tako da ne može da prikaže zastareo iznos. Korpa živi 7 dana. U svakom odgovoru postoji checkoutUrl — link možete jednostavno dati čoveku da završi porudžbinu u običnom checkout-u.

Pri kreiranju porudžbine može se proslediti idempotencyKey (8–64 znaka): ponavljanje sa istim ključem u roku od 48 sati vratiće izvornu porudžbinu, a ne kreirati drugu. Isto važi i za rezervacije — ponavljanje u istom okviru vratiće izvornu rezervaciju, a ne zauzeti drugi sto.

Povezivanje preko MCP#

Server: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Gostujući alati rade bez autorizacije; prijava preko OAuth dodaje im alate vašeg naloga.

Konfiguracija za Claude Desktop / Claude Code i kompatibilne klijente:

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

Gostujući alati (13, bez autorizacije):

Tipični scenariji:

• Brza porudžbina: get_menu → create_order → get_order_status (četvorocifreni broj se pojavljuje za par sekundi).
• Porudžbina u dijalogu: search_products → update_cart (stavku po stavku, kao u razgovoru) → get_cart → create_order, ili dati gostu checkoutUrl i pustiti ga da sam završi porudžbinu.
• Pitanje o objektu: get_store_info (adresa, radno vreme, kontakti) ili search_policies_and_faqs (uslovi dostave, povraćaj, pravila).
• Rezervacija stola: check_table_availability (stolovi sa šeme sale, slobodan/zauzet za izabrano vreme) → create_reservation sa tableId → get_reservation_status (restoran potvrđuje zahtev) → po potrebi cancel_reservation.

Pristup svojim podacima#

Ako ste vlasnik lokala ili zaposleni, na istih 13 gostujućih alata dodaje se 12 alata za rad sa svojim nalogom — u dve grupe.

Podaci naloga (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Oni otvaraju ne samo meni i porudžbine, već i CRM, magacin, osoblje, podešavanja kase i kuhinjskog ekrana, dokumente i skoro sve ostale sekcije.

Klijentski sajt lokacije (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

Prijava — običan OAuth 2.1 pod vašim nalogom cenaly.com: MCP klijent (Claude, ChatGPT, CLI) registruje se sam i otvara prozor za prijavu. Ništa ne treba ručno da se unosi.

• Metapodaci resursa: https://api.cenaly.com/.well-known/oauth-protected-resource
• Metapodaci servera za autorizaciju: https://api.cenaly.com/.well-known/oauth-authorization-server
• Dinamička registracija klijenta (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Dok nema tokena, tools/list prikazuje samo gostujuće alate — autorizovani prosto nisu vidljivi.

Pravila i garancije#

• Porudžbina se validira prema živom meniju: nepostojeće jelo, varijanta ili dodatak — greška 400 sa spiskom problema; cene i ukupan iznos računa server, agent nema način da „odredi“ cenu.
• Za preuzimanje i dostavu obavezni su ime i telefon gosta; za dostavu — adresa.
• orderId / reservationId — tajni tokeni: preko njih se proverava status i otkazuje rezervacija. Ne objavljujte ih.
• Porudžbine i rezervacije stižu restoranu u realnom vremenu — u admin panel, na kuhinjski ekran i u obaveštenja, kao obične porudžbine sa sajta.
• Gostujuće rezervacije imaju status pending dok ih restoran ne potvrdi u admin panelu.
• U Rusiji alkohol preko agentskog kanala poručivanja nije moguć. Distantna prodaja alkoholnih proizvoda zabranjena je zakonom (pp. 14 p. 2 st. 16 171-FZ), pa kod lokacija sa zemljom „Rusija“ porudžbina sa alkoholnom stavkom ne prolazi validaciju: u odgovoru 400 stiže red sa nazivom te stavke i objašnjenjem da se ona može poručiti samo kod konobara u sali. Porudžbinu treba ponovo sastaviti bez alkohola.

Mašinski čitljivo otkrivanje#

• https://cenaly.com/llms.txt — kratka mapa API-ja za LLM;
• GET https://api.cenaly.com/llm/v1 — discovery dokument: pun spisak endpointa, primeri porudžbine, rezervacije i rada sa korpom, linkovi na OAuth metapodatke.