Guest API для AI-агентів

Публічний API cenaly.com, через який AI-асистенти та агенти діють від імені гостя: читають меню ресторану, шукають за каталогом, збирають кошик, оформлюють замовлення та бронюють столик. Для всього цього авторизація не потрібна — це ті самі операції, що доступні гостю на сайті меню.

Адресація ресторану#

Ресторан адресується кодом локації — це сегмент URL меню у верхньому регістрі. Якщо меню відкривається за cenaly.com/MYCAFE, код — MYCAFE. Той самий код зашитий у QR-коди столиків.

Швидкий старт (REST)#

# Що вміє API
curl https://api.cenaly.com/llm/v1

# Меню ресторану російською
curl "https://api.cenaly.com/llm/v1/locations/MYCAFE/menu?lang=ru"

# Оформити замовлення на виніс
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": "…"}

# Статус замовлення (orderId — секретний токен доступу)
curl https://api.cenaly.com/llm/v1/locations/MYCAFE/orders/{orderId}

Повна специфікація: OpenAPI 3.1 · інтерактивна документація (мова бренду; ?lang=en|ka|ru|tr|sq).

Ендпоінти#

Кошик: зібрати замовлення крок за кроком#

Агенту не обов'язково вгадувати склад замовлення одним пострілом — можна вести кошик на сервері, як це робить людина у веб-кошику:

1. POST /carts з першими рядками → cartId
2. PATCH /carts/{cartId} — додати, змінити кількість, прибрати (quantity: 0)
3. POST /orders з cartId — оформити

Ціни в кошику завжди перераховуються за живим меню, тож застарілу суму він показати не може. Кошик живе 7 днів. У кожній відповіді є checkoutUrl — посилання можна просто віддати людині, щоб вона завершила замовлення у звичайному чекауті.

Під час створення замовлення можна передати idempotencyKey (8–64 символи): повтор із тим самим ключем протягом 48 годин поверне початкове замовлення, а не створить друге. Те саме працює й для бронювань — повтор у тому самому вікні поверне початкове бронювання, а не займе другий стіл.

Підключення за MCP#

Сервер: https://api.cenaly.com/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Гостьові інструменти працюють без авторизації; вхід за OAuth додає до них інструменти вашого облікового запису.

Конфігурація для Claude Desktop / Claude Code і сумісних клієнтів:

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

Гостьові інструменти (13, без авторизації):

Типові сценарії:

• Швидке замовлення: get_menu → create_order → get_order_status (4-значний номер з'являється за пару секунд).
• Замовлення в діалозі: search_products → update_cart (по одному товару, як у розмові) → get_cart → create_order, або віддати гостю checkoutUrl і дати йому завершити замовлення самому.
• Питання про заклад: get_store_info (адреса, години, контакти) або search_policies_and_faqs (умови доставки, повернення, правила).
• Бронювання столика: check_table_availability (столики зі схеми залу, вільний/зайнятий на вибраний час) → create_reservation з tableId → get_reservation_status (ресторан підтверджує заявку) → за потреби cancel_reservation.

Доступ до своїх даних#

Якщо ви власник закладу або співробітник, до тих самих 13 гостьових інструментів додаються 12 інструментів роботи зі своїм обліковим записом — двома групами.

Дані облікового запису (6): resolve_domain, list_files, read_file, write_file, delete_file, write_signal. Вони відкривають не лише меню та замовлення, а й CRM, склад, персонал, налаштування каси й кухонного екрана, документи та майже всі інші розділи.

Клієнтський сайт локації (6): get_site_settings, update_site_settings, list_site_templates, apply_site_template, check_domain_availability, rename_site_domain.

Вхід — звичайний OAuth 2.1 під вашим обліковим записом cenaly.com: MCP-клієнт (Claude, ChatGPT, CLI) реєструється сам і відкриває вікно логіну. Нічого вставляти руками не потрібно.

• Метадані ресурсу: https://api.cenaly.com/.well-known/oauth-protected-resource
• Метадані сервера авторизації: https://api.cenaly.com/.well-known/oauth-authorization-server
• Динамічна реєстрація клієнта (RFC 7591): POST https://api.cenaly.com/llm/oauth/register

Поки токена немає, tools/list показує лише гостьові інструменти — авторизовані просто не видно.

Правила та гарантії#

• Замовлення валідується за живим меню: неіснуюча страва, варіант чи доп — помилка 400 зі списком проблем; ціни та підсумок рахує сервер, у агента немає способу «призначити» ціну.
• Для самовивозу та доставки обов'язкові ім'я і телефон гостя; для доставки — адреса.
• orderId / reservationId — секретні токени: за ними перевіряється статус і скасовується бронювання. Не публікуйте їх.
• Замовлення та бронювання потрапляють ресторану в реальному часі — в адмінку, на кухонний екран і в повідомлення, як звичайні замовлення із сайту.
• Бронювання гостя мають статус pending, поки ресторан не підтвердить їх в адмінці.
• У Росії алкоголь через агентський канал замовити не можна. Дистанційний продаж алкогольної продукції заборонений законом (пп. 14 п. 2 ст. 16 171-ФЗ), тому в локацій зі країною «Росія» замовлення з алкогольною позицією не проходить валідацію: у відповіді 400 приходить рядок із назвою цієї позиції та поясненням, що замовити її можна лише в офіціанта в залі. Замовлення потрібно перезібрати без алкоголю.

Машиночитане виявлення#

• https://cenaly.com/llms.txt — стисла карта API для LLM;
• GET https://api.cenaly.com/llm/v1 — discovery-документ: повний список ендпоінтів, приклади замовлення, бронювання та роботи з кошиком, посилання на OAuth-метадані.