Public API

Bearer-authenticated REST API pre Zapier, Make, custom integrations. Stable v1 — Backward-compatible breaking changes len cez nový major version (v2).

📄 OpenAPI 3.1 spec (JSON)🔔 Webhooks dokumentácia 🔑 Vytvoriť API kľúč

1. Authentication

Každý request musí mať header Authorization: Bearer rk_live_*. Vytvorte kľúč v dashboard → API kľúče. Plaintext sa zobrazí iba raz — uložte ho do env var alebo secret manager.

curl -X GET "https://app.terminuj.sk/api/v1/services" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

2. Scopes

Pri tvorbe kľúča vyberiete scopes — limitujte na potrebné minimum.

Scope	Endpointy
`booking:read`	GET /bookings, GET /bookings/{id}
`booking:write`	POST /bookings, PATCH cancel/reschedule
`customer:read`	GET /customers
`service:read`	GET /services
`webhook:manage`	GET/POST/DELETE /webhooks + /deliveries

3. Endpoints

Vytvoriť rezerváciu

curl -X POST "https://app.terminuj.sk/api/v1/bookings" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "uuid-of-service",
    "startAt": "2026-06-15T14:00:00.000Z",
    "customer": {
      "fullName": "Jana Vassová",
      "email": "jana@example.com",
      "phone": "+421900123456"
    }
  }'

Zrušiť rezerváciu

PATCH s discriminated union body — alebo {"action": "reschedule", "startAt": "..."}.

curl -X PATCH "https://app.terminuj.sk/api/v1/bookings/<booking-uuid>" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "action": "cancel", "reason": "Customer no-show" }'

Search zákazníkov

curl "https://app.terminuj.sk/api/v1/customers?search=jana&limit=10" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

4. Pagination

Cursor-based, parametre ?limit=25&cursor=<id>. Max 100/page pre booky+customers, 200 pre services. Response: { pagination: { nextCursor, hasMore, limit } }.

# First page
curl "https://app.terminuj.sk/api/v1/bookings?limit=25"

# Next page (use nextCursor from previous response)
curl "https://app.terminuj.sk/api/v1/bookings?limit=25&cursor=<nextCursor-id>"

5. Rate limiting

Per-key token bucket:

Read scopes (booking:read, customer:read, service:read): 600 req/min
Write scopes (booking:write, webhook:manage): 60 req/min

Pri prekročení dostanete 429 rate_limit_exceeded s headerom Retry-After (sekundy do reset). Implementujte exponenciálny backoff alebo skontrolujte počet pred ďalším requestom.

6. Chybové kódy

HTTP	error	Význam
401	`missing_or_invalid_authorization`	Bearer chýba alebo zlý formát
401	`invalid_api_key`	Kľúč neexistuje / hash mismatch
401	`api_key_revoked`	Kľúč bol manuálne revokeovaný
401	`api_key_expired`	Prešiel expiresAt
403	`insufficient_scope`	Kľúč nemá požadovaný scope
422	`invalid_body`	Zod validation error — detail v `detail`
429	`rate_limit_exceeded`	600/min read, 60/min write per kľúč

7. Webhooks

Pre push-based notifikácie (BOOKING_CREATED, CANCELLED, ...) pozri /docs/webhooks — HMAC SHA-256 podpis, retry logika (5 attempts s exponenciálnym backoff), code samples.

Webhook CRUD aj cez API: GET/POST/DELETE /api/v1/webhooks + GET /api/v1/webhooks/{id}/deliveries pre debug log.

8. Support

Bug report / feature request: vass@vassweb.com.