Gyors indulás — Bokko Docs

Mire jó ez az oldal?#

Ez az útmutató fejlesztőknek szól, akik gyorsan szeretnék kipróbálni a Bokko Public API-t. Végigvezet egy teljes foglalási flow-n: listázod a szolgáltatásokat, keresel szabad időpontot, lefoglalod, majd lekérdezed a foglalás állapotát. Minden lépés copy-paste-elhető curl parancs.

Előfeltételek#

Bokko Pro előfizetés — a Public API csak Pro csomagon érhető el (lásd auth.plan_insufficient)
API kulcs az alábbi 4 capability-vel:
services.read — 1. lépés: szolgáltatások listázása
availability.read — 2. lépés: elérhetőség keresése
booking.create — 3. lépés: foglalás létrehozása
booking.read — 4. lépés: foglalás állapota

Tipp

Még nincs API kulcsod? A dashboardon hozhatod létre az Integrációk → API kulcsok menüpontban. Részletes UI útmutató: Help: API kulcsok kezelése.

1. lépés: Szolgáltatások listázása#

bash

curl -X GET "https://api.bokko.io/v1/services?salonSlug=pelda-szalon" \
  -H "Authorization: Bearer bk_live_..."

Példa válasz (200):

json

{
  "ok": true,
  "data": {
    "services": [
      {
        "id": "svc_haircut_01",
        "name": "Hajvágás",
        "durationMinutes": 45,
        "priceType": "fixed",
        "pricingVersion": "a1b2c3d4e5f6",
        "price": {
          "amount": 4500,
          "currency": "HUF"
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "v": "1"
  }
}

Jegyezd meg az id értékét — a következő lépésben szükséged lesz rá.

2. lépés: Elérhetőség keresése#

Az elérhetőséget POST kéréssel keressed — a paraméterek a request body-ban mennek, nem query string-ben.

bash

curl -X POST "https://api.bokko.io/v1/availability/search" \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "salonSlug": "pelda-szalon",
    "serviceId": "svc_haircut_01",
    "dateRange": {
      "from": "2026-05-12",
      "to": "2026-05-18"
    }
  }'

A dateRange.from és dateRange.to YYYY-MM-DD formátumú dátumok, a szalon helyi időzónájában értelmezve (max 31 nap tartomány).

Példa válasz (200):

json

{
  "ok": true,
  "data": {
    "slots": [
      {
        "date": "2026-05-12",
        "startTime": "10:00",
        "endTime": "10:45",
        "serviceId": "svc_haircut_01",
        "staffId": "staff_anna_01"
      },
      {
        "date": "2026-05-12",
        "startTime": "14:00",
        "endTime": "14:45",
        "serviceId": "svc_haircut_01",
        "staffId": "staff_anna_01"
      }
    ],
    "snapshotAt": "2026-05-11T08:00:00.000Z"
  },
  "meta": {
    "requestId": "req_def456",
    "v": "1"
  }
}

A date, startTime, endTime mezők a szalon helyi időzónájában értendők (nem UTC). A snapshotAt ezzel szemben UTC ISO 8601 timestamp. Jegyezd meg a kívánt date, startTime és staffId értékeket.

3. lépés: Foglalás létrehozása#

Mutáló műveleteknél (POST) Idempotency-Key header szükséges. Az UUID-t egyszer generáld shell változóba — retry esetén pontosan ugyanezt a kulcsot küldd újra.

bash

IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST "https://api.bokko.io/v1/bookings" \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -d '{
    "salonSlug": "pelda-szalon",
    "serviceId": "svc_haircut_01",
    "expectedPricingVersion": "a1b2c3d4e5f6",
    "staffId": "staff_anna_01",
    "slot": {
      "date": "2026-05-12",
      "startTime": "10:00"
    },
    "guest": {
      "name": "Teszt Vendég",
      "phone": "+36301234567"
    }
  }'

Figyelmeztetés

Az Idempotency-Key minden retry esetén UGYANAZ legyen — különben duplikált foglalást kockáztatsz. A példában az IDEMPOTENCY_KEY shell változót egyszer generáljuk, és minden retry-on újrahasználjuk. A backend RFC 4122 UUID v1–v5 formátumot validál (UUID v4 ajánlott).

Példa válasz (201):

json

{
  "ok": true,
  "data": {
    "booking": {
      "bookingId": "bkg_789xyz",
      "status": "requested",
      "serviceId": "svc_haircut_01",
      "serviceName": "Hajvágás",
      "staffId": "staff_anna_01",
      "staffName": "Anna",
      "guestName": "Teszt Vendég",
      "requestedSlot": {
        "date": "2026-05-12",
        "startTime": "10:00",
        "timezone": "Europe/Budapest"
      },
      "confirmedSlot": null,
      "createdAt": "2026-05-11T08:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_ghi789",
    "v": "1"
  }
}

Jegyezd meg a bookingId értékét.

4. lépés: Foglalás állapotának lekérdezése#

bash

curl -X GET "https://api.bokko.io/v1/bookings/{bookingId}?salonSlug=pelda-szalon" \
  -H "Authorization: Bearer bk_live_..."

A {bookingId} helyébe az előző lépésből kapott azonosítót írd (pl. bkg_789xyz).

Lehetséges státuszok: requested, confirmed, declined, cancelled, completed, noShow.

5. lépés (opcionális): Webhookok#

Ha valós idejű értesítéseket szeretnél a foglalás státuszváltozásairól (pl. booking.confirmed, booking.cancelled), állíts be webhookot. Ehhez webhook.manage capability szükséges a kulcsodon.

Részletes útmutató: Webhooks →

Mi jön ezután?#

Foglalási flow — teljes lifecycle, hibakezelés, lifecycle figyelése
Hibakódok — minden error code, retry stratégiák
Webhooks — HMAC aláírás verifikálás, delivery audit
API Reference — interaktív OpenAPI referencia

Tipp

A fenti példákban pelda-szalon, svc_haircut_01, staff_anna_01, bk_live_... illusztratív placeholderek — nem valódi backend azonosítók. A saját értékeid a Bokko dashboardon érhetők el.