Заказы и статусы

Создание заказа

POST /api/v1/orders требует orders:write. Передавайте уникальный external_id — постоянный идентификатор заказа в вашей системе. MenuLab автоматически связывает заказ с API-клиентом; поле api_client_id передавать нельзя.

Успешный ответ содержит MenuLab ID заказа в data.id. Храните пару:

external_id ↔ MenuLab order_id

Подтверждение онлайн-оплаты

Передавайте оплату только после окончательного подтверждения провайдером:

curl -X POST "https://restaurant.example/api/v1/orders/3812/mark-paid" \
  -H "X-API-Key: $MENULAB_API_KEY" \
  -H "X-API-Secret: $MENULAB_API_SECRET" \
  -H "X-Idempotency-Key: site-order-100-paid" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "2fbb8f0e-000f-5000-8000-18db351245c7",
    "payment_provider": "yookassa",
    "payment_method": "online",
    "amount": 45.00
  }'

payment_id однозначно определяет операцию у эквайера. Не меняйте его при повторе. Успешный ответ содержит payment_status: "paid".

Чтение состояния

• GET /api/v1/orders/{id} — полный заказ по MenuLab ID;
• GET /api/v1/orders?external_id=... — поиск полного заказа, ответ пагинирован;
• GET /api/v1/orders/status?external_id=... — компактный статус для fallback polling.

Если одинаковый external_id теоретически встречается у разных источников, всегда передавайте source.

Основные статусы заказа

Статус	Значение
pending	Ожидает принятия
accepted	Принят рестораном
preparing	Готовится
ready	Готов к выдаче или передаче
completed	Завершён
cancelled	Отменён

Список может расширяться. Терминальные состояния — completed и cancelled; интеграция не должна пытаться отменить уже завершённый заказ.

Статусы платежа

pending означает, что MenuLab не получила подтверждения оплаты; paid — оплата подтверждена; refunded — внешний возврат успешно подтверждён в MenuLab.