Integracja partnerska z portalem ofert pracy

Praktyczny punkt wyjścia do połączenia portalu ofert pracy z Kit przez istniejące API, feed i proces aplikowania partnera.

Zacznij od interfejsu, który już masz

Kit może połączyć się z portalem ofert pracy bez narzucania mu własnego protokołu. Jeśli masz już partnerskie API, importer feedu XML, proces OAuth, endpoint taksonomii, callback moderacji albo umowę dotyczącą zewnętrznego aplikowania, zintegrujemy się właśnie z nim.

Ten przewodnik jest listą pytań o potrzeby integracji, a nie specyfikacją narzuconą partnerom. Ma skrócić pierwszą rozmowę techniczną: pokazuje, co Kit udostępnia już dziś, jakie decyzje zwykle trzeba podjąć i gdzie możemy dopasować się do istniejącego procesu.

Important

Obowiązuje specyfikacja portalu dla środowiska produkcyjnego. Dopasujemy Kit do udokumentowanych pól portalu, uwierzytelniania, cyklu życia, zasad rozliczania kredytów i procesu kandydata. Poniższe przykłady opisują obecne możliwości Kit; nie zakładają, że konkretny portal akceptuje te formaty.

Modele integracji

Większość partnerstw wykorzystuje co najmniej jeden z tych modeli:

Model	Kiedy sprawdza się najlepiej	Co zapewnia Kit
Wysyłanie do API portalu	Portal ma już API dla pracodawców albo multipostingu	Tworzenie, aktualizowanie, wstrzymywanie lub zamykanie oraz synchronizacja statusu przez adapter właściwy dla portalu
Pobieranie feedu przez portal	Portal cyklicznie importuje feedy klientów albo systemów ATS	Publiczny, buforowalny feed XML dla każdego pracodawcy; dodajemy wariant portalu zgodny z jego obowiązującym schematem
Link do zewnętrznego formularza	Portal odsyła kandydatów do systemu ATS pracodawcy	Stabilny adres ogłoszenia albo bezpośredni adres aplikowania z oznaczeniem źródła
Aplikowanie w portalu z przekazaniem do Kit	Portal zbiera kandydaturę i ma zgodę na jej przekazanie	Serwerowe API ograniczone do klienta, proces wgrywania CV przez podpisany adres, schemat formularza i potwierdzenie przyjęcia bez danych osobowych

Możemy zacząć od najprostszego obsługiwanego modelu, a później rozszerzyć synchronizację statusów lub aplikacji. Feed pobierany przez portal nie wymaga wdrożenia modelu push Kit, a integracja push nie wymaga obsługi któregoś z obecnych wariantów feedu Kit.

Formaty dostępne w Kit

Publiczne feedy XML i Atom

Każdy hostowany portal kariery ma osobny feed pracodawcy, zawierający tylko ogłoszenia aktualnie przyjmujące zgłoszenia:

https://startupkit.app/careers/example/jobs.xml
https://startupkit.app/careers/example/jobs/atom

Niestandardowe domeny portalu kariery udostępniają te same feedy pod /jobs.xml i /jobs/atom. Kit generuje obecnie warianty Adzuna, Atom 1.0, Jooble, Jobrapido, Talent.com i Uitzendbureau. Pokazują one dostępne dane, ale nie zakładamy, że inny portal akceptuje którykolwiek z nich. Gdy partner przekaże schemat i przykładowe payloady, Kit może udostępnić specjalny wariant pod stabilnym adresem URL. Dla Talent.com zobacz Publikowanie ofert w Talent.com.

Wpisy feedu mają stabilny publiczny identyfikator ogłoszenia i mogą zawierać:

tytuł i opis HTML;
nazwę pracodawcy, dział lub kategorię, lokalizację oraz informację o pracy zdalnej;
daty publikacji i aktualizacji;
rodzaj zatrudnienia;
minimalne i maksymalne wynagrodzenie, walutę oraz okres, jeśli zostały podane;
publiczny adres ogłoszenia i bezpośredni adres aplikowania z parametrami UTM partnera.

Wstrzymanie albo zamknięcie roli usuwa ją z feedu. Ponowne otwarcie przywraca ten sam stabilny identyfikator. Zmiana treści aktualizuje istniejący wpis zamiast tworzyć drugi.

Publiczne API REST ofert pracy

Publiczne API ofert pracy udostępnia JSON przez HTTPS do integracji serwerowej lub przeglądarkowej:

GET /api/public/v1/jobs
GET /api/public/v1/jobs/:public_token
POST /api/public/v1/jobs/:public_token/applications

Lista zwraca tylko opublikowane ogłoszenia. Szczegóły zawierają dodatkowo oczyszczony opis HTML i schemat formularza zgłoszeniowego pracodawcy. Każdy pracodawca tworzy parę kluczy ograniczoną do swojego konta; integracje serwerowe używają tajnego klucza sk_…. Żaden z kluczy nie pozwala odczytać danych kandydatów.

Przekazywanie aplikacji z portalu uzgadniamy osobno. Portal musi zachować wymagane pytania, ograniczenia CV, informacje o zgodach, ochronę przed botami i prawdziwe źródło kandydata. Jeśli portal obsługuje już zewnętrzny adres ATS, przekierowanie kandydatów do Kit zwykle daje najszybsze i najprostsze pierwsze wdrożenie.

Dane strukturalne JobPosting

Każda publiczna strona ogłoszenia zawiera generowany po stronie serwera JSON-LD schema.org/JobPosting. Obejmuje opis stanowiska, daty publikacji, pracodawcę, lokalizację lub wymagania dotyczące pracy zdalnej, rodzaj zatrudnienia, wynagrodzenie, jeśli je podano, status bezpośredniego aplikowania oraz kanoniczny adres URL.

JSON-LD pomaga w wykrywaniu i walidacji. Nie zastępuje uzgodnionego API publikacji, schematu feedu, statusu moderacji ani callbacku cyklu życia.

Podpisane webhooki cyklu życia

Kit może wysyłać podpisane webhooki przy następujących zdarzeniach:

job_posting.published
job_posting.paused
job_posting.closed
job_posting.reopened

Zdarzenie identyfikuje klienta i ogłoszenie oraz zawiera jego aktualny status i publiczny adres URL. Partner może potraktować je jako sygnał do odświeżenia kopii danych, a następnie ponownie pobrać kanoniczne ogłoszenie z uzgodnionego feedu albo API. Zobacz Wprowadzenie do webhooków oraz Bezpieczeństwo i dostarczanie webhooków.

Kanoniczne dane ogłoszenia

Obecne interfejsy publikacyjne Kit mogą udostępnić następujący podstawowy zestaw danych:

Pole	Uwagi
Stabilny identyfikator ogłoszenia	Publiczny token nie zmienia się po edycji, wstrzymaniu ani ponownym otwarciu
Tytuł i opis	Zwykły tytuł oraz oczyszczony opis HTML
Pracodawca	Nazwa klienta; logo i witryna są dostępne z profilu pracodawcy
Dział lub kategoria	Wartość podana przez pracodawcę, w razie potrzeby dopasowana do taksonomii portalu
Lokalizacja i praca zdalna	Tekstowa lokalizacja, miasto, region i kod kraju w danych strukturalnych, flaga pracy zdalnej oraz kraje, z których mogą pracować kandydaci zdalni
Zatrudnienie	Rodzaj zatrudnienia; wartości umów właściwe dla partnera można zebrać podczas mapowania
Wynagrodzenie	Minimum, maksimum, waluta ISO oraz okres godzinowy, dzienny, miesięczny lub roczny, jeśli dane są jawne
Daty	Znaczniki czasu publikacji i ostatniej aktualizacji; zamknięte ogłoszenia znikają z aktywnych feedów
Adresy URL	Kanoniczny adres ogłoszenia i bezpośredni adres aplikowania
Formularz aplikacyjny	Wymagane pola, pytania screeningowe, informacje o zgodzie i ograniczenia CV

Portale często wymagają dodatkowych danych kontrolowanych, takich jak poziom doświadczenia, umiejętności, języki, identyfikatory kategorii, wiele lokalizacji, taksonomie umów, informacje o prywatności czy opcje płatnych pakietów. Mapujemy albo zbieramy je podczas przeglądu integracji, zamiast zastępować je ogólną wartością, która pomija szczegóły.

Czego potrzebujemy od partnera

Prześlij używaną już dokumentację i opis procesu. Poniższa lista pomaga wcześnie znaleźć luki; nie szkodzi, jeśli część punktów nie ma zastosowania.

Kontakty techniczne i handlowe
Dokumentacja API, feedu albo multipostingu wraz z przykładowymi żądaniami i odpowiedziami
Dane dostępowe do sandboxa albo bezpieczne konto testowe
Uwierzytelnianie, rotacja kluczy, zakresy, rate limiting i wymagania dotyczące adresów IP
Taksonomie kategorii, lokalizacji, poziomów doświadczenia, umiejętności, umów i wynagrodzeń
Pola wymagane i opcjonalne oraz reguły walidacji
Zachowanie przy tworzeniu, edycji, publikacji, wstrzymaniu lub zamknięciu, ponownym otwarciu i wygaśnięciu
Idempotencja, ponawianie, zapobieganie duplikatom i znaczenie błędów
Statusy moderacji oraz obsługa odpytywania lub callbacków
Zasady aplikowania zewnętrznego lub bezpośredniego, oznaczanie źródła, prywatność i okres przechowywania
Własność pakietu, zużycie kredytów, wybór marki i zasady kredytów testowych
Proces zatwierdzenia produkcyjnego, certyfikacji i wsparcia

Tip

Działający przykład jest cenniejszy niż nowy dokument. Na początek wystarczy istniejąca kolekcja Postman, plik OpenAPI, przykład XML albo przewodnik integracyjny. Dopasujemy do niego Kit i opiszemy tylko decyzje właściwe dla naszego połączenia.

Bezpieczeństwo i dane kandydatów

Publiczne feedy i endpointy list ofert zawierają dane ogłoszeń, nigdy dane osobowe kandydatów.
Poświadczenia są ograniczone do klienta, a sekrety serwerowe nie trafiają do przeglądarki.
Webhooki są podpisane. Odbiorca musi sprawdzać podpis i wiek żądania, aby odrzucać powtórzenia.
Dane aplikacji przyjmujemy wyłącznie przez uzgodniony proces albo własną stronę aplikowania pracodawcy w Kit.
Nie budujemy integracji partnerskich przez pobieranie danych z prywatnych lub nieudokumentowanych endpointów.

Rozpoczęcie współpracy

Napisz na [email protected], dołączając istniejący przewodnik integracyjny albo nazwisko osoby, która za niego odpowiada. Odpowiemy zwięzłym mapowaniem pól i propozycją małego pilotażu, który pozwoli obu zespołom sprawdzić integrację.

Lista kontrolna

Wybierz API push, feed pull, zewnętrzne aplikowanie, aplikowanie bezpośrednie albo ich połączenie
Udostępnij istniejącą specyfikację portalu i sposób testowania w sandboxie
Uzgodnij mapowanie pól i taksonomii oraz rozliczanie kredytów
Przetestuj tworzenie, edycję, zamknięcie, błędy i ścieżki moderacji
Sprawdź oznaczenie źródła i prywatność kandydatów
Zacznij od małego płatnego pilotażu, a potem monitoruj status i aplikacje