Dokumentacja API
Wprowadzenie
Błędy, limity i paginacja
API używa konwencjonalnych kodów HTTP oraz przewidywalnego formatu błędu. Poniżej komplet kodów, zasady rate limitingu i sposób stronicowania list.
Format błędu
Błędy zwracamy w JSON z czytelnym opisem i maszynowym kodem, po którym bezpiecznie rozgałęziać logikę integracji:
{
"error": "klucz nie ma wymaganego zakresu",
"code": "forbidden_scope"
}Kody odpowiedzi
Kody z zakresu 2xx oznaczają sukces, 4xx — błąd po stronie żądania (dane, uprawnienia, limit).
| HTTP | code | Znaczenie |
|---|---|---|
401 | unauthorized | brak lub nieprawidłowy klucz API. |
403 | forbidden_scope | klucz nie ma zakresu wymaganego przez endpoint. |
404 | not_found | zasób nie istnieje w tym tenancie. |
410 | pii_deleted | dane osobowe zostały usunięte (RODO) — kartoteka niedostępna. |
422 | incomplete / parse_failed / export_failed | dane niekompletne lub błąd przetwarzania (np. brak wymaganych pól przy eksporcie ZUS). |
429 | rate_limited | przekroczony limit żądań — patrz rate limiting. |
Rate limiting
Obowiązuje limit 120 żądań / min / klucz. Po jego przekroczeniu API zwraca 429 rate_limited. Do każdej odpowiedzi dołączamy nagłówki pozwalające sterować tempem żądań:
X-RateLimit-Limit | maksymalna liczba żądań w oknie. |
X-RateLimit-Remaining | liczba żądań pozostałych w bieżącym oknie. |
X-RateLimit-Reset | moment zresetowania limitu (epoch, sekundy). |
Ponawianie żądań
Po otrzymaniu429 odczekaj do czasu z nagłówka X-RateLimit-Reset i ponów żądanie (zalecany backoff wykładniczy). Nie odpytuj w pętli bez opóźnienia.Paginacja
Endpoint GET /employees zwraca dane stronami. Steruj parametrami page (dom. 1) i pageSize (dom. 50, maks. 200). Odpowiedź zawiera metadane stronicowania:
{
"data": [ /* ... */ ],
"page": 1,
"pageSize": 50,
"total": 130,
"totalPages": 3
}Iteruj po stronach aż page osiągnie totalPages. Do synchronizacji przyrostowej używaj filtra updatedSince (patrz endpoint listy pracowników).
curl -H "Authorization: Bearer onb_..." \
"https://www.onboardly.work/api/v1/employees?updatedSince=2026-07-01&page=2&pageSize=100"Audyt PII
Każdy odczyt lub eksport kartoteki z odszyfrowanymi danymi osobowymi tworzy wpis audytu (RODO art. 30). Odczyty listy (bez PII) nie generują wpisu.