REST API (verzia v1) pre vlastný web prevádzky, AI recepčnú, Zapier, Make a iné napojenia. Odpovede sú JSON s poľom ok; pri chybe aj error. Úplný popis všetkých ciest a polí je v OpenAPI 3.1.
Každá požiadavka musí mať hlavičku Authorization: Bearer rk_live_…. Kľúč vytvoríte v nástenke → API kľúče. Celý kľúč sa zobrazí iba raz — uložte si ho do premenných prostredia alebo správcu hesiel; u nás je uložený len jeho odtlačok. Kľúč patrí jednej prevádzke, preto sa prevádzka v požiadavkách neuvádza.
curl "https://app.terminuj.sk/api/v1/services" \
-H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"Pri vytváraní kľúča vyberiete oprávnenia — dajte mu len tie, ktoré napojenie naozaj potrebuje.
| Oprávnenie | Cesty (/api/v1/…) |
|---|---|
booking:read | GET /bookings, GET /bookings/{id}, GET /time-off |
booking:write | POST /bookings, PATCH /bookings/{id} (zrušiť, presunúť, potvrdiť), 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 |
Pre každý deň vráti, či je otvorené, a voľné časy po odpočítaní rezervácií, voľna a prestávok služby; najskôr 2 h od teraz.from = deň v tvare RRRR-MM-DD (predvolene dnes), days 1–62 (predvolene 28), voliteľne staff = konkrétny pracovník. Časové pásmo je Europe/Bratislava.
curl "https://app.terminuj.sk/api/v1/availability?service=<id-sluzby>&from=2026-06-15&days=7" \
-H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"startAt v UTC so Z na konci (12:00Z = 14:00 v lete v Bratislave). E-mail zákazníka je povinný; bez neho len s "channel": "telefon" (termín prijatý telefonicky — stačí meno a telefón). Termín z verejného formulára vášho webu posielajte s "channel": "web"; ak prevádzka vyžaduje súhlas so začatím služby pred uplynutím lehoty na odstúpenie, pridajte "serviceStartConsent": true podľa políčka, ktoré zákazník zaškrtol (inak 422 consent_required). Voliteľne preferredStaffId, customer.notes a locale (sk | en | cs | hu | de | es — jazyk hlášok API a ďalších správ zákazníkovi k tejto rezervácii, predvolene jazyk prevádzky). Opakované odoslanie tej istej služby a času s tým istým e-mailom do 10 minút vráti tú istú rezerváciu (dvojklik, výpadok siete).
Terminuj zákazníkovi pri rezervácii cez API potvrdzovací e-mail neposiela — potvrdenie pošle vaše napojenie. Majiteľ dostane oznámenie podľa nastavení prevádzky. Rezervácia sa ráta do mesačného počtu plánu.
curl -X POST "https://app.terminuj.sk/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"
}
}'Jedna cesta, podľa poľa action: {"action": "cancel", "reason": "…"}, {"action": "reschedule", "startAt": "…Z"} alebo {"action": "confirm"} (len termín, ktorý čaká na zálohu). Pri zrušení dostane zákazník e-mail; o presune a potvrdení, ak má prevádzka zapnuté potvrdzovacie e-maily.
curl -X PATCH "https://app.terminuj.sk/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" }'search hľadá v mene, e-maile a telefóne.
curl "https://app.terminuj.sk/api/v1/customers?search=jana&limit=10" \
-H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"Ďalšie cesty (zoznam rezervácií s filtrom from/to/status/createdFrom, služby, blokovanie času /time-off, webhooky) sú popísané v OpenAPI.
Zoznamy majú parametre ?limit=25&cursor=<id>. Predvolene 25, najviac 100 na stranu (rezervácie, zákazníci, doručenia webhookov); služby predvolene 50, najviac 200. Odpoveď obsahuje { pagination: { nextCursor, hasMore, limit } }.
# Prvá strana
curl "https://app.terminuj.sk/api/v1/bookings?limit=25" -H "Authorization: Bearer rk_live_…"
# Ďalšia strana (nextCursor z predchádzajúcej odpovede)
curl "https://app.terminuj.sk/api/v1/bookings?limit=25&cursor=<nextCursor>" -H "Authorization: Bearer rk_live_…"Limit sa počíta na kľúč v kĺzavom okne 1 minúty:
Pri prekročení príde 429 rate_limit_exceeded s hlavičkou Retry-After (o koľko sekúnd to skúsiť znova) a poľom retryAfterSeconds. Hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset prídu pri odmietnutí.
| HTTP | error | Význam |
|---|---|---|
| 401 | missing_or_invalid_authorization | Chýba hlavička Authorization alebo kľúč nemá tvar rk_live_ + 24 znakov |
| 401 | invalid_api_key | Taký kľúč neexistuje |
| 401 | api_key_revoked | Kľúč bol zrušený v nástenke |
| 401 | api_key_expired | Kľúču uplynula platnosť (expiresAt) |
| 402 | trial_ended | Prevádzke skončila skúšobná doba — 30 dní alebo 50 rezervácií (used, limit, resetAt = koniec skúšky); nové rezervácie až po výbere plánu |
| 402 | monthly_limit_exceeded | Prevádzka vyčerpala mesačný počet rezervácií partnerského plánu (used, limit, resetAt) |
| 403 | insufficient_scope | Kľúč nemá potrebné oprávnenie (required, have) |
| 403 | manual_requires_app | „manual: true“ smie poslať len prihlásený človek z appky Terminuj, nie API kľúč |
| 404 | not_found | Rezervácia, voľno alebo webhook v tejto prevádzke neexistuje (aj service_not_found) |
| 409 | slot_conflict | Termín je medzitým obsadený; pri vytvorení prídu aj suggestedAlternatives |
| 409 | already_cancelled | Stav rezervácie zmenu nedovolí (aj already_completed, cannot_cancel, not_reschedulable, already_confirmed, cannot_confirm) |
| 422 | invalid_body | Telo požiadavky nesedí so schémou — podrobnosti v detail |
| 422 | consent_required | Prevádzka vyžaduje súhlas so začatím služby pred uplynutím lehoty na odstúpenie a chýba serviceStartConsent: true |
| 422 | start_in_past | Začiatok je v minulosti (aj outside_working_hours = mimo otváracích hodín) |
| 429 | rate_limit_exceeded | Prekročený limit požiadaviek kľúča — pozri časť 5 |
| 429 | daily_cap_reached | Prevádzka dosiahla denný strop verejných rezervácií (posledných 24 h) — zápis kľúčom sa ráta rovnako ako formulár |
Ak chcete, aby vám Terminuj sám oznámil novú, zrušenú alebo presunutú rezerváciu, pozri /docs/webhooks — podpis HMAC SHA-256, opakovania po 1 min, 5 min, 30 min a 2 h, ukážky kódu.
Webhooky sa dajú spravovať aj cez API: GET/POST /api/v1/webhooks, GET/DELETE /api/v1/webhooks/{id} a GET /api/v1/webhooks/{id}/deliveries (záznam doručení).
Chyba alebo požiadavka na novú funkciu: vass@vassweb.com.