Nyilvános API

Minden kérésnek tartalmaznia kell az Authorization: Bearer rk_live_… fejlécet. A kulcsot az irányítópulton hozza létre → API-kulcsok. A teljes kulcs csak egyszer jelenik meg — mentse el környezeti változóba vagy jelszókezelőbe; nálunk csak az ujjlenyomata tárolódik. A kulcs egyetlen vállalkozáshoz tartozik, ezért a vállalkozást a kérésekben nem kell megadni.

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

A kulcs létrehozásakor kiválasztja a jogosultságokat — csak azokat adja meg, amelyekre a csatlakozásnak valóban szüksége van.

Szabad időpontok

Minden napra visszaadja, hogy nyitva van-e, valamint a szabad időpontokat a foglalások, a szabadnapok és a szolgáltatás szünetei levonása után; legkorábban most + 2 óra. from = nap ÉÉÉÉ-HH-NN formátumban (alapértelmezés: ma), days 1–62 (alapértelmezés: 28), opcionálisan staff = egy adott munkatárs. Az időzóna 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"

Foglalás létrehozása

startAt UTC-ben, a végén Z betűvel (12:00Z = nyáron 14:00 Pozsonyban). Az ügyfél e-mail-címe kötelező; nélküle csak "channel": "telefon" esetén (telefonon felvett időpont — elég a név és a telefonszám). A weboldala nyilvános űrlapjáról érkező időpontokat "channel": "web" értékkel küldje; ha a vállalkozás megköveteli a hozzájárulást a szolgáltatás elállási határidő lejárta előtti megkezdéséhez, adja hozzá ezt: "serviceStartConsent": true, aszerint, hogy az ügyfél bejelölte-e a jelölőnégyzetet (különben 422 consent_required). Opcionálisan preferredStaffId, customer.notes és locale (sk | en | cs | hu | de | es — az API-üzenetek és az ügyfélnek e foglalással kapcsolatban küldött további üzenetek nyelve; alapértelmezés a vállalkozás nyelve). Ha ugyanazt a szolgáltatást és időpontot ugyanazzal az e-mail-címmel 10 percen belül újra elküldi, ugyanazt a foglalást kapja vissza (dupla kattintás, hálózati kiesés).

Az API-n keresztüli foglalásnál a Terminuj nem küld visszaigazoló e-mailt az ügyfélnek — a visszaigazolást az Ön csatlakozása küldi. A tulajdonos a vállalkozás beállításai szerint kap értesítést. A foglalás beleszámít a csomag havi keretébe.

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"
    }
  }'

Foglalás lemondása, áthelyezése vagy megerősítése

Egyetlen útvonal, az action mező szerint: {"action": "cancel", "reason": "…"}, {"action": "reschedule", "startAt": "…Z"} vagy {"action": "confirm"} (csak előlegre váró időpontnál). Lemondáskor az ügyfél e-mailt kap; áthelyezéskor és megerősítéskor akkor, ha a vállalkozásnál be vannak kapcsolva a visszaigazoló e-mailek.

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" }'

Ügyfelek keresése

A search a névben, az e-mail-címben és a telefonszámban keres.

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

A további útvonalakat (foglalások listája from/to/status/createdFrom szűrővel, szolgáltatások, időblokkolás /time-off, webhookok) az OpenAPI írja le.

A listák paraméterei: ?limit=25&cursor=<id>. Alapértelmezés 25, legfeljebb 100 oldalanként (foglalások, ügyfelek, webhook-kézbesítések); szolgáltatásoknál alapértelmezés 50, legfeljebb 200. A válasz tartalmazza: { pagination: { nextCursor, hasMore, limit } }.

# Első oldal
curl "https://app.terminuj.com/api/v1/bookings?limit=25" -H "Authorization: Bearer rk_live_…"

# Következő oldal (nextCursor az előző válaszból)
curl "https://app.terminuj.com/api/v1/bookings?limit=25&cursor=<nextCursor>" -H "Authorization: Bearer rk_live_…"

A korlát kulcsonként, 1 perces csúszó ablakban számít:

• Olvasás (booking:read, customer:read, service:read): percenként 600 kérés
• Írás (booking:write, webhook:manage): percenként 60 kérés

Túllépéskor 429 rate_limit_exceeded választ kap a Retry-After fejléccel (hány másodperc múlva próbálja újra) és a retryAfterSeconds mezővel. Az X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejlécek az elutasításkor érkeznek.

Ha szeretné, hogy a Terminuj maga értesítse az új, lemondott vagy áthelyezett foglalásokról, lásd: /docs/webhooks — HMAC SHA-256 aláírás, újrapróbálás 1 perc, 5 perc, 30 perc és 2 óra után, kódpéldák.

A webhookok az API-n keresztül is kezelhetők: GET/POST /api/v1/webhooks, GET/DELETE /api/v1/webhooks/{id} és GET /api/v1/webhooks/{id}/deliveries (kézbesítési napló).

Hiba vagy új funkció kérése: podpora@terminuj.com.