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-FZ), затова при обектите със страна „Русия“ поръчка с алкохолна позиция не минава валидация: в отговора 400 идва ред с името на тази позиция и пояснение, че тя може да се поръча само от сервитьор в залата. Поръчката трябва да се събере отново без алкохол.

Машиночитаемо откриване#

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