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 і вебхуки входять у тарифи «Повний» і «Мережа». Для «Старт» і «Ресторан» за запитом.

Порівняти тарифи