Collabin REST API gyorstalpaló: az első lekérések 10 perc alatt

A Collabin REST API programozott hozzáférést ad a szervezeted felhasználóihoz, csapataihoz, szabadságtípusaihoz és szabadságkérelmeihez — mindenhez, ami riportok építéséhez, HR-rendszerek szinkronizálásához vagy a jóváhagyások automatizálásához kell. Ez a gyorstalpaló nagyjából tíz perc alatt visz el a nulláról az első hitelesített lekérésekig.

Mire lesz szükséged

Collabin-fiókra Pro csomaggal (a külső API Pro-funkció).
Adminisztrátori hozzáférésre a szervezeted felületéhez.
curl-re vagy bármilyen HTTP-kliensre.

1. lépés: API-kulcs generálása

Jelentkezz be a Collabin felületére, és nyisd meg az API Kulcsok menüpontot.
Az Új API Kulcs gombbal hozz létre egy kulcsot. Döntsd el, hogy csak olvasásra jogosítson, vagy írásra is (szabadság létrehozása, státuszváltás). Hacsak nem kifejezetten írnod kell, válaszd a csak olvashatót.
A kulcsot azonnal másold ki — így néz ki: clb_4f8a…, és csak egyszer jelenik meg. A Collabin csak a hash-ét tárolja; ha elveszted, visszavonod és újat generálsz.

A kulcsot jelszóként kezeld: környezeti változó vagy secret manager, soha ne kerüljön verziókezelőbe.

2. lépés: Az első lekérés

Az API a https://api.collabin.eu címen él, /v1 prefix alatt, és az X-API-Key fejléccel hitelesít:

curl -s https://api.collabin.eu/v1/users \
  -H "X-API-Key: $COLLABIN_API_KEY"

A listázó válaszok közös borítékban érkeznek, lapozási metaadatokkal:

{
  "data": [
    { "id": 7, "name": "Kiss Janka", "email": "janka@example.com" }
  ],
  "total": 134,
  "limit": 50,
  "offset": 0
}

A limit és offset paraméterekkel lapozhatsz — az alapértelmezett oldalméret 50, a maximum 500:

curl -s "https://api.collabin.eu/v1/users?limit=100&offset=100" \
  -H "X-API-Key: $COLLABIN_API_KEY"

A végpontok egy pillantásra

Metódus és útvonal	Mire való
`GET /v1/users`	Felhasználók listázása
`GET /v1/users/:id`	Egy felhasználó lekérése
`GET /v1/users/:id/leaves`	Egy felhasználó szabadságai
`GET /v1/teams`	Csapatok listázása
`GET /v1/teams/:id`	Egy csapat lekérése
`GET /v1/leave-types`	Szabadságtípusok listázása
`GET /v1/leaves`	Szabadságkérelmek listázása (szűrhető)
`GET /v1/leaves/:id`	Egy kérelem lekérése
`POST /v1/leaves`	Kérelem létrehozása (írási kulcs)
`PUT /v1/leaves/:id/status`	Jóváhagyás vagy elutasítás (írási kulcs)
`GET /v1/calendar`	Jóváhagyott szabadságok naptárnézete

3. lépés: Szabadságkérelmek szűrése

A GET /v1/leaves több, szabadon kombinálható query-paramétert fogad:

user_id — egy adott személyre szűkít
start és end — dátumtartomány, YYYY-MM-DD formátumban
status — pl. PENDING, APPROVED, REJECTED
updated_since — RFC 3339 időbélyeg, inkrementális szinkronhoz ideális

Például minden nyárra jóváhagyott szabadság:

curl -s "https://api.collabin.eu/v1/leaves?status=APPROVED&start=2026-06-01&end=2026-08-31" \
  -H "X-API-Key: $COLLABIN_API_KEY"

Egy inkrementális szinkron-jobnak csak az kell, ami a legutóbbi futása óta változott:

curl -s "https://api.collabin.eu/v1/leaves?updated_since=2026-06-12T00:00:00Z" \
  -H "X-API-Key: $COLLABIN_API_KEY"

4. lépés: Szabadság létrehozása és jóváhagyása (írási kulcs)

Kérelem létrehozása — PENDING státuszban indul:

curl -s -X POST https://api.collabin.eu/v1/leaves \
  -H "X-API-Key: $COLLABIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 7,
    "leave_type_id": 1,
    "start_date": "2026-07-01T00:00:00Z",
    "end_date": "2026-07-05T00:00:00Z",
    "reason": "Nyári szabadság"
  }'

Jóváhagyása (vagy elutasítása):

curl -s -X PUT https://api.collabin.eu/v1/leaves/1337/status \
  -H "X-API-Key: $COLLABIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "APPROVED" }'

Elutasításhoz küldj "status": "REJECTED" értéket, és opcionálisan egy "rejection_reason" mezőt. Mindkét művelet elsüti a megfelelő webhook-eseményeket (leave.created, leave.status_changed), így minden, amit webhookokra építettél, az API-n keresztüli változásokra is reagál.

Jó tudni

Rate limit: percenként 120 kérés. Túllépésnél várj és próbáld újra; nagy exportoknál inkább nagyobb oldalméretet használj több kérés helyett.
Tenant-izoláció: egy kulcs kizárólag azt a szervezetet látja, amelyhez kiállították — nincs mit konfigurálni, és nincs mód átnyúlni máshová.
Fél napok: egynapos, fél napot fedő szabadságnál add át az "is_half_day": true mezőt.
Visszavonás: a felületen törölt kulcs azonnal érvénytelen. Rotáld a kulcsokat, ha valaki távozik a csapatból.

Merre tovább

Kombináld az API-t a naptár feedekkel, ha egy fogyasztónak csak eseményekre van szüksége, és a webhookokkal, ha lekérdezgetés helyett inkább értesítést szeretnél kapni.