Veřejné API

REST API (verze v1) pro vlastní web provozovny, AI recepční, Zapier, Make a další napojení. Odpovědi jsou JSON s polem ok; při chybě i error. Úplný popis všech cest a polí najdete v OpenAPI 3.1.

📄 OpenAPI 3.1 (JSON)🔔 Webhooky 🔑 Vytvořit API klíč

1. Přihlášení klíčem

Každý požadavek musí mít hlavičku Authorization: Bearer rk_live_…. Klíč vytvoříte na nástěnce → API klíče. Celý klíč se zobrazí pouze jednou — uložte si ho do proměnných prostředí nebo správce hesel; u nás je uložen jen jeho otisk. Klíč patří jedné provozovně, proto se provozovna v požadavcích neuvádí.

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

2. Oprávnění klíče

Při vytváření klíče vyberete oprávnění — dejte mu jen ta, která napojení opravdu potřebuje.

Oprávnění	Cesty (/api/v1/…)
`booking:read`	GET /bookings, GET /bookings/{id}, GET /time-off
`booking:write`	POST /bookings, PATCH /bookings/{id} (zrušit, přesunout, potvrdit), POST /time-off, DELETE /time-off/{id}
`customer:read`	GET /customers
`service:read`	GET /services, GET /availability
`webhook:manage`	GET/POST /webhooks, GET/DELETE /webhooks/{id}, GET /webhooks/{id}/deliveries

3. Nejčastější použití

Volné termíny

Pro každý den vrátí, zda je otevřeno, a volné časy po odečtení rezervací, volna a přestávek služby; nejdříve 2 h od teď. from = den ve tvaru RRRR-MM-DD (výchozí dnes), days 1–62 (výchozí 28), volitelně staff = konkrétní pracovník. Časové pásmo je Europe/Bratislava.

curl "https://app.terminuj.com/api/v1/availability?service=<id-sluzby>&from=2026-06-15&days=7" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

Vytvořit rezervaci

startAt v UTC se Z na konci (12:00Z = 14:00 v létě v Bratislavě). E-mail zákazníka je povinný; bez něj jen s "channel": "telefon" (termín přijatý telefonicky — stačí jméno a telefon). Termín z veřejného formuláře vašeho webu posílejte s "channel": "web"; pokud provozovna vyžaduje souhlas se zahájením služby před uplynutím lhůty pro odstoupení, přidejte "serviceStartConsent": true podle políčka, které zákazník zaškrtl (jinak 422 consent_required). Volitelně preferredStaffId, customer.notes a locale (sk | en | cs | hu | de | es — jazyk hlášek API a dalších zpráv zákazníkovi k této rezervaci, výchozí je jazyk provozovny). Opakované odeslání stejné služby a času se stejným e-mailem do 10 minut vrátí tutéž rezervaci (dvojklik, výpadek sítě).

Terminuj zákazníkovi při rezervaci přes API potvrzovací e-mail neposílá — potvrzení pošle vaše napojení. Majitel dostane oznámení podle nastavení provozovny. Rezervace se započítává do měsíčního počtu tarifu.

curl -X POST "https://app.terminuj.com/api/v1/bookings" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "<id-sluzby>",
    "startAt": "2026-06-15T12:00:00Z",
    "customer": {
      "fullName": "Jana Nováková",
      "email": "jana@example.com",
      "phone": "+421900123456"
    }
  }'

Zrušit, přesunout nebo potvrdit rezervaci

Jedna cesta, podle pole action: {"action": "cancel", "reason": "…"}, {"action": "reschedule", "startAt": "…Z"} nebo {"action": "confirm"} (jen termín, který čeká na zálohu). Při zrušení dostane zákazník e-mail; o přesunu a potvrzení, pokud má provozovna zapnuté potvrzovací e-maily.

curl -X PATCH "https://app.terminuj.com/api/v1/bookings/<id-rezervacie>" \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "action": "cancel", "reason": "Zákazník neprišiel" }'

Hledat zákazníky

search hledá ve jméně, e-mailu a telefonu.

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

Další cesty (seznam rezervací s filtrem from/to/status/createdFrom, služby, blokování času /time-off, webhooky) jsou popsány v OpenAPI.

4. Stránkování

Seznamy mají parametry ?limit=25&cursor=<id>. Výchozí 25, nejvýše 100 na stránku (rezervace, zákazníci, doručení webhooků); služby výchozí 50, nejvýše 200. Odpověď obsahuje { pagination: { nextCursor, hasMore, limit } }.

# První strana
curl "https://app.terminuj.com/api/v1/bookings?limit=25" -H "Authorization: Bearer rk_live_…"

# Další strana (nextCursor z předchozí odpovědi)
curl "https://app.terminuj.com/api/v1/bookings?limit=25&cursor=<nextCursor>" -H "Authorization: Bearer rk_live_…"

5. Limit požadavků

Limit se počítá na klíč v klouzavém okně 1 minuty:

Čtení (booking:read, customer:read, service:read): 600 požadavků za minutu
Zápis (booking:write, webhook:manage): 60 požadavků za minutu

Při překročení přijde 429 rate_limit_exceeded s hlavičkou Retry-After (za kolik sekund to zkusit znovu) a polem retryAfterSeconds. Hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset přijdou při odmítnutí.

6. Chybové kódy

HTTP	error	Význam
401	`missing_or_invalid_authorization`	Chybí hlavička Authorization nebo klíč nemá tvar rk_live_ + 24 znaků
401	`invalid_api_key`	Takový klíč neexistuje
401	`api_key_revoked`	Klíč byl zrušen na nástěnce
401	`api_key_expired`	Platnost klíče vypršela (expiresAt)
402	`trial_ended`	Provozovně skončila zkušební doba — 14 dní od registrace (resetAt = konec zkoušky); nové rezervace až po výběru tarifu
402	`monthly_limit_exceeded`	Provozovna vyčerpala měsíční počet rezervací partnerského tarifu (used, limit, resetAt)
403	`insufficient_scope`	Klíč nemá potřebné oprávnění (required, have)
403	`manual_requires_app`	„manual: true“ smí poslat jen přihlášený člověk z aplikace Terminuj, ne API klíč
404	`not_found`	Rezervace, volno nebo webhook v této provozovně neexistuje (i service_not_found)
409	`slot_conflict`	Termín je mezitím obsazený; při vytvoření přijdou i suggestedAlternatives
409	`already_cancelled`	Stav rezervace změnu nedovolí (i already_completed, cannot_cancel, not_reschedulable, already_confirmed, cannot_confirm)
422	`invalid_body`	Tělo požadavku neodpovídá schématu — podrobnosti v detail
422	`consent_required`	Provozovna vyžaduje souhlas se zahájením služby před uplynutím lhůty pro odstoupení a chybí serviceStartConsent: true
422	`start_in_past`	Začátek je v minulosti (i outside_working_hours = mimo otevírací dobu)
429	`rate_limit_exceeded`	Překročený limit požadavků klíče — viz část 5
429	`daily_cap_reached`	Provozovna dosáhla denního stropu veřejných rezervací (posledních 24 h) — zápis klíčem se počítá stejně jako formulář

7. Webhooky

Pokud chcete, aby vám Terminuj sám oznámil novou, zrušenou nebo přesunutou rezervaci, podívejte se na /docs/webhooks — podpis HMAC SHA-256, opakování po 1 min, 5 min, 30 min a 2 h, ukázky kódu.

Webhooky lze spravovat i přes API: GET/POST /api/v1/webhooks, GET/DELETE /api/v1/webhooks/{id} a GET /api/v1/webhooks/{id}/deliveries (záznam doručení).

8. Podpora

Chyba nebo požadavek na novou funkci: podpora@terminuj.com.