Changelog

Verziós policy#

A Bokko Public API szemantikus verziózást követ. A jelenlegi stabil verzió: v1.

• Major változás (v1 → v2): nem visszakompatibilis — külön URL prefix, átmeneti párhuzamos futtatás
• Minor változás (v1.0 → v1.1): visszakompatibilis bővítés (pl. új opcionális mező, új endpoint)
• Patch: hibajav, belső változás, a contract nem módosul

Mi a contract#

Az alábbiak képezik az API contract részét — ezekre támaszkodhatnak az integrátorok:

• Endpoint URL és HTTP method
• Request és response mezők neve és típusa (required mezők esetén)
• Error code értékek, HTTP státuszuk és retryable flagjük
• Jogosultságnevek és hatókörük
• Webhook eseménynevek és a payload.event mező értéke

Mi NEM contract#

Az alábbiakra nem vállalunk stabilitási garanciát:

• Opcionális mezők hozzáadása vagy eltávolítása (ha eddig sem volt required)
• Hibaüzenet szövege (message mező) — csak a code stabil
• Meta extension mezők (meta.truncated, meta.returnedSlots stb.)
• Rate limit kvóta értékek (a struktúra stabil, az értékek nem)
• Belső Firestore path-ok, Cloud Function nevei

Jelenlegi v1 contract összefoglaló#

Kivezetési szabályok#

Ha egy endpoint, mező vagy jogosultság kivezetésre kerül:

1. Minimum 6 hónappal előre közöljük a kivezetést
2. Az érintett endpointok Deprecation HTTP response headert kapnak (RFC 8594)
3. A tervezett kikapcsolás dátumát Sunset HTTP response header jelzi
4. Email értesítés a Business előfizető regisztrált kapcsolati email-címére

v1.2.0 — 2026-09-14 — Webhook-újrapróbálás (at-least-once)#

• A kézbesítési garancia at-least-once: egy webhook-eseményt legfeljebb 3-szor próbálunk kézbesíteni (timeout, hálózati hiba, 408, 429, 5xx), a Retry-After figyelembevételével. A fogadónak kötelező idempotensen, deliveryId alapján feldolgoznia — deduplikáció nélkül ugyanaz az esemény kétszer is feldolgozódhat.
• A deliveryId minden eseménynél az üzleti esemény identitása: determinisztikus 32 karakteres hex string, minden kísérleten és újrakézbesítésen azonos. A nem-booking.requested eseményeknél sem véletlen UUID többé.
• Új fejléc: X-Bokko-Attempt (1–3). A törzs, a deliveryId és a timestamp minden kísérleten azonos; az aláírás az aktuális secrettel készül.
• booking.reschedule_confirmed közvetlen időpont-módosításnál: egy már megerősített időpont áthelyezése is ezt az eseményt küldi.
• Kézbesítési napló: eseményenként egy rekord status, attemptCount, lastAttemptAt, nextAttemptAt és attempts mezőkkel; az outcome és a statusCode a legutóbbi kísérletet írja le, az outcome pedig null, amíg az első kísérlet folyamatban van.
• Hibakód-formátum: a guest-partner végpont-tiltás kódja auth.kind_endpoint_denied, a <domain>.<reason> mintát követve.

v1.1.0 — 2026-05-16 — Telephelyek és confirmedSlot pontosítás#

• Telephelyi hatókör: Tisztáztuk a locationSlug paraméter használatát. A telephelyre szűkített katalógus- és foglalási végpontokon ez a paraméter kötelező a szolgáltatások (GET /services), munkatársak (GET /staff) listázásához, az availability kereséshez és a foglalás létrehozásához.
• Booking schema bővítés: A foglalás objektum kiegészült a locationId és locationSnapshot mezőkkel minden végponton és webhook üzenettörzsben.
• confirmedSlot pontosítás: Pontosítottuk a dokumentációt: a confirmedSlot mező az aktív, megerősített jellegű életciklus-állapotoknál van kitöltve, például confirmed, completed és noShow esetén, míg cancelled vagy declined foglalásoknál mindig null.
• Embed Widget v1.1.0: Új data-location attribútum támogatása konkrét telephelyek beágyazásához.

v1.0.0 — 2026-05-05 — Kezdeti publikáció#

Az első stabil nyilvános kiadás. Az alábbi számok erre a release-re vonatkoznak és rögzítve maradnak — nem frissülnek automatikusan ha a contract bővül.

• 14 dokumentált endpoint
• 27 stabil error code
• 8 webhook event
• 8 jogosultság
• 5 kérésilimit-csoport

Endpointok:

• POST /availability/search
• GET /bookings
• POST /bookings
• GET /bookings/{bookingId}
• POST /bookings/{bookingId}/cancel
• GET /bookings/{bookingId}/events
• GET /services
• GET /staff
• GET /subscription
• GET /webhooks/config
• PUT /webhooks/config
• DELETE /webhooks/config
• POST /webhooks/config/rotate-secret
• GET /webhooks/deliveries