Przejdź do treści
RolePark
PL
O produkcie ↗

API, webhooki, SCIM i logowanie jednokrotne SAML

RolePark łączy się z Twoimi systemami na cztery sposoby: REST API z kluczami o wąskich uprawnieniach, podpisane webhooki, SCIM 2.0 do tworzenia i dezaktywacji kont oraz logowanie jednokrotne SAML 2.0. Konfiguruje je administrator firmy.

Zaktualizowano:

Sprawdzone przez zespół RolePark

W skrócie

  • REST API z 7 zakresami: odczyt osób, zatrudnień, publicznych ofert i aplikacji oraz dodawanie kandydatów; 120 żądań na minutę na klucz.
  • Webhooki dla 8 zdarzeń, podpisane HMAC-SHA256: łącznie 6 prób doręczenia (5 ponowień).
  • SCIM 2.0 dla kont użytkowników i logowanie jednokrotne SAML 2.0 z możliwością wyłączenia logowania hasłem.
  • Dostępne w każdym planie, także w Free; klucze wydaje i SSO ustawia tylko administrator firmy.

REST API

API działa pod adresem https://rolepark.com/api/v1. Każde żądanie przekazuje klucz w nagłówku Authorization jako token bearer. Klucze tworzy administrator firmy na stronie „Integracje” i nadaje każdemu tylko potrzebne zakresy.

Zakresy

people.read, employments.read, vacancies.read, applications.read, candidates.write, webhooks.manage, scim.manage. Klucz daje zewnętrznemu systemowi dostęp do danych firmy niezależnie od ról, dlatego wydaje go tylko administrator, a zakresy są wąskie.

Co API odczytuje i zapisuje

  • Odczyt osób i zatrudnień z filtrem „zmienione od” do przyrostowej synchronizacji.
  • Odczyt publicznych ofert i aplikacji z filtrem po statusie lub ofercie.
  • Dodawanie kandydatów. Wymagane są imię, nazwisko, źródło oraz e-mail, telefon lub LinkedIn. Jeśli kandydat już istnieje, RolePark uzupełnia tylko puste pola i nie nadpisuje reszty.
  • Odczyt kart kandydatów przez klucz jest celowo niedostępny.

Limity, klucze i dokumentacja

  • 120 żądań na minutę na klucz; powyżej API odpowiada 429 z Retry-After.
  • Stronicowanie: domyślnie 25 rekordów, maksymalnie 100.
  • Klucz jest pokazywany raz. RolePark przechowuje tylko jego skrót SHA-256, więc nie może go pokazać ponownie; odwołany klucz przestaje działać natychmiast.
  • Opis OpenAPI 3 jest pod adresem /api/v1/openapi.json i otwiera się tym samym kluczem.

Webhooki

RolePark wysyła żądanie POST na Twój adres HTTPS, gdy nastąpi jedno z tych zdarzeń: employment.created, employment.updated, employment.ended, application.stage_changed, document.signed, interview.scheduled, interview.cancelled, scorecard.submitted.

  • Każde żądanie jest podpisane: sha256=HMAC(secret, timestamp + "." + body). Sprawdzaj podpis na surowej treści żądania. Sekret jest pokazywany raz i można go wymienić.
  • Akceptowane są tylko adresy HTTPS na publicznych hostach. Odbiorca musi odpowiedzieć 2xx w ciągu 10 sekund; przekierowania nie są wykonywane.
  • Nieudane doręczenie jest ponawiane po 30 sekund, 2 minutach, 10 minutach, 1 godzinie i 6 godzinach. Po ostatniej próbie adres zostaje wyłączony, co widać na stronie „Integracje”.
  • Dziennik pokazuje ostatnie 50 doręczeń ze statusem i błędem; doręczenie można ponowić ręcznie.

SCIM 2.0: konta z Twojego dostawcy tożsamości

SCIM to standard IETF do tworzenia, zmiany i usuwania kont użytkowników z dostawcy tożsamości (RFC 7643 i RFC 7644). Adres SCIM w RolePark to https://rolepark.com/api/scim/v2; wymaga klucza API z zakresem scim.manage.

  • Obsługiwane: zasób Users (lista, tworzenie, odczyt, zastąpienie, zmiana i usunięcie) oraz ServiceProviderConfig.
  • Filtr userName eq, stronicowanie przez startIndex i count, do 200 na stronę.
  • Usunięcie użytkownika lub active = false dezaktywuje konto. Nic nie jest kasowane: historia, podpisy i oceny zostają. Ostatniego aktywnego administratora nie można dezaktywować.
  • Nowi użytkownicy SCIM dostają rolę „Pracownik”; inne role administrator nadaje w RolePark. Grupy nie są obsługiwane.

Logowanie jednokrotne SAML 2.0

Administrator firmy konfiguruje logowanie jednokrotne w „Ustawienia” → „Firma”. RolePark pokazuje swoje dane dla Twojego dostawcy tożsamości — Entity ID dostawcy usług, adres ACS i metadane — a Ty wpisujesz Entity ID dostawcy tożsamości, jego adres logowania HTTPS i certyfikat podpisu.

  • Dostawca tożsamości musi podpisywać asercje. Po zapisaniu RolePark pokazuje tylko odcisk certyfikatu.
  • RolePark odczytuje e-mail i imię z nazw atrybutów, których domyślnie używają Okta i Microsoft Entra ID (Azure AD).
  • Konto nie powstaje przy pierwszym logowaniu: najpierw zaproś osoby lub utwórz je przez SCIM.
  • Gdy SSO działa, administrator może wyłączyć logowanie hasłem w firmie. Jeden dostawca tożsamości na firmę.

Klucze analityczne dla Power BI i Excela

Z dostępem do ATS administrator może wydać osobne klucze do kanałów JSON i CSV ze statystykami ofert i osób. Power BI i Excel czytają je jako źródło danych z sieci. Kanał ofert zawiera tylko liczby — aplikacje według etapów, zatrudnienia i czas zatrudnienia — bez danych osobowych kandydatów.

Inne połączenia

Asystenci AI, tacy jak Claude i ChatGPT, łączą się przez MCP z uprawnieniami danej osoby, a Djinni — kluczem API z Twojego konta Djinni. Oba mają osobne instrukcje.

Częste pytania

Czy API jest dostępne w planie Free?

Tak. API, webhooki, SCIM i logowanie jednokrotne SAML są dostępne w każdym planie. Klucze analityczne dla Power BI wymagają dostępu do ATS.

Czy mogę odczytywać kandydatów przez API?

Nie, celowo. Klucz może dodawać kandydatów (candidates.write) oraz odczytywać osoby, zatrudnienia, publiczne oferty i aplikacje.

Czy RolePark obsługuje grupy SCIM?

Nie. RolePark obsługuje zasób SCIM Users. Role nadaje się w RolePark; nowi użytkownicy SCIM zaczynają z rolą pracownika.

Czy logowanie SAML tworzy konta automatycznie?

Nie. Osoba musi już mieć konto — z zaproszenia lub przez SCIM. Nieznane adresy e-mail są odrzucane.

Jak zweryfikować webhook?

Oblicz HMAC-SHA256 sekretem webhooka ze znacznika czasu, kropki i surowej treści żądania, a następnie porównaj z podpisem w żądaniu.

Źródła

Utwórz przestrzeń robocząNapisz do zespołu RolePark