Guest API dla agentów AI

Publiczne API cenaly.com, przez które asystenci i agenci AI działają w imieniu gościa: czytają menu restauracji, wyszukują w katalogu, kompletują koszyk, składają zamówienie i rezerwują stolik. Do tego wszystkiego autoryzacja nie jest potrzebna — to te same operacje, które są dostępne dla gościa na stronie menu.

Adresowanie restauracji#

Restauracja jest adresowana kodem lokalizacji — to segment URL menu zapisany wielkimi literami. Jeśli menu otwiera się pod cenaly.com/MYCAFE, kod to MYCAFE. Ten sam kod jest zaszyty w kodach QR stolików.

Szybki start (REST)#

# Co potrafi API
curl https://api.cenaly.com/llm/v1

# Menu restauracji po rosyjsku
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Złożyć zamówienie na wynos
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 zamówienia (orderId — tajny token dostępu)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Pełna specyfikacja: OpenAPI 3.1 · dokumentacja interaktywna (w języku marki; ?lang=en|ka|ru|tr|sq).

Endpointy#

Koszyk: złożyć zamówienie krok po kroku#

Agent nie musi zgadywać składu zamówienia jednym strzałem — może prowadzić koszyk na serwerze, tak jak robi to człowiek w koszyku w przeglądarce:

1. POST /carts z pierwszymi pozycjami → cartId
2. PATCH /carts/{cartId} — dodać, zmienić ilość, usunąć (quantity: 0)
3. POST /orders z cartId — złożyć

Ceny w koszyku są zawsze przeliczane według aktualnego menu, więc nie może pokazać nieaktualnej kwoty. Koszyk żyje 7 dni. W każdej odpowiedzi jest checkoutUrl — link można po prostu przekazać człowiekowi, żeby dokończył zamówienie w zwykłym checkoutcie.

Przy tworzeniu zamówienia można przekazać idempotencyKey (8–64 znaki): powtórzenie z tym samym kluczem w ciągu 48 godzin zwróci pierwotne zamówienie, a nie utworzy drugiego. To samo działa dla rezerwacji — powtórzenie w tym samym oknie zwróci pierwotną rezerwację, a nie zajmie drugiego stolika.

Połączenie przez MCP#

Serwer: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Narzędzia gościa działają bez autoryzacji; logowanie przez OAuth dodaje do nich narzędzia Twojego konta.

Konfiguracja dla Claude Desktop / Claude Code i zgodnych klientów:

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

Narzędzia gościa (13, bez autoryzacji):

Typowe scenariusze:

• Szybkie zamówienie: get_menu → create_order → get_order_status (4-cyfrowy numer pojawia się po kilku sekundach).
• Zamówienie w dialogu: search_products → update_cart (po jednym przedmiocie, jak w rozmowie) → get_cart → create_order, albo przekazać gościowi checkoutUrl i pozwolić mu dokończyć zamówienie samemu.
• Pytanie o lokal: get_store_info (adres, godziny, kontakty) lub search_policies_and_faqs (warunki dostawy, zwrot, zasady).
• Rezerwacja stolika: check_table_availability (stoliki ze schematu sali, wolny/zajęty na wybrany czas) → create_reservation z tableId → get_reservation_status (restauracja potwierdza zgłoszenie) → w razie potrzeby cancel_reservation.

Dostęp do własnych danych#

Jeśli jesteś właścicielem lokalu lub pracownikiem, do tych samych 13 narzędzi gościnnych dochodzi 12 narzędzi pracy z własnym kontem — w dwóch grupach.

Dane konta (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Otwierają nie tylko menu i zamówienia, ale też CRM, magazyn, personel, ustawienia kasy i ekranu kuchennego, dokumenty oraz niemal wszystkie pozostałe sekcje.

Strona klienta placówki (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

Logowanie — zwykły OAuth 2.1 na Twoim koncie cenaly.com: klient MCP (Claude, ChatGPT, CLI) rejestruje się sam i otwiera okno logowania. Niczego nie trzeba wklejać ręcznie.

• Metadane zasobu: https://api.cenaly.com/.well-known/oauth-protected-resource
• Metadane serwera autoryzacji: https://api.cenaly.com/.well-known/oauth-authorization-server
• Dynamiczna rejestracja klienta (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Dopóki nie ma tokenu, tools/list pokazuje tylko narzędzia gościnne — autoryzowane po prostu nie są widoczne.

Zasady i gwarancje#

• Zamówienie jest walidowane na żywym menu: nieistniejące danie, wariant lub dodatek — błąd 400 z listą problemów; ceny i podsumowanie liczy serwer, agent nie ma sposobu, by „ustalić” cenę.
• Dla odbioru osobistego i dostawy obowiązkowe są imię i telefon gościa; dla dostawy — adres.
• orderId / reservationId — tajne tokeny: na ich podstawie sprawdza się status i anuluje rezerwację. Nie publikuj ich.
• Zamówienia i rezerwacje trafiają do restauracji w czasie rzeczywistym — do panelu administracyjnego, na ekran kuchenny i do powiadomień, jak zwykłe zamówienia ze strony.
• Rezerwacje gościa mają status pending, dopóki restauracja nie potwierdzi ich w panelu administracyjnym.
• W Rosji alkoholu nie można zamówić kanałem agentowym. Zdalna sprzedaż wyrobów alkoholowych jest zabroniona przez prawo (pp. 14 p. 2 art. 16 171-FZ), dlatego w placówkach z krajem „Rosja” zamówienie z pozycją alkoholową nie przechodzi walidacji: w odpowiedzi 400 przychodzi wiersz z nazwą tej pozycji i wyjaśnieniem, że można ją zamówić tylko u kelnera na sali. Zamówienie trzeba złożyć ponownie bez alkoholu.

Wykrywanie maszynowe#

• https://cenaly.com/llms.txt — skrócona mapa API dla LLM;
• GET https://api.cenaly.com/llm/v1 — dokument discovery: pełna lista endpointów, przykłady zamówienia, rezerwacji i pracy z koszykiem, linki do metadanych OAuth.