Продукт

API найма: паттерн REST + Bearer Token для интеграций найма

ClarityHire Team(Editorial)2026-05-215 min read

Почему вам нужен REST API

Большинство модерных платформ ATS открывают данные только через вебхуки и натувный UI. Это работает, если у вас есть 20 человек и один процесс. Но в момент, когда вы хотите:

Синхронизировать кандидатов в вашу систему HR (BambooHR, Workday), которая не имеет предварительно построенной интеграции
Тянуть отчеты в ваш хранилище данных для пользовательской аналитики
Массовый импорт кандидатов из старой системы
Построить пользовательский приборную доску, которую ваша команда предпочитает в нативный UI
Автоматизировать задачи с Zapier или Make.com без написания кода

...вам нужен публичный REST API.

REST API — лингва франка SaaS интеграции. Любой инструмент, который говорит HTTP, может говорить с ней. Zapier, Make, n8n, Pipedream, пользовательские скрипты Python, мобильные приложения, ваши собственные приборные доски — все они могут читать и писать данные с простым токеном аутентификации.

Паттерн Bearer Token

Самый простой безопасный паттерн API — bearer tokens: вы выпускаете каждому пользователю ключ API, они включают его в Authorization: Bearer YOUR_KEY заголовок, и каждый запрос аутентифицируется против того ключа.

Это как Stripe, GitHub, Slack, и большинство модерных API работают. Это легко отозвать (удалить ключ), легко ротировать (генерировать новый), и легко охватить (выпускают разные ключи с разными разрешениями).

curl -H "Authorization: Bearer sk_live_abc123xyz" \
  https://api.clarityhire.com/v1/candidates?job_id=j_engineering_2026

Сравните с именем пользователя/паролем или OAuth: bearer tokens без состояния (никакая база данных сеанса), могут быть приданы немедленно, и позволить вам аудить какой ключ сделал какой запрос.

Scopes и разрешения

Лучшая практика безопасности: не выпускайте токены с полной читай-пиши доступом ко всему. Вместо этого, используйте scopes.

candidates:read       # Может список и вид кандидатов
candidates:write      # Может переместить кандидатов, добавить заметки
tests:read            # Может вид результатов тестирования
tests:write           # Может создать и редактировать тесты
jobs:read             # Может список должностей
webhooks:manage       # Может создать/удалить вебхуки

Когда разработчик третьей стороны просит доступ API (скажем, провайдер HRIS интегрирующий с вашей платформой), вы выпускаете им токен с только candidates:read и candidates:write. Они не могут видеть ваши данные биллинга или менять вопросы интервью.

Scopes также защищают против случайного урона. Если скрипт интеграции имеет ошибку и начинает удалять кандидатов, вы пятно это быстрее, если скрипт должен было только иметь candidates:read.

Вебхуки vs. опрос

Два паттерна для информированного синхронизирования данных:

Вебхуки (управляемое событием):

POST https://your-system.com/webhook/clarityhire
{
  "event": "candidate.stage_changed",
  "data": {
    "candidate_id": "c_123",
    "old_stage": "screening",
    "new_stage": "assessment",
    "timestamp": "2026-05-21T14:30:00Z"
  }
}

Когда что-то происходит в ClarityHire, это посты ваше конечно. Вы обрабатываете немедленно. Быстро, эффективно, нет опроса перегрузки.

Опрос (управляемое вытяжкой):

GET https://api.clarityhire.com/v1/candidates?job_id=j_123&updated_since=2026-05-21T00:00:00Z

Вы периодически (каждые 5 минут, каждый час) просите ClarityHire «что изменилось?» и обрабатываете ответ. Проще реализовать, если ваша система не открывает HTTP конечно, но медленнее и шумнее.

Лучшая практика: вебхуки для реального времени (этап изменения, новые заявления), опрос для периодических синхронизирований (дневной экспорт всех кандидатов для вашего хранилища данных).

Оба паттерна должны поддерживать логику повтора. Вебхуки могут выходить неудачей (отключение сети, ваше конечно вниз). API должен переделать с экспоненциальной отставкой и позволить вам видеть неудачные попытки в приборной доске «логов вебхука».

Ограничения скорости и идемпотентность

Когда вы открываете API, вам нужны защиты против злоупотребления и случайных дубликатов.

Ограничения скорости: «Вы можете сделать 1,000 запросов в час на ключ API». Если кто-то превышает это, они получают ответ 429 с заголовком Retry-After. Zapier и другие платформы интеграции уважают эти ограничения автоматически.

Идемпотентность: Если доставка вебхука выходит неудачей, мы переделаем. Но что если запрос действительно преуспел, но ответ получить отключение? Без идемпотентности, мы бы создали дубликат кандидата или переместили кандидата дважды.

Решение: требуйте Idempotency-Key заголовок на запросах написания.

curl -H "Authorization: Bearer sk_live_abc123xyz" \
  -H "Idempotency-Key: zap_12345_attempt_1" \
  -X POST https://api.clarityhire.com/v1/candidates \
  -d '{"email": "[email protected]", "job_id": "j_eng"}'

API хранит ключ и ответ. Если тот же ключ используется снова, это возвращает кэшированный ответ. Нет дубликатов.

Документация и SDKs

API бесполезен без документов. Вам нужно:

Справка конечных точек: каждый маршрут, каждый параметр, каждый ответный формат
Кодексы ошибок: что означает 400? a 403?
Типы событий вебхука: полный список событий вы выпускаете, с примерными полезными нагрузками
Примеры кода: curl, Python, JavaScript фрагменты для общих задач
Аутентификация: как генерировать и ротировать ключи

Бонус: опубликуйте SDKs для популярных языков (Python, JavaScript, Go). Zapier поставляется с построенным SDK, но пользовательские интеграции выигрывают от нативной библиотеки клиента, которая обрабатывает паджинацию, повторы, и обработку ошибок.

Zapier интеграция: следующий уровень рычага

Zapier связывает сотни приложений без кода. Один раз вы открываете REST API, написание интеграции Zapier становится проектом 1-2 недели вместо 4 недель пользовательского построения.

Пример Zap:

Триггер: «Новый кандидат в ClarityHire должности 'Старший инженер-бэкенд'»
Действие 1: «Добавить ряд в Google Sheets»
Действие 2: «Отправить сообщение Slack на #hiring»
Действие 3: «Создать контакт в Pipedrive»

Один пользователь Zapier устанавливает это с ноль кодирования. Другие пользователи Zapier открывают это в рынке Zapier и принимают. Вы построили 100-интеграцию экосистему без написания 100 интеграций.

Как ClarityHire открывает свой API

ClarityHire предложения /api/v1/* с bearer токеном аутентификацией, охватанными разрешениями, и поддержкой вебхука. Справка документы живут в api.clarityhire.com/docs. Ограничение скорости: 1,000 запросов/час на ключ. Идемпотентные запросы письма с заголовком Idempotency-Key.

Пример конечных точек:

GET /api/v1/candidates — список кандидатов (поддерживает фильтрацию, паджинацию)
GET /api/v1/candidates/{id} — единственный кандидат
POST /api/v1/candidates/{id}/move-stage — переход этапа
GET /api/v1/webhooks — список ваших активных вебхуков
POST /api/v1/webhooks — регистр новый вебхук

Вебхуки могут быть отфильтрованы событием типа, job_id, или организацией. Система повторно пытается неудачные доставки 10 раз в течение 24 часов с экспоненциальной отставкой.

TL;DR

Публичный REST API с bearer tokens разблокирует интеграции. Область разрешений по варианту использования. Предпочтите вебхуки для реального времени синхронизирования, опрос для батча экспортов. Полностью идемпотентность на запросы письма для предотвращения дубликатов. Документ тщательно, включая коды ошибок и примеры. Интеграция Zapier — умножитель: один API позволяет тысячу случаев использования без вашей команды кодирования их.

Инвестиция в дизайн API платят разделы в гибкости и усвоении.

apiинтеграцииzapierвебхукиавтоматизация найма