Как устроен Public API

Что можно подключить

MenuLab Public API v1 предназначен для server-to-server интеграций: сайтов ресторанов, мобильных приложений, агрегаторов и внешних CRM. Через API интеграция может получить меню, создать и прочитать заказ, передать онлайн-оплату, отменить заказ и синхронизировать возврат.

Базовый URL примеров:

https://<домен-ресторана>/api/v1

Как распределена ответственность

Система	За что отвечает
Внешняя интеграция	Создаёт заказ, хранит свой external_id, принимает принадлежащую ей онлайн-оплату и вызывает API эквайера для возврата
MenuLab	Ведёт заказ, производство, выдачу, бонусы, кассовые/POS-возвраты и состояние платежа в учёте
Webhook	Оперативно сообщает внешней системе об изменениях заказа и запросах возврата

Если онлайн-платёж принят интеграцией через YooKassa или другого провайдера, MenuLab не обращается к этому провайдеру напрямую. При отмене MenuLab создаёт запрос возврата, интеграция возвращает деньги и подтверждает результат в Public API.

Источник отмены не влияет на контракт: заказ можно отменить через API или в POS MenuLab. В обоих случаях владелец внешнего платежа получает payment.refund.requested.

Для наличных, карты курьеру и терминала возврат выполняется в кассе/POS, а создавший заказ API-клиент получает ту же цепочку событий только для синхронизации. Поля payment_owner: menulab_pos и action_required: false запрещают повторно обращаться к YooKassa.

Рекомендуемая последовательность

1. Создайте в MenuLab API-клиента подходящего типа.
2. Сохраните API key, API secret и webhook secret на backend.
3. Настройте HTTPS webhook URL.
4. Создавайте заказы с уникальным external_id.
5. Передавайте подтверждённую онлайн-оплату через mark-paid.
6. Обрабатывайте события заказов и возвратов.
7. Перед production пройдите приёмочный тест целиком.

Версионирование

Версия включена в URL (/api/v1). Интеграция не должна строить логику на неизвестных полях ответа: MenuLab может добавлять новые необязательные поля без изменения версии. Удаление поля или изменение его смысла требует отдельного совместимого перехода.