API pro vývojáře

• Menu: kategorie, jídla, ceny a dostupnost na jednotlivých provozovnách, a také vyprodané položky: stáhnout jídlo z prodeje nebo ho vrátit
• Úprava menu: kategorie a jídla, názvy a popisy v jazycích hostů, ceny, porce, modifikátory, pořadí a viditelnost
• Objednávky: seznam s filtry, položky a částky, stavy kuchyně a výdeje (přijata, připravuje se, hotova, vydána)
• Nové objednávky z call centra, kiosku nebo jiného webu se stejnými cenami a pravidly rozvozu jako na vašem webu; pokladna a kuchyně je vidí hned a host platí při převzetí
• Rozvoz: kdo veze (jen křestní jméno kurýra), kdy objednávku vyzvedl a kdy ji doručil: přímo v objednávce i událostí
• Platby a vracení peněz u každé objednávky pro odsouhlasení, jen ke čtení
• Rezervace: seznam, nová rezervace a změna stavu (potvrdit, odmítnout, host přišel nebo nepřišel)
• Hosté: profily a kontakty, jen se zvláštním oprávněním
• Bonusy hostů: připsat nebo odepsat s důvodem, se zvláštním oprávněním; zůstatek nejde do minusu a každá operace se zapíše do deníku
• Prodeje po dnech pro účetnictví: objednávky, tržby, slevy, vracení peněz a spropitné podle způsobu platby a kanálu
• Provozovny: adresy, kontakty a otevírací doba
• Události (nová objednávka, změna stavu, platba, zrušení, vrácení peněz, rozvoz, nová rezervace, vyprodané položky a změny menu) webhookem na váš server

Přijímat platby, vracet peníze ani rušit objednávky API neumí: s penězi hostů hýbe jen samotný podnik. Proto host objednávky z API platí při převzetí.

Klíč vytváří majitel podniku v administraci, v sekci „API a webhooky“: pojmenuje integraci a zvolí oprávnění a provozovny. Klíč se zobrazí jen jednou (v databázi zůstává pouze jeho otisk) a zrušit ho lze kdykoli. Jména, telefony a adresy hostů integrace vidí jen s oprávněním customers:read.

API běží na serveru podniku: každý klient Vitrina má vlastní server a vlastní doménu. Klíč se posílá v hlavičce Authorization: Bearer vit_live_…, odpověď je JSON vždy ve stejné obálce: data, servisní pole a chyba s kódem a textem v jazyce požadavku.

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 pro události přidává majitel ve stejné sekci administrace a u každé zvolí, které události na ni posílat. Každý požadavek je podepsaný: hlavička Vitrina-Signature obsahuje čas odeslání a HMAC-SHA256 z času a těla požadavku, vypočtený tajným klíčem adresy. Jména a kontakty hostů v událostech chodí jen na adresy se zapnutým políčkem „Posílat kontakty hosta“.

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 se počítá ze surového těla požadavku, před zpracováním JSON. Podpis starší než 5 min odmítněte; opakované doručení téže události nese stejnou hodnotu Vitrina-Event-Id; podle ní odfiltrujte duplikáty.

• 600 požadavků za minutu na každý klíč, špička až 60 najednou; nad limit přijde odpověď 429 a hlavička Retry-After
• Hlavička Idempotency-Key u POST, PUT a PATCH: opakování se stejným klíčem do 24 h vrátí první odpověď místo vytvoření duplikátu; u nových objednávek a bonusů je povinná
• Seznamy po stránkách: limit do 200 a offset, v odpovědi celkový počet
• Pokud váš server neodpoví do 10 s, událost posíláme znovu s rostoucí pauzou: 8 pokusů během téměř dvou dnů
• Adresa, která nepřijala 20 doručení po sobě, se sama vypne; deník doručení se uchovává 30 dní a každou událost z něj lze poslat znovu

Verze je v adrese: /api/open/v1. Nekompatibilní změny vycházejí jen jako nová verze vedle staré a stará odpovídá, dokud ji někdo používá. Datum revize rozhraní je v poli apiVersion každé události, nyní 2026-10-13.

Všechny požadavky, odpovědi a kódy chyb jsou ve specifikaci OpenAPI na serveru podniku: stránka /api/open/v1/docs a soubor /api/open/v1/openapi.json pro generátory klientů.

Píšete integraci pro více podniků, například pokladnu, rozvozovou službu nebo účetnictví? Napište nám: dáme vám testovací přístup a pomůžeme s prvním připojením.

API a webhooky jsou součástí tarifů „Kompletní“ a „Síť“. Pro „Start“ a „Restaurace“ na vyžádání.

Porovnat tarify