System HRappka udostępnia interfejs API, który pozwala na integrację z zewnętrznymi systemami (np. CRM, stronami WWW, narzędziami typu n8n czy Make). Poniżej znajdziesz wszystkie kluczowe informacje dotyczące procesu wdrożenia, autoryzacji, dobrych praktyk oraz możliwości i ograniczeń naszego API.

Oficjalna dokumentacja API HRappka dostępna jest pod adresem: Dokumentacja API Hrappka.

1. Jak uzyskać dostęp do API? (Krok po kroku) #

Dostęp do API jest całkowicie bezpłatny i dostępny dla każdego aktywnego użytkownika systemu. Aby rozpocząć integrację, wykonaj 3 proste kroki:

1. Wypełnij ankietę zgłoszeniową: Prześlij [Ankietę dostępu do API HRappka].
2. Utwórz konto techniczne: W panelu HRappka stwórz nowego użytkownika przeznaczonego wyłącznie do integracji (np. api@twojafirma.pl) i nadaj mu rolę z dostępem tylko do wybranych modułów. Dlaczego to ważne? Odseparowanie konta technicznego od prywatnych kont pracowników zapobiega przerwaniu integracji w przypadku rotacji personelu lub zmiany haseł użytkowników.
3. Przekaż dane integratorowi: Osoba wdrażająca połączenie potrzebuje 3 danych:
   • Adresu e-mail konta technicznego,
   • Hasła do konta technicznego,
   • companyId – unikalnego identyfikatora Twojej firmy, który znajdziesz w lewym dolnym rogu panelu po zalogowaniu.

2. Autoryzacja i tokeny (JWT) #

W systemie HRappka nie generujemy stałych kluczy API (API Key). Autoryzacja opiera się na bezpiecznym standardzie JWT (JSON Web Token) przypisanym do konta użytkownika technicznego.

3. Jak przebiega logowanie? #

W celu uzyskania tokenu należy wysłać zapytanie POST na endpoint /api/v1/auth/login z podaniem danych logowania oraz companyId. Każde kolejne zapytanie wymaga przesyłania nagłówka HTTP: Authorization: Bearer <TWÓJ_JWT_TOKEN>

4. Wygaśnięcie i odświeżanie tokena #

Podczas pierwszego uwierzytelniania API zwraca dwa tokeny: Access Token oraz Refresh Token.

• Access Token ma domyślny czas ważności wynoszący 1 godzinę. Po jego wygaśnięciu każda próba wykonania zapytania zwróci błąd HTTP 401 Unauthorized.
• Refresh Token posiada dłuższy okres ważności i służy do odnawiania dostępu bez konieczności ponownego podawania danych logowania.

W przypadku wygaśnięcia Access Tokena dostępne są dwa sposoby na odzyskanie dostępu do API:

1. Ponowne zalogowanie (Standardowa autoryzacja)Alternatywnie dostęp można odzyskać poprzez ponowne uwierzytelnienie. W tym celu należy wysłać żądanie do endpointu /api/v1/auth/login, podając w parametrach login oraz hasło do konta technicznego.
2. Użycie tokena odświeżającego (Refresh Token)Aby uzyskać nowy zestaw tokenów bez przesyłania loginu i hasła, należy wysłać żądanie do endpointu /api/v1/auth/refresh, przekazując w parametrach posiadany Refresh Token.

Uwaga:

Obsługa błędów ,w tym wychwycenie błędu 401 Unauthorized, jest po stronie użytkownika korzystającego z API.

5. Dokumentacja i zasoby techniczne #

• Oficjalna dokumentacja API: Znajdziesz ją pod adresem Dokumentacja API Hrappka.
• Limity zapytań (Rate Limiting): Nie stosujemy sztywnych limitów na liczbę wywołań na sekundę. Ruch jest jednak monitorowany pod kątem obciążenia serwera, dlatego przy pobieraniu dużych zbiorów danych zalecamy stosowanie cache’owania po stronie zewnętrznej aplikacji.