Перейти до вмісту
RolePark
UA
Про продукт ↗

API, вебхуки, SCIM і єдиний вхід SAML

RolePark зʼєднується з іншими вашими системами чотирма способами: REST API з ключами з вузькими правами, підписані вебхуки, SCIM 2.0 для створення й деактивації облікових записів і єдиний вхід SAML 2.0. Налаштовує їх адміністратор компанії.

Оновлено:

Перевірено командою RolePark

Коротко

  • REST API з 7 областями доступу: читання людей, працевлаштувань, публічних вакансій і заявок, додавання кандидатів; 120 запитів на хвилину на ключ.
  • Вебхуки для 8 подій, підписані HMAC-SHA256: усього 6 спроб доставки (5 повторів).
  • SCIM 2.0 для облікових записів і єдиний вхід SAML 2.0 з можливістю вимкнути вхід паролем.
  • Доступно на всіх тарифах, зокрема на Free; ключі видає й SSO налаштовує лише адміністратор компанії.

REST API

API розміщено за адресою https://rolepark.com/api/v1. Кожен запит несе ключ у заголовку Authorization як bearer-токен. Ключі створює адміністратор компанії на сторінці «Інтеграції» і дає кожному лише потрібні області доступу.

Області доступу

people.read, employments.read, vacancies.read, applications.read, candidates.write, webhooks.manage, scim.manage. Ключ дає зовнішній системі доступ до даних компанії незалежно від ролей, тому видає його лише адміністратор, а області доступу вузькі.

Що API читає і записує

  • Читання людей і працевлаштувань із фільтром «змінено після» для поступової синхронізації.
  • Читання публічних вакансій і заявок із фільтром за статусом або вакансією.
  • Додавання кандидатів. Потрібні імʼя, прізвище, джерело та пошта, телефон або LinkedIn. Якщо кандидат уже є, RolePark заповнює лише порожні поля й не перезаписує решту.
  • Читати картки кандидатів через ключ свідомо не можна.

Ліміти, ключі й документація

  • 120 запитів на хвилину на ключ; понад це API відповідає 429 із Retry-After.
  • Посторінкова видача: 25 записів за замовчуванням, до 100.
  • Ключ показується один раз. RolePark зберігає лише його SHA-256-хеш, тож показати його знову не може; відкликаний ключ перестає працювати одразу.
  • Опис OpenAPI 3 — за адресою /api/v1/openapi.json, відкривається тим самим ключем.

Вебхуки

RolePark надсилає POST-запит на вашу HTTPS-адресу, коли стається одна з цих подій: employment.created, employment.updated, employment.ended, application.stage_changed, document.signed, interview.scheduled, interview.cancelled, scorecard.submitted.

  • Кожен запит підписано: sha256=HMAC(secret, timestamp + "." + body). Перевіряйте підпис за сирим тілом запиту. Секрет показується один раз, його можна замінити.
  • Приймаються лише HTTPS-адреси на публічних хостах. Отримувач має відповісти 2xx протягом 10 секунд; переадресації не виконуються.
  • Невдалу доставку повторюємо через 30 секунд, 2 хвилини, 10 хвилин, 1 годину і 6 годин. Після останньої спроби адресу вимкнено, і сторінка «Інтеграції» це показує.
  • Журнал показує останні 50 доставок зі статусом і помилкою, доставку можна повторити вручну.

SCIM 2.0: облікові записи з вашого постачальника ідентичності

SCIM — стандарт IETF для створення, зміни й видалення облікових записів із постачальника ідентичності (RFC 7643 і RFC 7644). Адреса SCIM у RolePark — https://rolepark.com/api/scim/v2; потрібен ключ API з областю scim.manage.

  • Підтримано: ресурс Users (перелік, створення, читання, заміна, зміна й видалення) і ServiceProviderConfig.
  • Фільтр userName eq, посторінкова видача через startIndex і count, до 200 на сторінку.
  • Видалення користувача чи active = false деактивує обліковий запис. Нічого не стирається: історія, підписи й оцінки лишаються. Останнього активного адміністратора деактивувати не можна.
  • Нові користувачі SCIM отримують роль «Працівник»; інші ролі адміністратор призначає в RolePark. Групи не підтримуються.

Єдиний вхід SAML 2.0

Адміністратор компанії налаштовує єдиний вхід у «Налаштування» → «Компанія». RolePark показує свої дані для вашого постачальника ідентичності — Entity ID постачальника послуг, адресу ACS і метадані, — а ви вводите Entity ID постачальника ідентичності, його HTTPS-адресу входу й сертифікат підпису.

  • Постачальник ідентичності має підписувати твердження. Після збереження RolePark показує лише відбиток сертифіката.
  • RolePark бере пошту й імʼя з назв атрибутів, які за замовчуванням використовують Okta і Microsoft Entra ID (Azure AD).
  • Під час першого входу обліковий запис не створюється: спершу запросіть людей або створіть їх через SCIM.
  • Коли SSO працює, адміністратор може заборонити вхід паролем для компанії. Один постачальник ідентичності на компанію.

Ключі аналітики для Power BI і Excel

З доступом до ATS адміністратор може видати окремі ключі для JSON- і CSV-фідів статистики вакансій і людей. Power BI і Excel читають їх як вебджерело даних. Фід вакансій містить лише числа — заявки за етапами, наймання й час до найму — без персональних даних кандидатів.

Інші підключення

AI-асистенти, як-от Claude і ChatGPT, підключаються через MCP з правами самої людини, а Djinni — ключем API з вашого акаунта Djinni. Для обох є окремі інструкції.

Часті питання

Чи доступне API на тарифі Free?

Так. API, вебхуки, SCIM і єдиний вхід SAML доступні на всіх тарифах. Ключам аналітики для Power BI потрібен доступ до ATS.

Чи можна читати кандидатів через API?

Ні, так задумано. Ключ може додавати кандидатів (candidates.write) і читати людей, працевлаштування, публічні вакансії й заявки.

Чи підтримує RolePark групи SCIM?

Ні. RolePark підтримує ресурс SCIM Users. Ролі призначаються в RolePark; нові користувачі SCIM починають із ролі «Працівник».

Чи створює вхід SAML облікові записи автоматично?

Ні. Людина вже має мати обліковий запис — за запрошенням або через SCIM. Невідомі адреси пошти відхиляються.

Як перевірити вебхук?

Обчисліть HMAC-SHA256 секретом вебхука від мітки часу, крапки й сирого тіла запиту і порівняйте з підписом у запиті.

Джерела

Створити робочий простірНаписати команді RolePark