Hitelesítés

Áttekintés#

A Bokko Public API minden kérése Bearer-tokenes hitelesítést igényel. Az API kulcsot az Authorization fejlécben kell küldeni.

Authorization: Bearer bk_live_<key>

• Minden kulcs egyetlen szolgáltatói üzlethez van kötve
• A kulcsok explicit jogosultsághalmazzal rendelkeznek -- csak azokat a műveleteket engedik, amelyekre jogosultságot kaptak
• A kulcs önmagában nem ad teljes hozzáférést: a jogosultságok és az üzletszintű hatókör együtt határozzák meg a hozzáférést

API kulcs típusok#

API kulcsfajták#

A kulcstípus mellett a Bokko v1 egy külön key kind mezőt is használ, amely tovább szűkíti, mit tehet egy integration kulcs.

guest_partner kulcsnál az engedélyezett jogosultságkészlet erre a négyre szűkül:

• services.read
• staff.read
• availability.read
• booking.create

Jogosultságok#

A kulcsok jogosultságokkal rendelkeznek, amelyek meghatározzák, mely műveleteket végezhetik el. Ezeket a kulcs létrehozásakor kell beállítani.

Üzletszintű hatókör#

Az API kulcsok egyetlen szolgáltató üzletéhez vannak kötve. Az üzletszintű hatókör érvényesítése az alábbi módon történik:

Kötelező salonSlug és locationSlug paraméterek:

• POST /availability/search -- szabad időpontok lekérdezéséhez (request body-ban)
• POST /bookings -- foglalás létrehozásához (request body-ban)
• GET /services -- szolgáltatások listázásához (query stringben)
• GET /staff -- munkatársak listázásához (query stringben)

Kötelező salonSlug paraméter:

• GET /bookings -- foglalások listázásához (query stringben)
• GET /webhooks/config, PUT /webhooks/config, DELETE /webhooks/config -- webhook konfiguráció kezeléséhez
• POST /webhooks/config/rotate-secret -- webhook secret rotálásához
• GET /webhooks/deliveries -- kézbesítési napló lekérdezéséhez

Nem kötelező (a kulcs + booking resource alapján érvényesítve):

• GET /bookings/{bookingId}
• GET /bookings/{bookingId}/events
• POST /bookings/{bookingId}/cancel
• GET /subscription (a kulcs önmagában meghatározza, melyik szolgáltatói üzlet előfizetéséről van szó)

Ha a megadott salonSlug nem egyezik a kulcshoz rendelt üzlettel, vagy a locationSlug nem található:

HTTP 403
{
  "error": {
    "code": "auth.scope_mismatch",
    "message": "A kulcs nem jogosult erre a szolgáltatóra vagy telephelyre."
  }
}

Idempotencia#

Write műveletek támogatják az Idempotency-Key fejlécet az ismételt küldés elleni védelemhez.

Működés:

• Ugyanaz a kulcs + egyező fingerprint --> az eredeti válasz visszaadásra kerül (meta.idempotent: true)
• Ugyanaz a kulcs + eltérő fingerprint --> 409 idempotency.payload_mismatch

Rate limiting#

A Bokko Public API végpontcsoportonként (route group) és API kulcsonként külön limitet alkalmaz, 1 perces gördülő ablakkal. Két limit-szint (tier) létezik: standard és elevated.

Túllépés esetén a válasz:

HTTP 429
Retry-After: 30

{
  "error": {
    "code": "rate_limit.exceeded",
    "message": "Túllépte a kérésmennyiséget.",
    "retryable": true,
    "details": {
      "retryAfterSeconds": 30
    }
  }
}

Kulcs életciklus#

Kódpéldák#

cURL#

curl -X GET "https://api.bokko.io/v1/services?salonSlug=pelda-uzlet&locationSlug=belvaros" \
  -H "Authorization: Bearer bk_live_abc123def456"

JavaScript (fetch)#

const response = await fetch(
  'https://api.bokko.io/v1/services?salonSlug=pelda-uzlet&locationSlug=belvaros',
  {
    headers: {
      'Authorization': 'Bearer bk_live_abc123def456',
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();

Python (requests)#

import requests

response = requests.get(
    'https://api.bokko.io/v1/services',
    params={'salonSlug': 'pelda-uzlet', 'locationSlug': 'belvaros'},
    headers={
        'Authorization': 'Bearer bk_live_abc123def456',
        'Content-Type': 'application/json',
    },
)

data = response.json()