API Onboardly: jak połączyć onboarding z programem kadrowym i ZUS

Nazywam się Katarzyna Wrona i od kilkunastu lat pracuję w kadrach i płacach. Dziś po stronie Onboardly. Informatycy naszych klientów i biura rachunkowe pytają mnie w kółko o jedno: „czy to się spina z naszym programem kadrowym, czy znowu będziemy przeklejać dane ręcznie?”. Spina się. Onboardly ma publiczne API maszyna do maszyny (/api/v1), a w tym artykule pokażę, jak z niego korzystać. Bez owijania w bawełnę, na konkretnych żądaniach.

Po co komu API w onboardingu?

Onboarding zbiera komplet danych pracownika: dane osobowe, adresy, dokument tożsamości, numer konta, dane do umowy i do ZUS. Te same dane potrzebne są potem w programie kadrowym, na liście płac i w zgłoszeniu do ZUS. Bez integracji ktoś to przepisuje ręcznie, a każde przepisywanie to godziny pracy i ryzyko literówki w numerze konta albo w kodzie tytułu ubezpieczenia.

API pozwala ten most zautomatyzować w obie strony: pobrać gotową kartotekę z Onboardly do swojego systemu i odesłać zmiany, które kadrowa wprowadziła u siebie. Dane wpisane raz, przy onboardingu przez samego pracownika, żyją dalej same.

Uwierzytelnianie kluczem API

API nie działa na sesji przeglądarki. Autoryzujesz się kluczem API wystawianym per firma (tenant), a nie per użytkownik. Klucz tworzysz i odwołujesz w panelu, w sekcji Ustawienia → Klucze API. Kilka rzeczy, o których warto wiedzieć zawczasu:

• Pełną wartość klucza (onb_...) widzisz tylko raz, w momencie utworzenia. W bazie trzymamy wyłącznie jej skrót (SHA-256), więc zapisz klucz w bezpiecznym miejscu od razu.
• Klucz podajesz w nagłówku Authorization: Bearer onb_... albo X-Onboardly-Api-Key: onb_....
• Zakresy (scopes) ograniczają, co klucz może zrobić: read:employees, write:employees, read:payroll, read:invoices. Brak zakresu kończy się odpowiedzią 403 forbidden_scope. Radzę wydawać klucze możliwie wąskie. Integracja, która tylko czyta kartoteki, nie potrzebuje prawa zapisu.
• Limit zapytań to 120 żądań na minutę na klucz (po przekroczeniu 429 rate_limited z nagłówkami X-RateLimit-*).
• Każdy odczyt danych wrażliwych jest audytowany, bo tego wymaga art. 30 RODO. Dzięki temu zawsze wiadomo, który klucz i kiedy sięgnął po PESEL czy adres.

Odczyt danych (OUT): pobieranie kartoteki i plików

Najczęstszy scenariusz: Twój system pyta „co się zmieniło od ostatniej synchronizacji” i pobiera tylko nowe rekordy. Do dyspozycji masz m.in.:

• GET /api/v1/employees: lista pracowników (bez danych wrażliwych), z filtrami status, companyId, updatedSince i stronicowaniem.
• GET /api/v1/employees/{id}: pełna kartoteka z odszyfrowanymi danymi (to żądanie trafia do audytu PII).
• GET /api/v1/employees/{id}/export?format=kedu|optima|symfonia|csv|xlsx: gotowy plik do zaczytania w konkretnym programie.
• GET /api/v1/payroll/{yearMonth}: listy płac w modelu SoCap (JSON).
• GET /api/v1/invoices oraz GET /api/v1/settlements/{id}: rachunki, faktury i rozliczenie projektu z prowizją.

Przykład. Pobierz wszystkich zmienionych od 1 lipca:

curl -H "Authorization: Bearer onb_..." \
  "https://onboardly.work/api/v1/employees?updatedSince=2026-07-01&pageSize=50"

Zapis danych (IN): odesłanie zmian z programu kadrowego

Kierunek do Onboardly jest równie ważny. Kadrowa poprawia oddział NFZ albo numer konta u siebie, a zmiana wraca do teczki:

• POST /api/v1/employees/import: podgląd dopasowania (nic nie zapisuje, tylko pokazuje, kto pasuje).
• POST /api/v1/employees/import/confirm: merge zachowawczy dopasowanych rekordów.
• PATCH /api/v1/employees/{id}: punktowa aktualizacja pól kadrowych: stanowisko, wynagrodzenie, stawka, daty, nfzCode, dane US, bank, NIP, PIT-2, rezygnacja z PPK.
• POST /api/v1/employees/{id}/zus/deregister: ustawia datę zakończenia i zwraca gotowy KEDU ZWUA (wyrejestrowanie z ZUS).

Jedna rzecz, o której muszę uprzedzić, bo pada w co drugiej rozmowie: zakres write:employees nie zakłada nowych pracowników. Import i PATCH tylko aktualizują osoby już dopasowane (po PESEL, a w drugiej kolejności po imieniu, nazwisku i dacie urodzenia). Zakładanie kartoteki od zera to osobny proces onboardingu. I słusznie, bo tam zbieramy zgody i weryfikujemy tożsamość.

KEDU, czyli jeden plik do sześciu programów

Najczęściej i tak wszystko sprowadza się do ZUS. Onboardly generuje zgłoszenia ZUA (pełne ubezpieczenia) i ZZA (tylko zdrowotne) w formacie KEDU XML (schema ZUS 5.4). Ten sam plik czyta Płatnik, ePłatnik (PUE), Comarch Optima, InsERT Gratyfikant nexo, Symfonia i enova365: jeden eksport, sześć programów.

curl -H "Authorization: Bearer onb_..." \
  "https://onboardly.work/api/v1/employees/{id}/export?format=kedu" -o kedu.xml

Jeśli Twój program woli format natywny, mamy też eksport Optima XML (z numerem konta, którego KEDU nie zawiera), Symfonia XML oraz najszerszy zestaw danych w CSV/XLSX (35 kolumn, łącznie z PIT-2 i numerami zezwoleń). enova365 obsługujemy dodatkowo przez WebAPI, z pushem pracownika na żywo.

Webhooki: reaguj na zdarzenia zamiast odpytywać

Zamiast co chwilę pytać „czy już podpisane?”, możesz nasłuchiwać zdarzeń. Onboardly wysyła webhooki: onboarding.created, onboarding.completed, onboarding.signed, onboarding.fully_signed, kyc.passed, kyc.failed. Każdy jest podpisany HMAC-SHA256 (nagłówek X-Onboardly-Signature), a kolejka ma trwałe ponawianie (do 6 prób), więc chwilowa awaria Twojego endpointu nie gubi zdarzeń.

Czego API jeszcze nie robi (i dlaczego)

Nie obiecam Ci rzeczy, których zwyczajnie nie da się zrobić. ZUS nie udostępnia publicznego API do pobierania zwolnień lekarskich (e-ZLA), zgłoszonych członków rodziny (ZCNA) czy rozliczeń RCA/DRA. Te dane żyją w programie kadrowym i w PUE ZUS. Dlatego „ściąganie z ZUS” realizujemy jako dwukierunkowy sync z programem kadrowym, który pełni rolę mostu do ZUS. Bezpośredniego kanału z samym ZUS po prostu nie ma jak zbudować. Jest to na naszej mapie rozwoju i napiszę o tym, gdy ruszy.

Od czego zacząć

1. Wejdź w Ustawienia → Klucze API, wystaw klucz z minimalnym potrzebnym zakresem i zapisz go bezpiecznie.
2. Zacznij od jednego żądania GET /api/v1/employees?updatedSince=..., żeby zobaczyć strukturę danych.
3. Dołóż eksport KEDU dla jednego pracownika i przetestuj import do swojego programu.
4. Dopiero potem automatyzuj cały przepływ i podłącz webhooki.

Materiał ma charakter informacyjny. Zakres i nazwy pól API mogą się rozwijać. Aktualną, wiążącą specyfikację znajdziesz w dokumentacji technicznej Onboardly.