API za razvijalce

• Meni: kategorije, jedi, cene in razpoložljivost po lokacijah ter razprodane jedi: umakniti jed iz prodaje ali jo vrniti
• Urejanje menija: kategorije in jedi, imena in opisi v jezikih gostov, cene, porcije, modifikatorji, vrstni red in vidnost
• Naročila: seznam s filtri, postavke in zneski, statusi kuhinje in izdaje (sprejeto, v pripravi, pripravljeno, izdano)
• Nova naročila iz klicnega centra, kioska ali druge spletne strani, z enakimi cenami in pravili dostave kot na vaši spletni strani; blagajna in kuhinja jih vidita takoj, gost pa plača ob prevzemu
• Dostava: kdo vozi (le ime dostavljavca), kdaj je naročilo prevzel in kdaj ga je dostavil: v samem naročilu in kot dogodek
• Plačila in vračila za vsako naročilo za usklajevanje, samo za branje
• Rezervacije: seznam, nova rezervacija in sprememba statusa (potrditi, zavrniti, gost je prišel ali ni prišel)
• Gostje: profili in kontakti, le s posebnim dovoljenjem
• Bonusi gostov: pripisati ali odšteti z razlogom, s posebnim dovoljenjem; stanje ne gre v minus, vsaka operacija pa se zapiše v dnevnik
• Prodaja po dnevih za računovodstvo: naročila, prihodek, popusti, vračila in napitnine po načinih plačila in kanalih
• Lokacije: naslovi, kontakti in delovni čas
• Dogodki (novo naročilo, sprememba statusa, plačilo, preklic, vračilo, dostava, nova rezervacija, razprodane jedi in spremembe menija) z webhookom na vaš strežnik

API ne zna sprejemati plačil, vračati denarja ali preklicevati naročil: z denarjem gostov upravlja le lokal sam. Zato gost naročila iz API-⁠ja plača ob prevzemu.

Ključ ustvari lastnik lokala na nadzorni plošči, v razdelku »API in webhooki«: integraciji da ime ter izbere pravice in lokacije. Ključ se prikaže le enkrat (v bazi ostane samo njegov prstni odtis) in ga je mogoče kadar koli preklicati. Imena, telefonske številke in naslove gostov integracija vidi le s pravico customers:read.

API teče na strežniku lokala: vsak naročnik platforme Vitrina ima svoj strežnik in svojo domeno. Ključ pošljete v glavi Authorization: Bearer vit_live_…, odgovor je JSON vedno v isti ovojnici: podatki, servisna polja in napaka s kodo in besedilom v jeziku zahteve.

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
}

Naslove za dogodke lastnik doda v istem razdelku plošče in za vsakega izbere, katere dogodke mu pošiljati. Vsaka zahteva je podpisana: glava Vitrina-Signature vsebuje čas pošiljanja in HMAC-SHA256 časa in telesa zahteve, izračunan s skrivnostjo naslova. Imena in kontakti gostov v dogodkih gredo le na naslove z vključeno možnostjo »Pošiljaj kontakte gosta«.

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 izračuna iz surovega telesa zahteve, pred razčlenjevanjem JSON. Podpis, starejši od 5 min, zavrnite; ponovna dostava istega dogodka nosi isti Vitrina-Event-Id; po njem izločite dvojnike.

• 600 zahtev na minuto na ključ, v konici do 60 naenkrat; nad omejitvijo pride odgovor 429 in glava Retry-After
• Glava Idempotency-Key pri POST, PUT in PATCH: ponovitev z istim ključem v 24 h vrne prvi odgovor, namesto da bi ustvarila dvojnik; pri novih naročilih in bonusih je obvezna
• Seznami po straneh: limit do 200 in offset, v odgovoru skupno število
• Če vaš strežnik ne odgovori v 10 s, dogodek pošljemo znova z naraščajočim premorom: 8 poskusov v skoraj dveh dneh
• Naslov, ki zapored ni sprejel 20 dostav, se sam izklopi; dnevnik dostav se hrani 30 dni, vsak dogodek iz njega pa je mogoče poslati znova

Različica je v naslovu: /api/open/v1. Nezdružljive spremembe izidejo le kot nova različica ob stari, stara pa odgovarja, dokler jo kdo uporablja. Datum revizije vmesnika je v polju apiVersion vsakega dogodka, trenutno 2026-10-13.

Vse zahteve, odgovori in kode napak so v specifikaciji OpenAPI na strežniku lokala: stran /api/open/v1/docs in datoteka /api/open/v1/openapi.json za generatorje odjemalcev.

Razvijate integracijo za več lokalov, na primer blagajno, dostavno službo ali računovodstvo? Pišite nam: dali vam bomo testni dostop in pomagali pri prvi povezavi.

API in webhooki so vključeni v paketa »Celoten« in »Veriga«. Za »Start« in »Restavracija« na zahtevo.

Primerjajte pakete