API для разработчиков

• Меню: категории, блюда, цены и наличие по точкам, а также стоп-лист: снять блюдо с продажи или вернуть его
• Редактирование меню: категории и блюда, названия и описания на языках гостей, цены, порции, модификаторы, порядок и видимость
• Заказы: список с фильтрами, состав и суммы, статусы кухни и выдачи (принят, готовится, готов, выдан)
• Новые заказы из колл-центра, киоска или другого сайта по тем же ценам и правилам доставки, что и на вашем сайте; касса и кухня видят их сразу, а гость платит при получении
• Доставка: кто везёт (только имя курьера), когда забрал и когда доставил: в самом заказе и событием
• Оплаты и возвраты каждого заказа для сверки, только просмотр
• Бронирования: список, новое бронирование и смена статуса (подтвердить, отклонить, гость пришёл или не пришёл)
• Гости: профили и контакты, только с отдельным разрешением
• Бонусы гостей: начислить или списать с причиной, с отдельным разрешением; баланс не уходит в минус, каждая операция записывается в журнал
• Продажи по дням для учёта: заказы, выручка, скидки, возвраты и чаевые с разбивкой по способам оплаты и каналам
• Точки: адреса, контакты и часы работы
• События (новый заказ, смена статуса, оплата, отмена, возврат, доставка, новое бронирование, стоп-лист и изменения меню) вебхуком на ваш сервер

Принимать оплату, возвращать деньги и отменять заказы API не умеет: деньги гостей двигает только само заведение. Поэтому заказы из API гость оплачивает при получении.

Ключ создаёт владелец заведения в панели управления, в разделе «API и вебхуки»: даёт интеграции название и выбирает права и точки. Ключ показывается один раз (в базе остаётся только его отпечаток), и отозвать его можно в любой момент. Имена, телефоны и адреса гостей интеграция видит только с правом customers:read.

API работает на сервере заведения: у каждого клиента Vitrina свой сервер и свой домен. Ключ передаётся в заголовке Authorization: Bearer vit_live_…, ответ приходит в JSON в одном и том же конверте: данные, служебные поля и ошибка с кодом и текстом на языке запроса.

curl https://api.example.com/api/open/v1/ping \
  -H "Authorization: Bearer vit_live_…"

{
  "data": {
    "ok": true,
    "brand": "my-bistro",
    "apiVersion": "2026-10-13",
    "serverTime": "2026-10-13T09:30:00.000Z",
    "clientName": "POS integration",
    "scopes": ["menu:read", "orders:read", "orders:write"],
    "cafeIds": []
  },
  "meta": null,
  "error": null
}

Адреса для событий владелец добавляет в том же разделе панели и выбирает, какие события на каждый отправлять. Каждый запрос подписан: заголовок Vitrina-Signature содержит время отправки и HMAC-SHA256 от времени и тела запроса, вычисленный секретом адреса. Имена и контакты гостей в событиях отправляем только на адреса с включённой галочкой «Отправлять контакты гостя».

import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

export function isFromVitrina(rawBody, header, secret) {
  const parts = header.split(',').map((part) => part.trim().split('='))
  const t = parts.find(([name]) => name === 't')?.[1] ?? ''
  const age = Math.abs(Date.now() / 1000 - Number(t))
  if (!/^\d+$/.test(t) || age > TOLERANCE_SECONDS) return false
  const hmac = createHmac('sha256', secret).update(`${t}.${rawBody}`)
  const want = Buffer.from(hmac.digest('hex'))
  return parts
    .filter(([name]) => name === 'v1')
    .map(([, value]) => Buffer.from(value ?? ''))
    .some((got) => got.length === want.length && timingSafeEqual(got, want))
}

Подпись считается от сырого тела запроса, до разбора JSON. Подпись старше 5 мин отбрасывайте; повторная доставка того же события несёт тот же Vitrina-Event-Id, по нему отсекайте дубликаты.

• 600 запросов в минуту на каждый ключ, пик до 60 за раз; сверх лимита приходит ответ 429 и заголовок Retry-After
• Заголовок Idempotency-Key в POST, PUT и PATCH: повтор с тем же ключом в течение 24 ч возвращает первый ответ, а не создаёт дубль; для новых заказов и бонусов он обязателен
• Списки отдаются страницами: limit до 200 и offset, в ответе есть общее количество
• Если ваш сервер не ответил за 10 с, событие отправляем снова с растущей паузой: 8 попыток в течение почти двух суток
• Адрес, который не принял 20 доставок подряд, отключается сам; журнал доставок хранится 30 дней, и любое событие из него можно отправить снова

Версия указана в адресе: /api/open/v1. Несовместимые изменения выходят только новой версией рядом со старой, и старая отвечает, пока ею пользуются. Дата редакции контракта есть в поле apiVersion каждого события, сейчас это 2026-10-13.

Все запросы, ответы и коды ошибок описаны в спецификации OpenAPI на сервере заведения: страница /api/open/v1/docs и файл /api/open/v1/openapi.json для генераторов клиентов.

Пишете интеграцию для нескольких заведений, например кассу, службу доставки или учёт? Напишите нам: дадим тестовый доступ и поможем с первым подключением.

API и вебхуки входят в тарифы «Полный» и «Сеть». Для «Старт» и «Ресторан» по запросу.

Сравнить тарифы