Rýchly štart s REST API Collabin: prvé požiadavky za 10 minút

REST API Collabin vám poskytuje programový prístup k používateľom, tímom, typom dovoleniek a žiadostiam o dovolenku vašej organizácie — všetko, čo potrebujete na vytváranie reportov, synchronizáciu HR systémov alebo automatizáciu schvaľovania. Tento rýchly úvod vás dovedie od nuly k prvým autentifikovaným požiadavkám za približne desať minút.

Čo budete potrebovať

Účet Collabin v pláne Pro (externé API je funkciou plánu Pro).
Administrátorský prístup do prehľadu vašej organizácie.
curl alebo akýkoľvek HTTP klient.

Krok 1: Vygenerujte API kľúč

Prihláste sa do svojho prehľadu Collabin a otvorte API kľúče.
Vytvorte nový kľúč. Vyberte, či má byť iba na čítanie, alebo môže aj zapisovať (vytvárať dovolenky, meniť stavy). Pokiaľ konkrétne nepotrebujete zápis, dajte prednosť kľúču iba na čítanie.
Kľúč si okamžite skopírujte — vyzerá ako clb_4f8a… a zobrazí sa iba raz. Collabin uchováva iba jeho hash; ak kľúč stratíte, zrušte ho a vygenerujte nový.

Uchovávajte kľúč ako heslo: v premenných prostredia alebo v správcovi tajomstiev, nikdy v zdrojovom kóde.

Krok 2: Vykonajte prvú požiadavku

API je dostupné na https://api.collabin.eu s prefixom /v1 a autentifikuje sa pomocou hlavičky X-API-Key:

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

Odpovede pre zoznamy majú spoločnú obálku s metadátami stránkovania:

{
  "data": [
    { "id": 7, "name": "Ján Novák", "email": "jan@example.com" }
  ],
  "total": 134,
  "limit": 50,
  "offset": 0
}

Cez výsledky sa môžete posúvať pomocou limit a offset — predvolená veľkosť strany je 50, maximálna 500:

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

Endpointy v skratke

Metóda a cesta	Čo robí
`GET /v1/users`	Zoznam používateľov
`GET /v1/users/:id`	Získanie jedného používateľa
`GET /v1/users/:id/leaves`	Zoznam dovoleniek používateľa
`GET /v1/teams`	Zoznam tímov
`GET /v1/teams/:id`	Získanie jedného tímu
`GET /v1/leave-types`	Zoznam typov dovoleniek
`GET /v1/leaves`	Zoznam žiadostí o dovolenku (s možnosťou filtrovania)
`GET /v1/leaves/:id`	Získanie jednej žiadosti o dovolenku
`POST /v1/leaves`	Vytvorenie žiadosti o dovolenku (kľúč so zápisom)
`PUT /v1/leaves/:id/status`	Schválenie alebo zamietnutie žiadosti (kľúč so zápisom)
`GET /v1/calendar`	Kalendárové zobrazenie schválených dovoleniek

Krok 3: Filtrovanie žiadostí o dovolenku

GET /v1/leaves akceptuje viacero parametrov dopytu, ktoré možno voľne kombinovať:

user_id — obmedzenie na jednu osobu
start a end — rozsah dátumov, formát YYYY-MM-DD
status — napr. PENDING, APPROVED, REJECTED
updated_since — časová značka RFC 3339, ideálna na inkrementálnu synchronizáciu

Napríklad všetko schválené tohto leta:

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"

Úloha inkrementálnej synchronizácie potrebuje iba to, čo sa zmenilo od jej posledného spustenia:

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

Krok 4: Vytvorenie a schválenie dovolenky (kľúče so zápisom)

Vytvorenie žiadosti — začína v stave PENDING:

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": "Letná dovolenka"
  }'

Schválenie (alebo zamietnutie):

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

Na zamietnutie odošlite "status": "REJECTED" a voliteľne "rejection_reason". Obe operácie spustia príslušné webhook udalosti (leave.created, leave.status_changed), takže čokoľvek, čo ste postavili na webhookoch, reaguje aj na zmeny vyvolané cez API.

Dobré vedieť

Limit požiadaviek: 120 za minútu. Pri nárazoch spomaľte a skúste znova; pri veľkých exportoch dávajte prednosť väčším stranám pred väčším počtom požiadaviek.
Izolácia tenantov: kľúč vidí výhradne organizáciu, pre ktorú bol vydaný — nič sa nekonfiguruje a neexistuje spôsob, ako sa dostať mimo nej.
Polovičné dni: pri vytváraní jednodňovej dovolenky, ktorá pokrýva iba polovicu dňa, odošlite "is_half_day": true.
Zrušenie: vymazanie kľúča v prehľade ho okamžite deaktivuje. Kľúče obmieňajte, keď niekto odíde z tímu.

Kam ďalej

Skombinujte API s kalendárovými feedmi pre konzumentov iba na čítanie, ktorí potrebujú len udalosti, a s webhookmi, keď preferujete, aby vám dáta boli odosielané, než aby ste ich opytovali.