Хабрахабр

FAQ по HeadHunter API (публикация вакансий)

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

image

Предыстория

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

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

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

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

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

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

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

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

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

все методы?

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

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

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

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

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

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

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

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

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

А также

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

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

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

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

Про quota_exceeded

Пока один из менеджеров не был привязан, возвращалась ошибка quota_exceeded для его аккаунта. Со стороны это выглядело так, словно аккаунт, связанный с API, выступает мастер-аккаунтом и остальные менеджеры должны от него наследоваться через интерфейс сайта. Точно разобраться как это работает не было возможности, если вы знаете — сообщайте!

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

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

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

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

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

Теги
Показать больше

Похожие статьи

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

Кнопка «Наверх»
Закрыть