Спецификация 03. Контракты API и событий

Статус: ревизия №2 по итогам аудита корпуса · 10.10.2026. Числовые факты сопровождаются ссылками; канонические перечисления — в «Модели данных», §0.

Наружная поверхность платформы: для витрин, агрегаторов, партнёров и внутренних фронтендов. Версия контрактов — v1. Формат — JSON; время — ISO 8601 (UTC); деньги — десятичные строки.

1. Поверхность REST (ресурсы)

Группа	Метод и путь	Назначение
Заказы	POST /v1/orders	создать заказ (любой канал)
Заказы	GET /v1/orders/{id}	состояние заказа
Заказы	POST /v1/orders/{id}/status	смена статуса (касса, кухня, курьер)
Меню	GET /v1/menu?location=	витрина меню (категории, модификаторы, цены канала, стоп-лист)
Меню	POST /v1/menu/stop-list	стоп-лист (распространяется во все каналы)
Оплаты	POST /v1/payments/intent	намерение оплаты (эквайринг/СБП)
Чеки	GET /v1/fiscal/receipts?order=	фискальные документы заказа
Гости	POST /v1/guests/identify	идентификация по телефону
Лояльность	GET /v1/guests/{id}/loyalty	баланс и история
Лояльность	POST /v1/loyalty/redeem	списание бонусов в чек
Доставка	POST /v1/delivery/quote	расчёт зоны, стоимости, обещания
Курьерам	GET /v1/courier/assignments	назначения смены
Курьерам	POST /v1/courier/assignments/{id}/status	статус вручения (с фото)
Склад	POST /v1/inventory/receive	приёмка (план/факт)
Склад	POST /v1/inventory/count	результаты инвентаризации
Отзывы	POST /v1/reviews	отзыв (привязка к заказу)
Франшиза	GET /v1/franchise/invoices?period=	счета роялти

2. Контракт создания заказа (единый для всех каналов)

{
  "location_id": "loc_01",
  "channel": "pos | site | app | miniapp | kiosk | phone | aggregator:yandex",
  "items": [
    {
      "menu_item_id": "mi_123",
      "qty": 2,
      "modifiers": ["mod_extra_cheese"],
      "comment_to_kitchen": "без лука"
    }
  ],
  "guest": { "phone": "+79000000000", "consent": true },
  "delivery": { "address": "...", "zone_id": "dz_3", "slot": "asap" },
  "idempotency_key": "5b6f..."
}

Ответ: 201 с order_id, promise_time, status_url. Ошибки: 409 стоп-лист, 422 вне зоны, 423 точка закрыта.

Канонические словари статусов (источник — ../components/12-data-model.md, §0):

• Order.status: new | accepted | kitchen | ready | served | packed | delivered | cancelled — используется в POST /v1/orders/{id}/status и событиях order.status_changed.
• KitchenTicket.status: queued | cooking | ready | served — события kitchen.ticket_status.
• DeliveryAssignment.status: assigned | picked_up | delivering | delivered | failed — POST /v1/courier/assignments/{id}/status принимает picked_up | delivering | delivered | failed с proof_photo и/или proof_code; события delivery.status_changed питают обещания времени и уведомления гостя.
• channel: pos | site | app | miniapp | kiosk | phone | aggregator:{name} (канал колл-центра phone равноправен в аналитике).

3. Каталог событий шины (наружу — вебхуки)

Событие	Полезная нагрузка (ключевое)	Типичные получатели
order.created / order.status_changed	статус, состав, обещание	витрины, агрегаторы, экраны
payment.completed	сумма, метод, чек-референс	финучёт, аналитика
fiscal.receipt_sent	фискальные реквизиты	ОФД-мониторинг, роялти
kitchen.ticket_status	станция, время, отклонение	дашборды УК
stock.movement	тип, количество, документ	остатки, фудкост
delivery.status_changed	курьер, статус, фото	уведомления гостя
review.created	оценка, привязки заказа	сервис-рекавери
audit.finished	балл, нарушения	кабинет УК
franchise.invoice_created	период, сумма	биллинг

Формат вебхука:

{
  "event": "order.status_changed",
  "tenant": "tn_7",
  "location": "loc_01",
  "object_id": "ord_42",
  "version": 12,
  "data": { "status": "ready", "at": "2026-10-10T18:30:00Z" }
}

4. Правила надёжности

1. Идемпотентность: все создающие запросы принимают idempotency_key; повтор с тем же ключом не создаёт дубль.
2. Доставка вебхуков — минимум-один-раз с подписью; получатель обязан быть идемпотентным (по object_id + version).
3. Оптимистичные версии: обновление ресурсов — по version (конфликт → 409).
4. Пагинация курсорами (?cursor=); списки заказов — только по тенанту и точке.
5. Авторизация: токены с областью видимости (тенант, точка, роль); устройство кассы — отдельный класс токенов с короткой жизнью.
6. Ошибки — структурированные: { "error": "code", "message": "...", "details": {...} }.

5. Ограничение доступа по ролям (пример)

Роль	Ресурсы
Касса точки	заказы (создание/статусы), оплаты, смены
Кухня	тикеты, стоп-лист
Управляющий	склад, инвентаризация, персонал точки, отчёты точки
Франчайзи	все свои точки, счета роялти, заявки в УК
УК	агрегаты сети, шаблоны, аудиты, биллинг