API za programere

• Jelovnik: kategorije, jela, cijene i dostupnost po lokacijama te popis rasprodanog: povući jelo iz prodaje ili ga vratiti
• Uređivanje jelovnika: kategorije i jela, nazivi i opisi na jezicima gostiju, cijene, porcije, modifikatori, redoslijed i vidljivost
• Narudžbe: popis s filtrima, stavke i iznosi, statusi kuhinje i izdavanja (prihvaćena, priprema se, gotova, izdana)
• Nove narudžbe iz pozivnog centra, kioska ili druge web-stranice, s istim cijenama i pravilima dostave kao na vašoj web-stranici; blagajna i kuhinja vide ih odmah, a gost plaća pri preuzimanju
• Dostava: tko vozi (samo ime dostavljača), kada je preuzeo i kada je dostavio narudžbu: u samoj narudžbi i kao događaj
• Plaćanja i povrati novca za svaku narudžbu za usklađivanje, samo za čitanje
• Rezervacije: popis, nova rezervacija i promjena statusa (potvrditi, odbiti, gost je došao ili nije došao)
• Gosti: profili i kontakti, samo uz posebno dopuštenje
• Bodovi gostiju: dodijeliti ili oduzeti uz razlog, uz posebno dopuštenje; stanje ne ide u minus, a svaka se operacija bilježi u dnevnik
• Prodaja po danima za računovodstvo: narudžbe, prihod, popusti, povrati novca i napojnice po načinima plaćanja i kanalima
• Lokacije: adrese, kontakti i radno vrijeme
• Događaji (nova narudžba, promjena statusa, plaćanje, otkazivanje, povrat novca, dostava, nova rezervacija, popis rasprodanog i promjene jelovnika) webhookom na vaš poslužitelj

API ne može naplatiti, vratiti novac ni otkazati narudžbu: novcem gostiju upravlja samo sam lokal. Zato gost narudžbe iz API-⁠ja plaća pri preuzimanju.

Ključ izrađuje vlasnik lokala na upravljačkoj ploči, u odjeljku „API i webhookovi”: daje integraciji naziv te odabire ovlasti i lokacije. Ključ se prikazuje samo jednom (u bazi ostaje samo njegov otisak) i može se opozvati u bilo kojem trenutku. Imena, telefone i adrese gostiju integracija vidi samo uz ovlast customers:read.

API radi na poslužitelju lokala: svaki klijent platforme Vitrina ima vlastiti poslužitelj i vlastitu domenu. Ključ se šalje u zaglavlju Authorization: Bearer vit_live_…, a odgovor je JSON uvijek u istoj omotnici: podaci, servisna polja i pogreška s kodom i tekstom na jeziku zahtjeva.

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
}

Adrese za događaje vlasnik dodaje u istom odjeljku ploče i za svaku odabire koje joj događaje slati. Svaki je zahtjev potpisan: zaglavlje Vitrina-Signature sadrži vrijeme slanja i HMAC-SHA256 vremena i tijela zahtjeva, izračunat tajnim ključem adrese. Imena i kontakti gostiju u događajima idu samo na adrese s uključenom opcijom „Slati 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))
}

Potpis se računa iz sirovog tijela zahtjeva, prije parsiranja JSON-⁠a. Odbacite potpis stariji od 5 min; ponovna dostava istog događaja nosi isti Vitrina-Event-Id; po njemu uklonite duplikate.

• 600 zahtjeva u minuti po ključu, vršno do 60 odjednom; iznad ograničenja stiže odgovor 429 i zaglavlje Retry-After
• Zaglavlje Idempotency-Key u POST, PUT i PATCH: ponavljanje s istim ključem unutar 24 h vraća prvi odgovor umjesto stvaranja duplikata; kod novih narudžbi i bodova je obavezno
• Popisi po stranicama: limit do 200 i offset, u odgovoru ukupan broj
• Ako vaš poslužitelj ne odgovori u roku od 10 s, događaj šaljemo ponovno s rastućom stankom: 8 pokušaja tijekom gotovo dva dana
• Adresa koja nije primila 20 dostava zaredom sama se isključuje; dnevnik dostava čuva se 30 dana, a svaki događaj iz njega može se ponovno poslati

Verzija je u adresi: /api/open/v1. Nekompatibilne promjene izlaze samo kao nova verzija uz staru, a stara odgovara dok je se koristi. Datum revizije sučelja je u polju apiVersion svakog događaja, trenutačno 2026-10-13.

Svi zahtjevi, odgovori i kodovi pogrešaka nalaze se u OpenAPI specifikaciji na poslužitelju lokala: stranica /api/open/v1/docs i datoteka /api/open/v1/openapi.json za generatore klijenata.

Razvijate integraciju za više lokala, na primjer blagajnu, dostavnu službu ili računovodstvo? Pišite nam: dat ćemo vam testni pristup i pomoći s prvim povezivanjem.

API i webhookovi uključeni su u pakete „Potpuni” i „Lanac”. Za „Start” i „Restoran” na upit.

Usporedite pakete