Скилл HeadHunter в Aizor: как подключить API hh.ru и работать с вакансиями и откликами

Что даёт скилл HeadHunter в Aizor

Официальное описание скилла от команды Aizor: интеграция с API hh.ru: поиск вакансий и резюме, отклики, публикация и управление вакансиями работодателя. Агент выполняет эти действия по вашей просьбе обычными словами.

Скилл подойдёт рекрутеру и владельцу малого бизнеса, который сам нанимает людей, а также соискателю, которому нужно искать вакансии и откликаться. Доступные функции зависят от того, под какой ролью вы авторизуетесь: соискатель или работодатель. Подробнее об Aizor читайте на странице «Что такое Aizor».

Что понадобится

• Аккаунт на hh.ru: соискателя или работодателя (менеджера работодателя).
• Зарегистрированное приложение на dev.hh.ru и настроенная авторизация OAuth 2.0.
• Для работодателя: оплаченные услуги, если нужны платные методы. Поиск резюме, сохранённые поиски и публикация вакансий зависят от услуг и квот аккаунта.
• Установленный Aizor (macOS или Windows) и скилл из каталога.

Как получить ключ API: по шагам

1. Откройте dev.hh.ru и нажмите «Добавить приложение». Заполните заявку: по документации она нужна, если приложению требуется доступ к вакансиям, резюме, откликам и авторизации пользователя. Названия приложений и использование логотипа hh.ru регулируются отдельными требованиями.
2. Дождитесь проверки. Заявка проходит несколько отделов и может занимать до 15 рабочих дней, повлиять на скорость нельзя.
3. После одобрения у приложения появляется client_id. Авторизуйте пользователя: откройте https://hh.ru/oauth/authorize?response_type=code&client_id=ВАШ_CLIENT_ID, войдите и разрешите доступ. Для нужной роли в ссылку можно добавить параметр role со значением applicant или employer.
4. Обменяйте полученный временный код на токен запросом POST https://api.hh.ru/token (сервер-сервер). Вы получите access_token и refresh_token.
5. Передавайте токен в заголовке Authorization: Bearer ваш_access_token и указывайте User-Agent. Для проверки токена удобно использовать метод /me.

Срок жизни access_token указан в поле expires_in в секундах. После его истечения нужно получить новую пару токенов по refresh_token. Токен приложения (для запросов от имени приложения) генерируется один раз, его можно посмотреть на dev.hh.ru/admin. Повторный запрос отзывает ранее выданный токен.

Как эти шаги выполнить без программирования, зависит от реализации скилла. В Aizor установите скилл HeadHunter из каталога и следуйте его настройкам: вставьте данные приложения или токен в то место, которое он запрашивает. Какие тарифы подходят, смотрите на странице тарифов Aizor.

Проверка: первые запросы агенту

• «Покажи информацию о моём аккаунте на hh.ru» (только чтение, аналог метода /me).
• «Найди вакансии менеджера по продажам в Уфе» (только чтение).
• «Покажи мои вакансии и количество откликов на каждую» (только чтение, роль работодателя).
• «Откликнись на эту вакансию с моим резюме» (действие, включите подтверждение вручную).

Сценарии автоматизации

Ежедневная подборка вакансий

Соискатель описывает, что ищет, а агент по расписанию проверяет новые вакансии по запросу и присылает подборку. В API списки отдаются постранично, по умолчанию по 20 объектов.

Разбор откликов на вакансию

Работодатель просит агента показать новые отклики по вакансии и подготовить краткую сводку. Решения о приглашениях принимает человек.

Управление вакансиями

Агент публикует вакансию по вашему тексту или продлевает её. Публикация требует купленных услуг и квоты, поэтому такие действия лучше подтверждать вручную.

Поиск резюме

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

Частые ошибки

Что видите	Причина	Что делать
400 Bad Request при любом запросе	Не передан заголовок User-Agent или HH-User-Agent	Укажите название приложения и почту разработчика в заголовке
403, bad_authorization	Токен не существует или недействителен	Проверьте токен в настройках скилла и пройдите авторизацию заново
403, token_expired или token_revoked	Истёк срок жизни access-токена или токен отозван пользователем	Обновите токен через refresh_token или запросите новую авторизацию
403, action_must_be_payed	Запрошен платный метод без оплаченного доступа	Подключите нужную услугу работодателя на hh.ru или не используйте этот метод
403 по вакансиям: quota_exceeded, not_enough_purchased_services	Закончилась квота менеджера или не хватает купленных услуг	Проверьте квоты и услуги в аккаунте работодателя

Ещё из документации: если откликаться на вакансию нужно с прохождением теста, через API такой отклик в данный момент недоступен (test_required). Есть и лимит откликов и приглашений (limit_exceeded).

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

• Токены дают доступ к аккаунту hh.ru, а у работодателя ещё и к оплаченным контактам. Не публикуйте их и не отправляйте в чатах.
• Авторизуйте агента под отдельным рабочим аккаунтом менеджера, если у вас несколько менеджеров, и не давайте больше прав, чем нужно.
• Отклики, приглашения, публикацию и продление вакансий оставьте под ручным подтверждением в Aizor.
• Просмотр контактов в базе резюме может списывать оплаченные контакты. Не разрешайте агенту открывать их массово.
• Если токен мог утечь, инвалидируйте его методом инвалидации токена и запросите авторизацию заново. Токен приложения при повторном запросе отзывается автоматически.
• Резюме содержат персональные данные соискателей. Обращайтесь с ними осторожно.

Инструкция написана по официальной документации HeadHunter API (dev.hh.ru, api.hh.ru/openapi/redoc и репозиторий документации hhru/api), состояние на октябрь 2026 года. Интерфейс кабинета и условия могут измениться. Автор Aizorlab участвует в партнёрской программе Aizor.