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-метаподатоците.