Небольшая история про наш рекрутинговый сервис под заказчика и большая история про проблемы, которые появились при интеграции с HeadHunter с точки зрения публикации вакансий. Почему HeadHunter? Потому что на Superjob всё несколько проще (но это не точно).

Предыстория

Моя команда разрабатывает веб-приложение автоматического трудоустройства для одной крупной торговой сети. Цепочка действий строится таким образом:

1. бизнес утверждает базовые шаблоны вакансий (требования, обязанности, условия), универсальные для всех магазинов и городов;
2. HRы на основе базового шаблона создают основной шаблон вакансии под каждый город, указывая диапазон зарплаты для конкретной должности (для одинаковых должностей в разных регионах могут быть разные зарплаты);
3. директор магазина на основе шаблона вакансии открывает вакансию на свой магазин внутри нашего приложения и получает на неё ссылку;
4. кандидат, переходя по ссылке, попадает на анкету, куда вносит контактную информацию и отправляет на рассмотрение директору магазина;
5. ??????
6. PROFIT!

Когда появилось предложение публиковать вакансию на HeadHunter со ссылкой на анкету, я бегло изучил документацию к их API и подумал что-то в стиле "там делов на 5 минут". И вот, спустя ~1.5 месяца, пишу данную статью.

Работа с API HeadHunter

Итак, есть задача по публикации вакансий на HeadHunter, вам понадобятся:

Актуальная версия API

К сожалению (или к счастью?), API не версионирован, поэтому, теоретически, в любой момент может отвалиться что угодно. Даже если такого никогда не случалось и к этому нет предпосылок, всё равно он обновляется:

В ответах и параметрах API можно найти ключи, не описанные в документации. Обычно это означает, что они оставлены для совместимости со старыми версиями. Их использование не рекомендуется.

Регистрация приложения

Здесь всё просто, но не так просто, как хотелось бы. Будет предложено заполнить форму, где одно из полей содержит формулировку "Опишите все функциональные возможности приложения и укажите используемые методы API". Насколько подробно???

При первой регистрации приложения форма была заполнена детально, с указанием всех роутов, второй раз терпения хватило только на фразу "все методы из блока "вакансии"". Прошли оба варианта.

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

Регистрация второго приложения

Обратите внимание на параметр Redirect URI при регистрации приложения. Согласно нашему наблюдению, подтверждённому техподдержкой HeadHunter, если ваш тестовый контур находится на субдомене (допустим, test.example.com), то нужно приложение для прода (с redirect_uri=example.com) и для разработки (с redirect_uri=test.example.com). А это ещё две недели ожидания одобрения.

Изучение и уточнение правил

Пока мы разрабатывали функционал и в тестовом режиме публиковали закрытые вакансии, всё было хорошо. Выкатив в прод публикацию вакансий открытого типа, обнаружилось исчезновение ссылок из-за запрета правилами их размещение в вакансиях, но, со слов поддержки, ссылки можно автоматически отправлять в личку при отклике (что в правилах не описано). Тут нас подвела собственная невнимательность, однако, на мой взгляд, можно было поставить валидатор на стадии приёма текста вакансии.

Немного интуиции

Иногда тексты ошибок абсолютно непредсказуемы и нелогичны. Вот с чем мы столкнулись:

• not_enough_purchased_services (купленных услуг для публикации или обновления данного типа вакансии не достаточно) — при публикации вакансии с типом free. Что именно нужно купить для бесплатных вакансий — не понятно. Решение: указать type: standard;
• quota_exceeded (квота менеджера на публикацию данного типа вакансии закончилась) — квоты менеджера конфигурируются через https://hh.ru/employer/settings/quotas, последний же раз мы её видели при опечатке standart вместо standard в поле type;
• duplicate (аналогичная вакансия уже опубликована) при использовании флага ignore_duplicates — возникает при совпадающих полях name и area, независимо от наличия флага игнорирования дубликатов.

А также

Про безопасность

Учесть факт, что жизнь токена составляет две недели (это у них любимый срок, видимо) и рефрешить его раньше времени нельзя, только путём разлогина. Теоретически, проблем это вызвать не должно, однако, если токен утечёт, то у злоумышленника может быть достаточно времени для злоразмышлений, злодеяний и злорадствования.

Про интерфейсы

Описание вакансии — это одно поле description, поддерживающее несколько HTML-тегов, которые можно подсмотреть в их визуальном редакторе на сайте. Мы выбрали формат вакансии из трёх текстовых полей: обязанности, требования, условия и для HeadHunter просто объединяем их, вставляя h3 с названием поля в качестве разделителя.

Про справочники

Как и весь API, справочники могут измениться в любой момент, о чём явно сказано в их описаниях:

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

Итоги

"Быстрый старт" займёт у вас около двух недель, вероятно, с необходимостью регистрировать несколько приложений. В целом, документация и сам API достаточно вменяемы, в остальном можно разобраться по общению с техподдержкой или через issue на их гитхабе.

Уверен, мы нашли не все интересности, связанные с API HeadHunter, ведь даже не касались ветки резюме. Поэтому, если вам есть что рассказать / дополнить / уточнить — пишите в комментарии.