API pre vývojárov

• Menu: kategórie, jedlá, ceny a dostupnosť v jednotlivých prevádzkach, ako aj vypredané položky: stiahnuť jedlo z predaja alebo ho vrátiť
• Úprava menu: kategórie a jedlá, názvy a popisy v jazykoch hostí, ceny, porcie, modifikátory, poradie a viditeľnosť
• Objednávky: zoznam s filtrami, položky a sumy, stavy kuchyne a výdaja (prijatá, pripravuje sa, hotová, vydaná)
• Nové objednávky z call centra, kiosku alebo iného webu s rovnakými cenami a pravidlami rozvozu ako na vašom webe; pokladnica a kuchyňa ich vidia hneď a hosť platí pri prevzatí
• Rozvoz: kto veze (len krstné meno kuriéra), kedy objednávku vyzdvihol a kedy ju doručil: priamo v objednávke aj udalosťou
• Platby a vrátenia peňazí pri každej objednávke na odsúhlasenie, len na čítanie
• Rezervácie: zoznam, nová rezervácia a zmena stavu (potvrdiť, odmietnuť, hosť prišiel alebo neprišiel)
• Hostia: profily a kontakty, len s osobitným povolením
• Bonusy hostí: pripísať alebo odpísať s dôvodom, s osobitným povolením; zostatok nejde do mínusu a každá operácia sa zapíše do denníka
• Predaj po dňoch pre účtovníctvo: objednávky, tržby, zľavy, vrátenia peňazí a prepitné podľa spôsobu platby a kanála
• Prevádzky: adresy, kontakty a otváracie hodiny
• Udalosti (nová objednávka, zmena stavu, platba, zrušenie, vrátenie peňazí, rozvoz, nová rezervácia, vypredané položky a zmeny menu) webhookom na váš server

Prijímať platby, vracať peniaze ani rušiť objednávky API nevie: s peniazmi hostí narába iba samotný podnik. Preto hosť objednávky z API platí pri prevzatí.

Kľúč vytvára majiteľ podniku v administrácii, v sekcii „API a webhooky“: pomenuje integráciu a zvolí oprávnenia a prevádzky. Kľúč sa zobrazí iba raz (v databáze zostáva len jeho odtlačok) a zrušiť ho možno kedykoľvek. Mená, telefóny a adresy hostí integrácia vidí len s oprávnením customers:read.

API beží na serveri podniku: každý klient Vitrina má vlastný server a vlastnú doménu. Kľúč sa posiela v hlavičke Authorization: Bearer vit_live_…, odpoveď je JSON vždy v rovnakej obálke: dáta, servisné polia a chyba s kódom a textom v jazyku požiadavky.

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 pre udalosti pridáva majiteľ v tej istej sekcii administrácie a pre každú zvolí, ktoré udalosti na ňu posielať. Každá požiadavka je podpísaná: hlavička Vitrina-Signature obsahuje čas odoslania a HMAC-SHA256 z času a tela požiadavky, vypočítaný tajným kľúčom adresy. Mená a kontakty hostí v udalostiach idú len na adresy so zapnutým políčkom „Posielať kontakty hosťa“.

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 sa počíta zo surového tela požiadavky, pred spracovaním JSON. Podpis starší ako 5 min odmietnite; opakované doručenie tej istej udalosti nesie rovnakú hodnotu Vitrina-Event-Id; podľa nej odfiltrujte duplikáty.

• 600 požiadaviek za minútu na každý kľúč, špička až 60 naraz; nad limit príde odpoveď 429 a hlavička Retry-After
• Hlavička Idempotency-Key pri POST, PUT a PATCH: opakovanie s rovnakým kľúčom do 24 h vráti prvú odpoveď namiesto vytvorenia duplikátu; pri nových objednávkach a bonusoch je povinná
• Zoznamy po stránkach: limit do 200 a offset, v odpovedi celkový počet
• Ak váš server neodpovie do 10 s, udalosť posielame znova s rastúcou pauzou: 8 pokusov počas takmer dvoch dní
• Adresa, ktorá neprijala 20 doručení za sebou, sa sama vypne; denník doručení sa uchováva 30 dní a každú udalosť z neho možno poslať znova

Verzia je v adrese: /api/open/v1. Nekompatibilné zmeny vychádzajú len ako nová verzia vedľa starej a stará odpovedá, kým ju niekto používa. Dátum revízie rozhrania je v poli apiVersion každej udalosti, teraz 2026-10-13.

Všetky požiadavky, odpovede a kódy chýb sú v špecifikácii OpenAPI na serveri podniku: stránka /api/open/v1/docs a súbor /api/open/v1/openapi.json pre generátory klientov.

Píšete integráciu pre viacero podnikov, napríklad pokladnicu, donáškovú službu či účtovníctvo? Napíšte nám: dáme vám testovací prístup a pomôžeme s prvým pripojením.

API a webhooky sú súčasťou balíkov „Kompletný“ a „Sieť“. Pre „Štart“ a „Reštaurácia“ na požiadanie.

Porovnať balíky