Szybki start z REST API Collabin: pierwsze zapytania w 10 minut

REST API Collabin zapewnia programowy dostęp do użytkowników, zespołów, typów urlopów i wniosków urlopowych Twojej organizacji — wszystkiego, czego potrzebujesz do budowania raportów, synchronizacji systemów HR lub automatyzacji zatwierdzeń. Ten przewodnik quickstart przeprowadzi Cię od zera do pierwszych uwierzytelnionych zapytań w około dziesięć minut.

Czego będziesz potrzebować

Konta Collabin w planie Pro (zewnętrzne API jest funkcją planu Pro).
Dostępu administratora do panelu Twojej organizacji.
curl lub innego klienta HTTP.

Krok 1: Wygeneruj klucz API

Zaloguj się do panelu Collabin i otwórz Klucze API.
Utwórz nowy klucz. Wybierz, czy ma być tylko do odczytu, czy może też zapisywać (tworzyć urlopy, zmieniać statusy). Wybieraj tylko do odczytu, jeśli nie potrzebujesz konkretnie zapisu.
Skopiuj klucz natychmiast — wygląda tak: clb_4f8a… i jest wyświetlany tylko raz. Collabin przechowuje tylko jego hash; jeśli go zgubisz, unieważnij go i wygeneruj nowy.

Przechowuj klucz jak hasło: w zmiennych środowiskowych lub menedżerze sekretów, nigdy w repozytorium kodu.

Krok 2: Wykonaj pierwsze zapytanie

API znajduje się na https://api.collabin.eu pod prefiksem /v1 i uwierzytelnia za pomocą nagłówka X-API-Key:

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

Odpowiedzi list mają wspólną kopertę z metadanymi paginacji:

{
  "data": [
    { "id": 7, "name": "Jan Kowalski", "email": "jan@example.com" }
  ],
  "total": 134,
  "limit": 50,
  "offset": 0
}

Strony wyników przeglądasz za pomocą limit i offset — domyślny rozmiar strony to 50, maksymalny 500:

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

Endpointy w skrócie

Metoda i ścieżka	Co robi
`GET /v1/users`	Lista użytkowników
`GET /v1/users/:id`	Pobranie jednego użytkownika
`GET /v1/users/:id/leaves`	Lista urlopów użytkownika
`GET /v1/teams`	Lista zespołów
`GET /v1/teams/:id`	Pobranie jednego zespołu
`GET /v1/leave-types`	Lista typów urlopów
`GET /v1/leaves`	Lista wniosków urlopowych (z filtrowaniem)
`GET /v1/leaves/:id`	Pobranie jednego wniosku
`POST /v1/leaves`	Utworzenie wniosku urlopowego (klucz z zapisem)
`PUT /v1/leaves/:id/status`	Zatwierdzenie lub odrzucenie wniosku (klucz z zapisem)
`GET /v1/calendar`	Widok kalendarza zatwierdzonych urlopów

Krok 3: Filtruj wnioski urlopowe

GET /v1/leaves przyjmuje kilka parametrów zapytania, które można swobodnie kombinować:

user_id — ogranicza do jednej osoby
start i end — zakres dat, w formacie YYYY-MM-DD
status — np. PENDING, APPROVED, REJECTED
updated_since — znacznik czasu RFC 3339, idealny do synchronizacji przyrostowej

Na przykład wszystko zatwierdzone tego lata:

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"

Zadanie synchronizacji przyrostowej potrzebuje tylko tego, co zmieniło się od ostatniego uruchomienia:

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

Krok 4: Utwórz i zatwierdź urlop (klucze z zapisem)

Tworzenie wniosku — zaczyna ze statusem 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": "Urlop letni"
  }'

Zatwierdzenie (lub odrzucenie):

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

Aby odrzucić, wyślij "status": "REJECTED" i opcjonalnie "rejection_reason". Obie operacje wywołują odpowiednie zdarzenia webhooków (leave.created, leave.status_changed), więc wszystko, co zbudowałeś na webhookach, reaguje również na zmiany dokonane przez API.

Warto wiedzieć

Limit zapytań: 120 na minutę. Przy skokach ruchu zwolnij i spróbuj ponownie; przy dużych eksportach wybieraj większe strony zamiast większej liczby zapytań.
Izolacja tenantów: klucz widzi wyłącznie organizację, dla której został wystawiony — nic nie trzeba konfigurować i nie ma sposobu na dostęp do innych organizacji.
Pół dnia: przy tworzeniu jednodniowego urlopu obejmującego tylko pół dnia przekaż "is_half_day": true.
Unieważnianie: usunięcie klucza w panelu powoduje natychmiastowe zatrzymanie jego działania. Rotuj klucze, gdy ktoś odchodzi z zespołu.

Co dalej

Połącz API z kanałami kalendarza dla odbiorców tylko do odczytu, którym wystarczają zdarzenia, oraz z webhookami, gdy wolisz otrzymywać powiadomienia niż odpytywać.