API dla programistów

• Menu: kategorie, dania, ceny i dostępność w poszczególnych lokalach oraz lista niedostępnych pozycji: wycofać danie ze sprzedaży lub je przywrócić
• Edycja menu: kategorie i dania, nazwy i opisy w językach gości, ceny, porcje, modyfikatory, kolejność i widoczność
• Zamówienia: lista z filtrami, pozycje i kwoty, statusy kuchni i wydania (przyjęte, w przygotowaniu, gotowe, wydane)
• Nowe zamówienia z call center, kiosku lub innej strony z tymi samymi cenami i zasadami dostawy co na Twojej stronie; kasa i kuchnia widzą je od razu, a gość płaci przy odbiorze
• Dostawa: kto wiezie (tylko imię kuriera), kiedy odebrał zamówienie i kiedy je dostarczył: w samym zamówieniu i jako zdarzenie
• Płatności i zwroty każdego zamówienia do rozliczeń, tylko odczyt
• Rezerwacje: lista, nowa rezerwacja i zmiana statusu (potwierdzić, odrzucić, gość przyszedł lub nie przyszedł)
• Goście: profile i kontakty, tylko z osobnym uprawnieniem
• Punkty lojalnościowe gości: dodać lub odjąć z podaniem powodu, z osobnym uprawnieniem; saldo nie spada poniżej zera, a każda operacja trafia do dziennika
• Sprzedaż według dni dla księgowości: zamówienia, przychód, rabaty, zwroty i napiwki według metod płatności i kanałów
• Lokale: adresy, kontakty i godziny otwarcia
• Zdarzenia (nowe zamówienie, zmiana statusu, płatność, anulowanie, zwrot, dostawa, nowa rezerwacja, lista niedostępnych pozycji i zmiany menu) webhookiem na Twój serwer

API nie przyjmuje płatności, nie zwraca pieniędzy i nie anuluje zamówień: pieniędzmi gości obraca tylko sam lokal. Dlatego za zamówienia z API gość płaci przy odbiorze.

Klucz tworzy właściciel lokalu w panelu, w sekcji „API i webhooki”: nadaje integracji nazwę oraz wybiera uprawnienia i lokale. Klucz jest pokazywany tylko raz (w bazie zostaje wyłącznie jego odcisk) i można go w każdej chwili unieważnić. Imiona, telefony i adresy gości integracja widzi tylko z uprawnieniem customers:read.

API działa na serwerze lokalu: każdy klient Vitrina ma własny serwer i własną domenę. Klucz przekazujesz w nagłówku Authorization: Bearer vit_live_…, odpowiedź to JSON zawsze w tej samej kopercie: dane, pola techniczne i błąd z kodem oraz komunikatem w języku zapytania.

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
}

Adresy zdarzeń właściciel dodaje w tej samej sekcji panelu i dla każdego wybiera, które zdarzenia na niego wysyłać. Każde zapytanie jest podpisane: nagłówek Vitrina-Signature zawiera czas wysłania i HMAC-SHA256 z czasu i treści zapytania, obliczony sekretem adresu. Imiona i kontakty gości w zdarzeniach trafiają tylko na adresy z zaznaczonym polem „Wysyłaj kontakty gościa”.

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))
}

Podpis liczy się z surowej treści zapytania, przed parsowaniem JSON. Odrzucaj podpisy starsze niż 5 min; ponowne doręczenie tego samego zdarzenia ma ten sam Vitrina-Event-Id; po nim odfiltrujesz duplikaty.

• 600 zapytań na minutę na każdy klucz, szczytowo do 60 naraz; powyżej limitu przychodzi odpowiedź 429 i nagłówek Retry-After
• Nagłówek Idempotency-Key w POST, PUT i PATCH: powtórzenie z tym samym kluczem w ciągu 24 h zwraca pierwszą odpowiedź, zamiast tworzyć duplikat; przy nowych zamówieniach i punktach jest obowiązkowy
• Listy są dzielone na strony: limit do 200 i offset, a w odpowiedzi jest łączna liczba
• Jeśli Twój serwer nie odpowie w ciągu 10 s, wysyłamy zdarzenie ponownie z rosnącą przerwą: 8 prób w ciągu niemal dwóch dób
• Adres, który nie przyjął 20 doręczeń z rzędu, wyłącza się sam; dziennik doręczeń jest przechowywany przez 30 dni, a każde zdarzenie z niego można wysłać ponownie

Wersja jest w adresie: /api/open/v1. Niezgodne zmiany wychodzą tylko jako nowa wersja obok starej, a stara odpowiada, dopóki ktoś z niej korzysta. Data rewizji interfejsu jest w polu apiVersion każdego zdarzenia, obecnie 2026-10-13.

Wszystkie zapytania, odpowiedzi i kody błędów są w specyfikacji OpenAPI na serwerze lokalu: strona /api/open/v1/docs i plik /api/open/v1/openapi.json dla generatorów klientów.

Tworzysz integrację dla kilku lokali, na przykład kasę, serwis dostaw czy księgowość? Napisz do nas: damy Ci dostęp testowy i pomożemy przy pierwszym podłączeniu.

API i webhooki są w pakietach „Pełny” i „Sieć”. Dla „Start” i „Restauracja” na zapytanie.

Porównaj pakiety