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

Публичный API cenaly.ru, через который AI-ассистенты и агенты действуют от имени гостя: читают меню ресторана, ищут по каталогу, собирают корзину, оформляют заказ и бронируют столик. Для всего этого авторизация не нужна — это те же операции, что доступны гостю на сайте меню.

Если войти под своим аккаунтом cenaly.ru (OAuth), к гостевым инструментам добавляются ещё двенадцать — уже к данным и настройкам вашего заведения. См. раздел «Доступ к своим данным» ниже.

Есть и отдельный MCP-сервер управления аккаунтом по API-ключам, с готовыми командами по меню, локациям и заказам: MCP Server Guide.

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

Ресторан адресуется кодом локации — это сегмент URL меню в верхнем регистре. Если меню открывается по cenaly.ru/MYCAFE, код — MYCAFE. Тот же код зашит в QR-коды столиков.

Быстрый старт (REST)#

# Что умеет API
curl https://api.cenaly.ru/llm/v1

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

# Оформить заказ навынос
curl -X POST https://api.cenaly.ru/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.ru/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.ru/llm/mcp — Model Context Protocol, streamable HTTP, stateless. Гостевые инструменты работают без авторизации; вход по OAuth добавляет к ним инструменты вашего аккаунта.

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

{
  "mcpServers": {
    "meni-guest": {
      "type": "http",
      "url": "https://api.cenaly.ru/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.ru: MCP-клиент (Claude, ChatGPT, CLI) регистрируется сам и открывает окно логина. Ничего вставлять руками не нужно.

Где это работает. Авторизованное плечо доступно на брендах, работающих в облаке AWS с общим аккаунтом (cenaly.ru, cenaly.com и другие) — сервером авторизации служит наш общий Cognito. В российском контуре (cenaly.ru) вход устроен иначе, и OAuth туда пока не подключён: там работают только гостевые инструменты.

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

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

Права ровно те же, что у вас в админке: владелец видит весь аккаунт, сотрудник — свою локацию и по своей роли. Файлы, которые продукт ведёт как журнал событий (профиль, снимок меню, карточки блюд), напрямую переписать нельзя — для них есть безопасный write_signal.

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

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

Машиночитаемое обнаружение#

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