Przewodnik dla partnerów dotyczący tworzenia integracji z HackerRank

Last updated: February 7, 2026

Przegląd

Ten dokument jest przeznaczony dla partnerów, którzy chcą opracować integrację z HackerRank for Work. Stale współpracujemy z dostawcami ATS, aby opracować integracje dla lepszego doświadczenia użytkownika. Ten dokument dostarczy Ci wszystkich informacji potrzebnych do samodzielnego opracowania integracji.

 

Tło

Niektórzy z naszych klientów korporacyjnych - tacy, którzy korzystają z HackerRank for Work Tests i Interviews na etapie oceny, korzystają również z innych systemów IT do zarządzania swoim ogólnym procesem rekrutacji. Systemy te mogą być systemami komercyjnymi gotowymi do użycia (COTS), takimi jak Oracle Taleo, Jobvite, Greenhouse, Lever, Kenexa, RecruiterBox itp., lub specjalnie opracowanymi systemami własnymi. Będziemy odnosić się do tych aplikacji łącznie jako Systemy Śledzenia Kandydatów (ATS).

Takie firmy często proszą o integrację między ich ATS a HackerRank for Work, aby rutynowe działania związane z zarządzaniem kandydatami mogły być wykonywane w ramach ich przepływu pracy ATS. Przykłady takich rutynowych działań obejmują (a) zaproszenie wybranych kandydatów do wykonania testu HackerRank for Work, (b) przegląd wyników testu dla takich kandydatów w ich ATS, (c) zaplanowanie sesji rozmowy kwalifikacyjnej HackerRank między inżynierem a wybranym kandydatem, (d) przegląd raportów z rozmów kwalifikacyjnych w interfejsie ATS itp. Dlatego najczęściej żądane punkty integracji obejmują pobieranie danych z istniejącego konta HackerRank for Work i wykonywanie określonych działań z poziomu interfejsu ATS. Mamy wywołania API, które pomogą wdrożyć te działania z poziomu interfejsu użytkownika ATS.

 

Ogólny przepływ pracy

Integracja zazwyczaj polega na dodaniu funkcjonalności do ATS za pomocą wtyczki lub dostosowania przy użyciu API HackerRank for Work. Najlepiej wyjaśnić to wizualnie za pomocą następujących diagramów.

Zastosowane konwencje w poniższych przepływach pracy:

 

Konfiguracja integracji - Jednorazowa czynność

Uwaga: Każda oficjalna integracja ATS będzie miała sekcję w HackerRank for Work, gdzie administrator konta każdej firmy będzie mógł wygenerować klucz. Twój ATS pojawi się w następującej lokalizacji: https://www.hackerrank.com/work/settings/api 

Ogólny przebieg testu

Ogólny przepływ CodePair (API wywiadów)

Proces integracji

Zarejestruj się na bezpłatny okres próbny

Przejdź do https://www.hackerrank.com/work/signup, aby zarejestrować się na bezpłatny 14-dniowy okres próbny naszego produktu. To konto będzie wymagane do eksploracji naszego API (patrz poniżej) i testowania integracji.

Eksploruj nasze API

Posiadamy proste RESTful API, które będzie stanowić podstawę do integracji. Powinieneś zacząć naukę o naszym API tutaj:

https://www.hackerrank.com/work/apidocs 

Uwaga: Powyższa dokumentacja jest napisana z myślą o naszych końcowych klientach. Powinieneś eksplorować API na swoim koncie testowym jako końcowy klient. Jeśli masz jakiekolwiek pytania dotyczące API, skontaktuj się ze swoim punktem kontaktowym HackerRank lub zgłoś prośbę o wsparcie, pisząc na support@hackerrank.com

Zarejestruj swoją integrację

Po zapoznaniu się z API i zaplanowaniu przepływów, które chcesz obsługiwać, skontaktuj się ze swoim punktem kontaktowym HackerRank lub napisz do nas na support@hackerrank.com, prosząc o klucz partnerski i tajny token. Zostanie Ci również wydany „Klucz API dla całej firmy” do użycia w Twojej integracji.

Zmień mechanizm uwierzytelniania w swoim kodzie integracyjnym

Będziesz musiał dokonać trzech zmian:

  1. Dodaj niestandardowy nagłówek „X-HRW-Partner-Authorization: abcd”, gdzie abcd powinno zostać zastąpione wersją zakodowaną w base64 klucza PartnerKey:PartnerSecret.

  2. Dodaj niestandardowy nagłówek „HRW-User-Email: user@email.com”, gdzie user@email.com powinno zostać zastąpione adresem e-mail użytkownika inicjującego żądanie za pomocą Twojej aplikacji. Powinien on odpowiadać istniejącemu użytkownikowi w koncie HRW klienta.

  3. Użyj Klucza API dla całej firmy zamiast Tokena dostępu osobistego, którego używałeś podczas eksploracji API na swoim koncie.

  4. Przy każdym wywołaniu możesz również wybrać dołączenie dodatkowych metadanych do swojego ładunku, jeśli są metadane, które HackerRank ma zapisać. Niektóre często spotykane pola to

  5. user_email powinien identyfikować użytkownika inicjującego żądanie. Powinien on odpowiadać istniejącemu użytkownikowi w koncie HRW klienta.

  6. candidateId może być unikalnym identyfikatorem tego kandydata w Twoim systemie. Niektóre wywołania API nie są specyficzne dla kandydata, a w takich przypadkach można zignorować to pole.

  7. applicationId może być używane, jeśli kandydat może aplikować na więcej niż jedno Req. Może to być inne pole i identyfikować konkretne zgłoszenie. Niektóre wywołania API nie są specyficzne dla kandydata, a w takich przypadkach można zignorować to pole.

{

    ...

    "metadata": {

        "candidateId": "16651587",

        "applicationId": "25145412",

         "user_email": "abcd@example.com"

    }

}

Używanie tokena autoryzacji partnera oraz kluczy per firma jest ważne, ponieważ mamy inny zestaw polityk i limitów szybkości. Pomaga nam to również łatwiej rozwiązywać problemy klientów pochodzące od Ciebie, co prowadzi do lepszego doświadczenia użytkownika.

Weryfikacja integracji

Po zmodyfikowaniu integracji do użycia powyższego tokena autoryzacji partnera, ocenimy integrację pod kątem poprawnych ścieżek oraz niektórych znanych przypadków brzegowych, z którymi mieliśmy do czynienia w przeszłości.

Przegląd dokumentacji użytkownika końcowego będzie ważną częścią ćwiczenia walidacyjnego.

Dostępność ogólna

Po zakończeniu walidacji dodamy wpis na stronie ATS Integrations, która pokazuje wszystkie obsługiwane integracje. Korzystając z tego interfejsu, wspólni klienci będą mogli sami włączać lub wyłączać Twoją integrację.

Twoja integracja będzie dostępna jako opcja na naszej stronie Ustawień integracji: https://www.hackerrank.com/work/settings/api 

 

Najlepsze praktyki integracji

Scenariusze błędów

W naszym doświadczeniu z ATS-ami, niektóre powszechne scenariusze prowadzące do błędów podczas zapraszania kandydatów to:

  1. Klucz API nie jest ważny dla Twojego konta HackerRank for Work. (Musi to być klucz per firma, a autoryzacja partnera powinna działać poprawnie)

  2. Adres e-mail rekrutera dla konta ATS (wysłany przez metadane) jest inny niż używany w HackerRank for Work (np. używanie sriram.karra@hackerrank.com w koncie ATS i sriram@hackerrank.com w Twoich kontach HRW). Nie ma znaczenia, którą poprawisz, o ile będą takie same.

  3. Brak lub nieprawidłowy adres e-mail kandydata

  4. Kandydat z tym adresem e-mail został już zaproszony.

  5. Rekruter nie ma "Miejsca Rekrutacyjnego" na HackerRank i tym samym nie ma uprawnienia do zapraszania kandydatów

  6. Rekruter nie ma uprawnień do dostępu do konkretnego testu

  7. Konto HackerRank rekrutera nie jest aktywowane.

 

Zalecamy przetestowanie Twojej integracji we wszystkich powyższych scenariuszach i zapewnienie, że zachowanie aplikacji jest łagodne.

Obsługa błędów

API testowe

W przypadku API testowego zwracamy błędy w dwóch różnych formatach - musisz obsłużyć oba formaty odpowiedzi i wyświetlić odpowiedni komunikat końcowemu użytkownikowi.

Przypadek 1: Błąd jest lokalny dla kandydata, na przykład ponowne zaproszenie kandydata. Ma on następujący format:

{

  "data": {

    "username": “error@hackerrank.com",

    "password": "96d3efe9",

    "test_link": “link",

    "status": false,

    "error": 1002,

    "error_message": "Kandydat został już zaproszony do wykonania tego samego testu. Jeśli chcesz ponownie zaprosić, najpierw anuluj zaproszenie na swoim koncie HackerRank for Work."

  },

"message": "Nie zaproszono żadnych kandydatów.",

}

Pogrubione pola wskazują, że wystąpił błąd. Jeśli wystąpią nieobsłużone błędy podczas tworzenia kandydata, również będą wyświetlane w tym formacie.

Przypadek 2: Jeśli wystąpi błąd w samej konfiguracji rekrutera (zwykle w wyniku złej konfiguracji lub złego formatu), jest on zwracany w następującym formacie:

{

  "data": {},

  "status": false,

  "message": "Nie istnieje taki test",

}

Akcje wywołujące ten błąd obejmują nieprawidłowe konto rekrutera, nieprawidłowe e-maile, nieprawidłowy identyfikator testu itp.

Poprawne żądania będą zwracane z kodami odpowiedzi 200.

Nieprawidłowy token dostępu: Oprócz tych dwóch scenariuszy błędów, jeśli użytkownik skonfigurował integrację z nieprawidłowym kodem dostępu, zwrócimy błąd w następującym formacie z kodem odpowiedzi 401:

{

    "model": {},

    "message": "Nieprawidłowy token dostępu"

}

API CodePair (API rozmów kwalifikacyjnych)

Nieprawidłowy token dostępu: Jeśli token dostępu zawarty w żądaniu jest nieprawidłowy, zwrócimy pustą odpowiedź z kodem statusu 403.

Nieprawidłowe informacje: W przypadku, gdy żądanie zawiera jeden lub więcej błędów innych niż błąd tokena dostępu, zwrócimy listę wszystkich błędów w polu errors z kodem żądania 422. Na przykład:

{

    "errors": [

        "tytuł jest polem wymaganym",

        "zakres czasu rozmowy jest nieprawidłowy",

        "......."

    ]

}