Создать приложение
Приложения расширяют аккаунт ресторана через ограниченный, отзываемый OAuth-доступ. Ваш код работает на ваших серверах; платформа держит реестр, журнал установок и платёжные механизмы. Это руководство проведёт вас от нуля до установленного приложения с учётом использования.
1. Зарегистрируйте своё приложение
Создайте приложение в панели партнёра: название, категория, нужные вам области, необязательный webhook URL и модель оплаты. Отправка создаёт OAuth-клиент (client id + секрет) и отправляет приложение на проверку. После одобрения админом оно появляется в App Store и может быть установлено.
2. Установитесь
Владелец ресторана устанавливает ваше приложение со страницы его карточки в App Store, предоставляя запрошенные вами области. Установка создаёт AppInstallation и (для платных приложений) списывает первый период через их кошелёк.
3. Вызовите API
Обменяйте OAuth-токен для устанавливающего аккаунта, затем вызовите REST API с ним. Сообщайте об использовании, получайте webhooks или встраивайте страницу в их панель — рассмотрено ниже.
OAuth и токены
Приложения аутентифицируются через OAuth 2.0 (Laravel Passport). Ваши учётные данные клиента берутся из панели партнёра. Используйте стандартный поток authorization-code; выданный токен несёт области, одобренные владельцем при установке.
# Exchange an authorization code for an access token
curl -X POST https://www.menubarcode.comoauth/token \
-d grant_type=authorization_code \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET \
-d redirect_uri=YOUR_REDIRECT \
-d code=AUTH_CODE
# Call the API with the returned bearer token
curl https://www.menubarcode.com/api/v1/restaurants \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json"Токены ограничены: вызов, требующий orders:read не проходит, если владелец не предоставил это. Запрашивайте минимальный набор — проверяющие это контролируют.
Сессионные токены
Для кратковременных вызовов сервер-встраивание создайте сессионный токен из активной установки. Токены истекают через 60 секунд.
GET https://www.menubarcode.comapps/{appId}/session-token
# → { "token": "…", "expires_in": 60 }Встроенные приложения
Если ваше приложение объявляет embed_url, платформа размещает его в iframe внутри панели владельца по адресу /apps/{appId}/embed. Совместите его с сессионным токеном (выше), чтобы аутентифицировать встроенную страницу без полного цикла OAuth.
Вебхуки
Подпишитесь на события в webhook_url. Доставки ставятся в очередь, повторяются и подписываются по схеме Standard Webhooks с использованием секрета подписи вашего приложения. Ваша конечная точка должна быть публичным HTTPS URL (без приватных/loopback/metadata хостов) и возвращать 2xx быстро.
# A delivery your endpoint receives
POST https://your-app.com/webhooks
webhook-id: msg_...
webhook-timestamp: 1710000000
webhook-signature: v1,BASE64_HMAC
Content-Type: application/json
{ "type": "order.paid", "data": { "order_id": 123, ... } }Проверяйте подпись по вашему секрету, прежде чем доверять payload. См. список событий.
Оплата по использованию
Приложения с оплатой по использованию учитывают потребление, сообщая единицы. Каждый отчёт списывается с кошелька владельца по вашей цене за единицу. Передавайте уникальный ref чтобы сделать отчёт идемпотентным (повтор с тем же ref игнорируется).
curl -X POST https://www.menubarcode.com/api/app/usage \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
-d quantity=1 \
-d ref=unique-key-per-event| Поле | Тип | Заметки |
|---|---|---|
quantity | число > 0 | обязательно — потреблённые единицы |
ref | строка ≤ 120 | необязательный ключ идемпотентности |
Конечная точка возвращает 403 если токен не принадлежит зарегистрированному приложению или приложение не установлено для аккаунта.
Практические руководства
Выберите тип оплаты
- Бесплатно — без списания при установке.
- Периодический — фиксированная цена, списываемая каждый расчётный период (по умолчанию 30 дней) с кошелька владельца.
- По использованию — цена за единицу, списываемая по мере того, как вы сообщаете об использовании.
Запрашивайте области ответственно
Запрашивайте только те области, которые использует ваше приложение. Изменение областей у активной карточки отправляет приложение на повторную проверку. См. справочник областей.
Очищайте при удалении
Когда владелец удаляет приложение, платформа отзывает его токены и вызывает app/uninstalled событие. Остановите фоновую работу и удалите сохранённые данные этого аккаунта, когда получите его.
справочник областей
Отражено из реестра областей OAuth платформы.
| Область действия | Права |
|---|---|
menu:read | Read menus, categories and items |
menu:write | Create and update menu items |
orders:read | Read orders and their status |
orders:write | Create and update orders |
analytics:read | Read scan and sales analytics |
restaurant:read | Read restaurant profile and settings |
События webhook
События, на которые вы можете подписаться сегодня:
| Событие |
|---|
order.created |
order.status_changed |
order.paid |
refund.completed |
reservation.created |
reservation.cancelled |
customer.created |
shift.opened |
shift.closed |
menu.updated |
entitlement.changed |
subscription.paused |
subscription.resumed |
subscription.renewed |
subscription.expired |
subscription.plan_changed |
subscription.past_due |
subscription.expiring |
subscription.trial_ending |
app.uninstalled |
Требования к карточке и проверке
Прежде чем админ одобрит ваше приложение, оно должно:
- Запрашивать только используемые области, каждая обоснована в описании.
- Предоставлять рабочую конечную точку webhook (публичный HTTPS), если оно подписывается на события.
- Указывать точные цены — таблица цен на странице сведений генерируется из них.
- Включать чёткий слоган, описание, категорию и хотя бы один скриншот.
- Корректно обрабатывать удаление (отзыв доступа, остановка оплаты, удаление данных аккаунта).
Правки метаданных (слоган, описание, скриншоты, ссылки) публикуются сразу; изменения цены или областей отправляют на повторную проверку.
