API fejlesztőknek

• Menü: kategóriák, ételek, árak és elérhetőség egységenként, valamint az elfogyott tételek: étel levétele az árusításból vagy visszavétele
• Menü szerkesztése: kategóriák és ételek, nevek és leírások a vendégek nyelvein, árak, adagok, módosítók, sorrend és láthatóság
• Rendelések: szűrhető lista, tételek és összegek, konyhai és kiadási állapotok (elfogadva, készül, kész, kiadva)
• Új rendelések call centerből, kioszkból vagy egy másik weboldalról, ugyanazokkal az árakkal és kiszállítási szabályokkal, mint az Ön weboldalán; a kassza és a konyha azonnal látja őket, a vendég pedig átvételkor fizet
• Kiszállítás: ki viszi (csak a futár keresztneve), mikor vette át és mikor kézbesítette a rendelést: magában a rendelésben és eseményként
• Minden rendelés fizetései és visszatérítései egyeztetéshez, csak olvasásra
• Foglalások: lista, új foglalás és állapotváltás (megerősítés, elutasítás, a vendég megérkezett vagy nem jött el)
• Vendégek: profilok és elérhetőségek, csak külön engedéllyel
• A vendégek bónuszpontjai: jóváírás vagy levonás indoklással, külön engedéllyel; az egyenleg nem mehet mínuszba, és minden művelet bekerül a naplóba
• Napi eladások a könyveléshez: rendelések, bevétel, kedvezmények, visszatérítések és borravalók fizetési mód és csatorna szerint
• Egységek: címek, elérhetőségek és nyitvatartás
• Események (új rendelés, állapotváltás, fizetés, lemondás, visszatérítés, kiszállítás, új foglalás, elfogyott tételek és menüváltozások) webhookkal az Ön szerverére

Fizetést fogadni, pénzt visszatéríteni vagy rendelést lemondani az API nem tud: a vendégek pénzét csak maga a vendéglátóhely mozgatja. Ezért az API-⁠n át leadott rendelést a vendég átvételkor fizeti ki.

A kulcsot a vendéglátóhely tulajdonosa hozza létre a kezelőpanel „API és webhookok” részében: nevet ad az integrációnak, és kiválasztja a jogosultságokat és az egységeket. A kulcs csak egyszer jelenik meg (az adatbázisban csak az ujjlenyomata marad), és bármikor visszavonható. A vendégek nevét, telefonszámát és címét az integráció csak a customers:read jogosultsággal látja.

Az API a vendéglátóhely saját szerverén fut: minden Vitrina-ügyfélnek saját szervere és domainje van. A kulcsot a Authorization: Bearer vit_live_… fejlécben kell küldeni; a válasz mindig ugyanabban a borítékban érkező JSON: adatok, technikai mezők és hiba esetén kód és a kérés nyelvén írt üzenet.

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
}

A webhookcímeket a tulajdonos a kezelőpanel ugyanazon részében adja hozzá, és mindegyikhez kiválasztja, mely eseményeket kapja. Minden kérés alá van írva: a Vitrina-Signature fejléc tartalmazza a küldés idejét, valamint az idő és a kéréstörzs HMAC-SHA256 értékét, a cím titkos kulcsával számolva. A vendégek neve és elérhetősége csak azokra a címekre megy ki, amelyeknél be van jelölve „A vendég elérhetőségeinek küldése”.

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

Az aláírás a nyers kéréstörzsből készül, a JSON feldolgozása előtt. A 5 percnél régebbi aláírást utasítsa el; ugyanannak az eseménynek az ismételt kézbesítése ugyanazt a Vitrina-Event-Id értéket hordozza; ez alapján szűrje ki a duplikátumokat.

• Kulcsonként percenként 600 kérés, csúcsban egyszerre legfeljebb 60; a korlát felett 429-es válasz és Retry-After fejléc
• Idempotency-Key fejléc POST, PUT és PATCH kéréseknél: ugyanazzal a kulccsal 24 órán belül megismételt kérés az első választ adja vissza, és nem hoz létre duplikátumot; új rendeléseknél és bónuszpontoknál kötelező
• A listák oldalanként érkeznek: limit legfeljebb 200, offset, a válaszban az összes darabszám
• Ha az Ön szervere 10 másodpercen belül nem válaszol, az eseményt növekvő szünetekkel újraküldjük: 8 kísérlet közel két nap alatt
• Az a cím, amely egymás után 20 kézbesítést nem fogadott, automatikusan kikapcsol; a kézbesítési napló 30 napig őrződik meg, és bármely esemény újraküldhető belőle

A verzió a címben van: /api/open/v1. Nem kompatibilis változás csak új verzióként jelenik meg a régi mellett, és a régi addig válaszol, amíg használják. Az interfész változatának dátuma minden esemény apiVersion mezőjében van, jelenleg 2026-10-13.

Minden kérés, válasz és hibakód megtalálható az OpenAPI-⁠specifikációban a vendéglátóhely szerverén: a /api/open/v1/docs oldal és a kliensgenerátoroknak szóló /api/open/v1/openapi.json fájl.

Több vendéglátóhelynek fejleszt integrációt, például kasszát, kiszállítási szolgáltatást vagy könyvelést? Írjon nekünk: tesztelési hozzáférést adunk, és segítünk az első bekötésben.

Az API és a webhookok a „Teljes” és a „Lánc” csomag részei. A „Start” és az „Étterem” csomaghoz kérésre.

Csomagok összehasonlítása