Документация для разработчиков

Начало работы

Создайте API-токен в панели управления в разделе API-токены и Webhook. Выберите read и/или write права и скопируйте токен — он показывается только один раз.

Быстрая проверка, что ваш токен работает:

curl https://www.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer YOUR_TOKEN"

Аутентификация

Отправляйте токен как заголовок Bearer в каждом запросе:

Authorization: Bearer YOUR_TOKEN

Для быстрых тестов вы можете вместо этого передавать ?api_token=YOUR_TOKEN как параметр запроса, но заголовок настоятельно предпочтительнее, чтобы токены не попадали в логи.

Ограниченные токены

Помимо грубых read/write, токен можно ограничить конкретными ресурсами с помощью resource:action прав. Ресурсы: restaurants, menu, orders, customers, analytics, drivers, webhooks; Действия read, write. Выберите их при создании токена в панели управления.

Правила охвата: * даёт всё; область :write также даёт своё :read; грубые read/write ведут себя как *:read / *:write. Запрос без необходимой области возвращает 403. Устаревшие read/write токены не затрагиваются.

Токены хранятся в хешированном виде (SHA-256) и могут иметь необязательный срок действия. Отзывайте любой токен мгновенно из панели управления.

Ограничения частоты

API допускает 120 запросов в минуту на токен. При превышении возвращается 429 Too Many Requests с Retry-After заголовком. Стандартные заголовки лимита частоты включаются в каждый ответ:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118

Ошибки

Каждая ошибка на /api/v1 маршруте возвращает стандартные HTTP-коды статуса и единый JSON-конверт — понятное человеку message, стабильное машинное code, и (при валидации) по полям errors Карта

{ "message": "Invalid or expired token.", "code": "unauthenticated" }

{ "message": "The given data was invalid.",
  "code": "validation_failed",
  "errors": { "title": ["The title field is required."] } }

Пагинация

Конечные точки-списки возвращают конверты с пагинацией в стиле Laravel. Используйте ?page= параметр запроса для перехода по страницам.

{
  "data": [ ... ],
  "current_page": 1,
  "last_page": 3,
  "per_page": 20,
  "total": 47
}

Чтение ресторанов и меню

Список ресторанов, принадлежащих токену, с пагинацией (20 на страницу).

{
  "data": [
    { "id": 12, "title": "Nova Bistro", "slug": "nova-bistro",
      "url": "https://.../nova-bistro", "template": "linen",
      "created_at": "2026-06-01T10:22:00+00:00" }
  ],
  "current_page": 1, "last_page": 1, "total": 1
}

Один ресторан с его категориями меню и числом позиций.

Полное активное меню, сгруппированное по категориям.

[
  { "id": 3, "name": "Starters",
    "items": [
      { "id": 88, "name": "Bruschetta", "price": 6.50,
        "is_sold_out": false, "is_popular": true, "is_vegan": true,
        "is_halal": true, "calories": 210 }
    ]
  }
]

Управление меню Написать

Полный CRUD для категорий и позиций — всё, что нужно приложению мерчанта для управления меню. Все конечные точки записи требуют write токен и ограничены рестораном, которым вы владеете. Загрузка изображений вне области JSON; передавайте уже размещённый URL в image.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/menu/items \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "category_id": 3, "name": "Margherita", "price": 11.00,
    "description": "San Marzano, mozzarella, basil",
    "is_vegan": true, "is_halal": true, "calories": 850
  }'

Быстрый переключатель «86». Отправьте {"is_sold_out": true}, или опустите тело, чтобы переключить.

Заказы

Заказы, сначала новые, с пагинацией (30/страница). Фильтруйте через ?status=.

Полная информация о заказе с позициями, опциями, курьером и хронологией доставки.

Создать заказ — вот как приложение для клиента отправляет корзину (токен хранится на бэкенде мерчанта). Каждая позиция проверяется по актуальному меню ресторана; распроданные или чужие позиции отклоняют весь заказ (422). Срабатывает order.created и возвращает полный заказ, включая его track_token.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/orders \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "delivery",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "address": "9 Cedar Road",
    "tip_amount": 3.00,
    "note": "Ring the bell",
    "source": "customer_app",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12], "note": "no onion" },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Заказ type является одним из on-table, takeaway, delivery. для on-table передайте table_number; для delivery передайте address.

Идемпотентность. Отправьте Idempotency-Key заголовок (или тело client_uuid) при любом вызове создания заказа. Повтор с тем же ключом возвращает исходный заказ и никогда не создаёт дубликат — безопасно при потерянных ответах и офлайн-повторах. Ключи ограничены рамками ресторана.

Обновить статус кухни (new|preparing|ready|delivered|completed|cancelled). Срабатывает order.status_changed.

Storefront API (токен на ресторан)

Отдельный публичный API, аутентифицируемый через токен витрины на ресторан отправляемый как X-Storefront-Token (не Bearer-токен владельца). Выпускайте их из панели управления; каждый токен всегда может достичь только своего ресторана. Область чтения — menu:read; для оформления заказов нужна область order:write Область действия

Полное меню ресторана токена (варианты, опции, группы, галерея).

Базовая информация о ресторане токена.

Отправить корзину от имени гостя. Ценообразование на сервере и не оплачен (гость платит при получении); takeaway или on-table только. Каждая позиция проверяется по актуальному меню — распроданные или чужие позиции отклоняют весь заказ (422). Лимиты: 40 позиций/заказ, 30 шт./строка. Необязательно coupon_code применяет скидку владельца на стороне сервера. Срабатывает order.created и возвращает track_token + continue_url.

curl -X POST https://www.menubarcode.com/api/v1/storefront/orders \
  -H "X-Storefront-Token: YOUR_STOREFRONT_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "takeaway",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "coupon_code": "WELCOME10",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12] },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Аналитика и клиенты

Сводка продаж за период (?from=YYYY-MM-DD&to=YYYY-MM-DD, по умолчанию последние 30 дней): число заказов по статусу/типу, валовая и оплаченная выручка, средний чек и топ позиций.

{
  "range": { "from": "2026-06-02", "to": "2026-07-02" },
  "orders": { "total": 214, "paid": 198, "by_status": {...}, "by_type": {...} },
  "revenue": { "gross": 8420.50, "paid": 7990.00, "avg_order_value": 39.35 },
  "top_items": [ { "item_id": 88, "name": "Margherita", "quantity": 143 } ]
}

Список клиентов ресторана (CRM), с пагинацией. Фильтруйте через ?search=.

Управление курьерами Написать

Курьеры принадлежат вам и (необязательно) одному ресторану. Создание или ротация курьера возвращает необработанный токен курьера ровно один раз — передайте его приложению курьера; они аутентифицируются с ним (см. ниже).

curl -X POST https://www.menubarcode.com/api/v1/drivers \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Alex","phone":"+15550001111","restaurant_id":12}'

# → { "id": 7, "name": "Alex", ..., "token": "RAW_DRIVER_TOKEN_SHOWN_ONCE" }

Аннулирует старый токен и возвращает новый.

Назначить и отслеживать доставку

Заказы на доставку, фильтруемые по ?delivery_status= и ?driver_id=.

Назначить курьера {"driver_id": 7}. Задаёт delivery_status=assigned и срабатывает order.driver_assigned.

Переопределить этап доставки: pending | assigned | picked_up | out_for_delivery | delivered | failed.

API приложения для водителей

Приложение курьера аутентифицируется через Токен водителя (не токен владельца), выпущенный выше. Базовый путь https://www.menubarcode.com/api/v1/driver. Каждый ответ ограничен этим одним курьером.

Authorization: Bearer RAW_DRIVER_TOKEN

Профиль аутентифицированного курьера.

Заказы, назначенные этому курьеру. Добавьте ?active=1 чтобы скрыть доставленные/неудачные.

Продвинуть доставку: {"delivery_status":"out_for_delivery"} затем "delivered" или "picked_up" / "failed", необязательно note). Срабатывают те же webhooks, что и у конечной точки владельца.

Отправить текущую позицию: {"lat":25.2048,"lng":55.2708}. Показывается в отслеживании клиента, пока заказ в пути.

Аккаунты клиентов

A автономное приложение для клиента аутентифицирует своих пользователей токеном на клиента (в стиле Sanctum: несколько устройств, отзываемых по отдельности). Токен владельца не задействован. Клиенты ограничены рамками ресторана, поэтому авторизация находится под /restaurants/{id}/customer/…. Сначала просмотрите меню через публичную конечную точку:

Активное меню, сгруппированное по категориям (распроданные позиции опущены). Без авторизации.

Регистрация / вход

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/login \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","password":"secret123","device":"iPhone 15"}'

# → { "token": "RAW_CUSTOMER_TOKEN", "customer": { "id": 42, "name": "Sam", ... } }

Без пароля (SMS OTP)

Запросите код для номера телефона, затем подтвердите его. Verify находит или создаёт клиента и возвращает токен. Конечные точки авторизации имеют лимит частоты (вход/регистрация 10/мин, запрос OTP 6/мин).

API приложения для клиентов

Аутентифицируйтесь токеном клиента. Базовый путь https://www.menubarcode.com/api/v1/customer. Всё ограничено аутентифицированным клиентом — тело заказа никогда не может подделать id другого клиента.

Authorization: Bearer RAW_CUSTOMER_TOKEN

Чтение / обновление профиля (имя, email, телефон, день рождения, согласия).

Оформить заказ от имени этого клиента (та же структура позиций, что и у конечной точки создания мерчанта; личность берётся из токена). Возвращает заказ с его track_token.

Собственная история заказов клиента, с пагинацией.

Сохранённые адреса доставки (первый становится основным; поддерживает lat/lng).

Отзывает токен, использованный для запроса (только это устройство).

Отслеживание заказа Публичный

Без авторизации — доступ ограничен неугадываемым track_token (возвращается при создании заказа). Это обеспечивает работу приложение для клиента экрана отслеживания в реальном времени.

{
  "id": 5501, "status": "preparing", "delivery_status": "out_for_delivery",
  "is_paid": true, "total": 42.00,
  "timeline": { "preparing_at": "...", "out_for_delivery_at": "..." },
  "items": [ { "name": "Margherita", "quantity": 2 } ],
  "driver": { "name": "Alex", "lat": 25.2, "lng": 55.27, "location_updated_at": "..." }
}

Блок курьера (с координатами в реальном времени) появляется только после того, как заказ забран / в пути.

Вход для сотрудников

A приложения для персонала (POS / KDS / официант) аутентифицирует каждого сотрудника токеном на сотрудника. Два пути повторяют панель управления: email + пароль или быстрый числовой PIN-код для общих кухонных планшетов. Сотрудники ограничены рамками ресторана.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/staff/pin \
  -H "Content-Type: application/json" -d '{"pin":"4321","device":"Kitchen iPad"}'

# → { "token": "RAW_STAFF_TOKEN",
#     "staff": { "id": 3, "role": "kitchen", "permissions": ["kds"] } }

Ответ перечисляет действующие Разрешения — подмножество orders, menu_edit, coupons, analytics, kds, customers производные от их роли (менеджер / кассир / кухня / официант) плюс любые переопределения на сотрудника. Конечные точки ограничены правами (403 иначе).

API приложения для персонала

Аутентифицируйтесь токеном сотрудника. Базовый путь https://www.menubarcode.com/api/v1/staff. Все действия ограничены рестораном сотрудника.

Authorization: Bearer RAW_STAFF_TOKEN

Профиль с ролью и списком прав.

Список заказов и обновление статуса кухни. Требует orders права.

Актуальные кухонные тикеты, сгруппированные по заказу, отфильтрованные по станции сотрудника (или ?station_id=). Показывает только позиции, ещё queued|preparing|ready.

Продвинуть (queued → preparing → ready → served) или откатить на один статус KDS. Статус родительского заказа синхронизируется автоматически.

Редактируйте меню из зала (менеджеры). Те же payload, что и у конечных точек меню мерчанта, ограниченные рестораном сотрудника.

Сводка продаж для ресторана сотрудника (та же структура, что и у конечной точки аналитики мерчанта; ?from=&to=).

Отзывает токен этого устройства.

Webhooks — настройка

Регистрируйте конечные точки из панели управления в разделе API-токены и Webhook. Выберите, какие события получает каждая конечная точка. При сохранении вы получаете для каждой конечной точки Секрет подписи; используйте Тест кнопку, чтобы отправить ping. Приостановите конечную точку, чтобы остановить доставку, не теряя её секрет.

Ваша конечная точка должна отвечать статусом 2xx быстро (в течение 10 с). Любой другой статус — или таймаут — считается неудачей и повторяется.

Конечными точками также можно управлять программно (для REST-Hooks в Zapier/Make) с webhooks:write токеном:

GET    /api/v1/webhook-endpoints            # list your endpoints
POST   /api/v1/webhook-endpoints            # {"url":"https://…","events":["order.created"]} → 201 {id, secret, …}
DELETE /api/v1/webhook-endpoints/{id}       # unsubscribe → 204

Значение secret возвращается только при создании — сохраните его для проверки подписи. url должна быть публичной HTTPS-конечной точкой (с защитой от SSRF); events должно быть из списка ниже (или *).

События webhook

Доставка не удалась, пока ваша конечная точка была недоступна? Используйте Повторить доставку на любой строке в журнале «Недавние доставки» панели, чтобы снова поставить её в очередь с новым webhook-id.

Payload webhook

Каждая доставка — это POST с этим JSON-конвертом и этими заголовками:

POST /your-endpoint HTTP/1.1
Content-Type: application/json
webhook-id: msg_a1b2c3d4e5f6g7h8i9j0k1l2
webhook-timestamp: 1751472240
webhook-signature: v1,K5f...base64...==
X-Webhook-Event: order.created          (legacy)
X-Webhook-Signature: 9a3f...hex...      (legacy, HMAC of body only)

{
  "id": "msg_a1b2c3d4e5f6g7h8i9j0k1l2",
  "event": "order.created",
  "created_at": "2026-07-02T18:04:00+00:00",
  "data": { "order_id": 5501, "total": "42.00" }
}

Значение id уникален для каждой доставки. Поскольку повторы используют тот же id, используйте его, чтобы сделать ваш обработчик идемпотентным.

Проверка подписи

Значение webhook-signature заголовок — это HMAC-SHA256 в кодировке base64, вычисленный над {id}.{timestamp}.{body} с использованием секрета подписи вашей конечной точки. Привязка id и метки времени к подписи и делает перехваченный запрос защищённым от повторного воспроизведения. Отклоняйте любой запрос, чей webhook-timestamp старше примерно 5 минут.

PHP

$secret  = 'whsec_from_dashboard';
$id      = $_SERVER['HTTP_WEBHOOK_ID'];
$ts      = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body    = file_get_contents('php://input');
$sent    = explode(',', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])[1] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $secret, true));
if (!hash_equals($expected, $sent)) { http_response_code(401); exit; }

// verified — process $body
http_response_code(200);

Node.js

const crypto = require('crypto');

function verify(req, secret) {
  const id  = req.headers['webhook-id'];
  const ts  = req.headers['webhook-timestamp'];
  const sig = (req.headers['webhook-signature'] || '').split(',')[1];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${id}.${ts}.${req.rawBody}`)
    .digest('base64');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig || ''));
}

Повторы и журнал доставок

Доставка асинхронна и повторяется при неудаче с экспоненциальной задержкой плюс джиттер: примерно 1m → 5m → 15m → 1h (всего до 5 попыток). Каждая попытка — успешная или неудачная — фиксируется в журнале доставок вашей панели с её HTTP-статусом, номером попытки и фрагментом ответа.

Серверы MCP

Пять серверов Model Context Protocol соединяют AI-агентов (ChatGPT, Claude, Cursor) с платформой — выберите тот, что подходит вашей аудитории. Все используют JSON-RPC 2.0 поверх HTTP и согласуют версии протокола 2024-11-05 / 2025-03-26 / 2025-06-18.

Быстрый старт: перейти к Admin, Catalog, Customer, или Dev. Сервер витрины использует тот же шаблон подключения, что и Admin, с X-Storefront-Token заголовком вместо Bearer-токена.

MCP-сервер (Admin)

AI-клиент с поддержкой MCP (Claude, ChatGPT, Cursor) может управлять вашим рестораном на естественном языке, используя те же API-токены. Направьте его на:

Аутентифицируйтесь через Authorization: Bearer YOUR_TOKEN. Каждый инструмент объявляет нужное ему точечное право (resource:action); устаревший read токен покрывает каждый :read инструмент, а write покрывает всё. Все вызовы ограничены вашими ресторанами и имеют лимит частоты. Инструменты, на которые у вас нет права, скрыты из tools/list.

Подключение (Claude Code)

claude mcp add --transport http platform-admin https://www.menubarcode.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Список инструментов

curl -X POST https://www.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Вызвать инструмент (например, добавить позицию меню)

curl -X POST https://www.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"add_menu_item",
                 "arguments":{"restaurant_id":12,"name":"Latte","price":4.5}}}'

Инструменты

Catalog MCP (поиск ресторанов)

Публичный MCP-сервер только для чтения, позволяющий AI-агентам находить рестораны и блюда по всей платформе, а затем переходить по диплинку в конкретный магазин для заказа. Без авторизации, с лимитом частоты.

Подключение (Claude Code)

claude mcp add --transport http platform-catalog https://www.menubarcode.com/mcp/catalog

Появляются только активные, публично перечисленные магазины; владельцы могут отказаться в настройках магазина. Контактные данные владельца никогда не возвращаются. Чтобы оформить заказ, используйте storefront MCP магазина с агентским токеном на магазин.

Customer Account MCP

Позволяет AI-ассистенту гостя читать, отслеживать и повторять свои собственные заказы. Аутентификация через токен на клиента из существующего входа по OTP; личность клиента берётся только из токена — телефон или id клиента никогда не принимаются как аргумент.

Получить токен (поток OTP)

# 1) request a one-time code (sent to the customer's phone)
curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/otp/request \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567"}'

# 2) verify the code → returns a customer bearer token
curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/otp/verify \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567","code":"123456"}'

Подключение (Claude Code)

claude mcp add --transport http my-orders https://www.menubarcode.com/mcp/customer \
  --header "Authorization: Bearer CUSTOMER_TOKEN"

curl -X POST https://www.menubarcode.com/mcp/customer \
  -H "Authorization: Bearer CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"my_orders","arguments":{"limit":5}}}'

Подключите свой AI-редактор

Создаёте тему или интеграцию с Claude Code, Cursor или VS Code? Направьте их на публичный Dev MCP-сервер — ваш AI-инструмент получает актуальную документацию платформы, сгенерированный белый список Liquid и серверную проверку тем. Токен не нужен.

Claude Code

claude mcp add --transport http platform-dev https://www.menubarcode.com/mcp/dev

Cursor — .cursor/mcp.json

{ "mcpServers": { "platform-dev": { "url": "https://www.menubarcode.com/mcp/dev" } } }

VS Code — .vscode/mcp.json

{ "servers": { "platform-dev": { "type": "http", "url": "https://www.menubarcode.com/mcp/dev" } } }

Инструменты learn_platform (начните здесь), search_docs / fetch_full_doc, get_liquid_reference, get_section_schema, validate_theme, list_webhook_events. Рекомендуемый рабочий процесс агента: изучение → сборка → проверка → доставка.

Список изменений

Назад к Menubarcode