Для разработчиков

API Julia NeuroHR

Всё, что вы видите и настраиваете в кабинете, доступно по HTTP: диалоги с кандидатами, записи на собеседования, AI-рекрутеры и их сценарии, объявления, поиск кандидатов, аналитика, баланс и оплата. Подключайте свою CRM, отчёты или собственного ИИ-агента.

Быстрый старт

1. 1. Выпустите ключ. Кабинет → раздел «API» → «Выпустить ключ». Ключ показывается один раз — сразу сохраните его. Выпускать ключи может администратор кабинета.
2. 2. Проверьте ключ. Ответ покажет ваш кабинет и его номер tenant.id — он подставляется во все пути вместо {tenant_id}.
3. 3. Работайте. Например, заберите ближайшие записи на собеседования.

export NHR_KEY="nhr_live_..."          # ключ — из переменной окружения, не из кода
curl https://api.neurohr.za-bota.com/platform/api/whoami -H "Authorization: Bearer $NHR_KEY"

# {"tenant": {"id": 42, "name": "Ромашка", ...}, "key": {"level": "read", ...}, ...}

curl https://api.neurohr.za-bota.com/platform/tenants/42/bookings -H "Authorization: Bearer $NHR_KEY"

Адрес API — https://api.neurohr.za-bota.com. Формат — JSON (Content-Type: application/json). Время — unix-секунды, если не сказано иное; суммы кошелька — в копейках.

Ключи и уровни доступа

Каждый запрос — с заголовком Authorization: Bearer nhr_live_…. Ключ действует на весь ваш кабинет. При выпуске выбирается, что ключу можно:

Уровень ключа не может быть выше прав человека, который его выпустил. Если у этого человека забрали доступ в кабинет — его ключи перестают работать.

Границы ключа

Ключ работает только внутри своего кабинета — запрос к чужому получит 403. По ключу не работает только механика входа человека: логин, пароль, приглашение, привязка Telegram (403 cookie_session_required); узнать, с чем работает ключ, — GET /platform/api/whoami.

Ключ «Полный доступ» может выпускать другие ключи. Они запоминают, кем выпущены: отзыв ключа сразу гасит и все ключи, которые он успел выпустить, — утёкший ключ не оставит после себя «запасных».

Подтверждение трат

Действия, которые сразу списывают деньги или пишут живым людям (смена тарифа, докупка мест, покупка контактов кандидатов, письмо купленным кандидатам), выполняются только с параметром ?confirm=true. Без него — 400 confirmation_required, ничего не произошло. Так пробный запрос «проверить, есть ли маршрут» не потратит деньги.

Ошибки и лимиты

Ошибки доступа приходят объектом {"detail": {"code", "message", "docs"}}, ошибки разделов — строкой {"detail": "текст"}, ошибки формата тела —422 со списком полей.

Справочник

Пути даны относительно https://api.neurohr.za-bota.com. Поля тела и ответа — ровно те, что использует кабинет; полная машинная схема каждого запроса — OpenAPI (её можно импортировать в Postman или отдать ИИ-агенту).

Вебхуки

Вместо опроса API подпишитесь на события: мы сами пришлём POST в вашу систему, как только что-то произошло. Вебхук добавляется в кабинете (раздел «API» → «Вебхуки») или по ключу «Полный доступ» — POST /platform/tenants/{tenant_id}/webhooks.

POST https://ваша-crm.ru/neurohr/webhook
Content-Type: application/json
X-NeuroHR-Event: candidate.outcome
X-NeuroHR-Delivery: 9f2c…            # id события — повторы с тем же id не присылаем
X-NeuroHR-Signature: sha256=<hex HMAC-SHA256(секрет, тело)>

{"event": "candidate.outcome", "event_id": "9f2c…", "tenant_id": 42, "occurred_at": 1789000000,
 "data": {"vacancy": "Кассир", "status": "interview", "full_name": "Иван Петров",
          "phone": "+79990000000", "booking": {"date": "2026-09-20", "time": "10:00"}, ...}}

Проверка подписи (Python)

import hmac, hashlib

def valid(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

• Отвечайте 2xx быстро: на весь запрос — 10 секунд. Тяжёлую обработку делайте у себя асинхронно.
• Не ответили, ответили 5xx, 408 или 429 — повторим через 1 мин, 5 мин, 30 мин, 2 ч и 6 ч. На остальные 4xx не повторяем. Статус каждой доставки виден в кабинете («Доставки») и по API: GET …/webhooks/{id}/deliveries.
• После 20 неудач подряд вебхук выключается — включить снова можно в кабинете или POST …/webhooks/{id}/enable.
• Одно событие приходит один раз: повторы используют тот же event_id (заголовок X-NeuroHR-Delivery) — по нему удобно отсекать дубли у себя.
• Секрет подписи показывается один раз — при создании вебхука и при смене (POST …/webhooks/{id}/rotate-secret).
• Адрес — только https, порт 443 или 8443, домен латиницей (кириллический — в виде xn--…), только публичные адреса: внутренние и локальные отклоняются.
• В событиях — персональные данные кандидатов. При добавлении вебхука администратор подтверждает, что отвечает за их обработку в своей системе (pdn_ack: true); без этого события с анкетами не отправляются.
• Если у кабинета нет Telegram-групп для карточек, а вебхук есть, — событие в очереди вебхука считается доставкой карточки. Если группы есть, карточка в Telegram и событие в вебхук доставляются независимо.

Примеры

Записанные кандидаты — в свою CRM (Python)

Раз в 10 минут забирать предстоящие записи и отправлять новые в CRM. Хватит ключа «Чтение».

import os, requests

API = "https://api.neurohr.za-bota.com"
H = {"Authorization": f"Bearer {os.environ['NHR_KEY']}"}

tenant_id = requests.get(f"{API}/platform/api/whoami", headers=H, timeout=30).json()["tenant"]["id"]
bookings = requests.get(f"{API}/platform/tenants/{tenant_id}/bookings",
                        headers=H, timeout=30).json()

for b in bookings:
    if b["status"] != "booked":
        continue
    # b: external_chat_id, candidate_name, phone, date, time, recruiter_name, vacancy_external_id
    send_to_my_crm(b)          # ваша функция; дубли отсекайте по external_chat_id

Отметить, что кандидат пришёл

curl -X PATCH https://api.neurohr.za-bota.com/platform/tenants/42/bookings/CHAT_ID \
  -H "Authorization: Bearer $NHR_KEY" -H "Content-Type: application/json" \
  -d '{"status": "attended"}'          # или cancelled / no_show — слот освободится

Поставить AI-рекрутера на паузу и включить обратно

curl -X PATCH https://api.neurohr.za-bota.com/platform/tenants/42/profiles/VACANCY_ID \
  -H "Authorization: Bearer $NHR_KEY" -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Непрочитанные диалоги за сутки

curl "https://api.neurohr.za-bota.com/platform/tenants/42/dialogues?unread=true&days=1&sort=last" \
  -H "Authorization: Bearer $NHR_KEY"
# items[]: chat_id, candidate, channel, direction, status, listing_title, last_message, ...
# переписка целиком: GET /platform/tenants/42/dialogues/{chat_id}

Поиск кандидатов: отобрать и купить контакт

Отбор денег не тратит, покупка — тратит, поэтому нужен ключ «Полный доступ» и?confirm=true.

# кандидаты на рассмотрении
curl "https://api.neurohr.za-bota.com/platform/tenants/42/outbound/proposals?status=pending" -H "Authorization: Bearer $NHR_KEY"

# отобрать
curl -X POST https://api.neurohr.za-bota.com/platform/tenants/42/outbound/proposals/1001/approve -H "Authorization: Bearer $NHR_KEY"

# купить контакт и написать кандидату в рабочие часы
curl -X POST "https://api.neurohr.za-bota.com/platform/tenants/42/outbound/proposals/1001/buy?confirm=true" \
  -H "Authorization: Bearer $NHR_KEY"

Подключить ИИ-агента

Дайте агенту OpenAPI-схему — в ней только то, что доступно по ключу, с уровнем каждой операции в поле x-access-level. Ключ передайте агенту через переменную окружения, а не текстом в промпте. Для агента, который только анализирует, выпустите ключ «Чтение».

curl https://api.neurohr.za-bota.com/platform/api/openapi.json -o julia-neurohr-openapi.json

Обработка 429

import time, requests

def call(method, url, **kw):
    for _ in range(5):
        r = requests.request(method, url, timeout=30, **kw)
        if r.status_code != 429:
            return r
        time.sleep(int(r.headers.get("Retry-After", "5")))
    return r

Безопасность

• Храните ключ в переменной окружения или хранилище секретов — не в коде, не в репозитории и не в переписке.
• Один ключ — одна интеграция. Отзыв одного не сломает остальные, а в истории видно, что сделала какая: решения по кандидатам подписываются «API-ключ «название»».
• Выдавайте минимальный уровень: интеграции, которая только забирает данные, хватит «Чтения». «Полный доступ» управляет и сотрудниками, и ключами — храните его как пароль администратора.
• Заподозрили утечку — отзовите ключ в кабинете (действует сразу) и выпустите новый.
• Ключ работает только внутри вашего кабинета и не даёт доступа ни к чужим данным, ни к управлению платформой.

Вопросы по API: mail@za-bota.com