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



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


image


Предыстория


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


  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, ведь даже не касались ветки резюме. Поэтому, если вам есть что рассказать / дополнить / уточнить — пишите в комментарии.

Вы можете помочь и перевести немного средств на развитие сайта



Комментарии (7):

  1. SergiuCiudin
    /#20522261 / +1

    И еще будьте готовы что в одно и тоже поле могут быть разные структуры данных и вам придется написать кастомные десерялизаторы. Надеюсь вам не нужен будет HH API.

  2. iriss22
    /#20523013

    not_enough_purchased_services (купленных услуг для публикации или обновления данного типа вакансии не достаточно) — при публикации вакансии с типом free. Что именно нужно купить для бесплатных вакансий — не понятно. Решение: указать type: standard;

    бесплатные вакансии не доступны для многих регионов. Видимо для региона, в котором вы размещали вакансию, она не доступна

  3. iriss22
    /#20523131

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

    В API нет аккаунта, связанного с API. Вы можете использовать API под любым аккаунтом. Так же нет понятия мастер-аккаунт. Менеджеры ни от кого не наследуются.
    Ошибка quota_exceeded возникает, когда у менеджера закончилась квота на публикацию вакансий данного типа. Эту квоту можно настроить на сайте (https://hh.ru/employer/settings/quotas).
    Если у вас все еще есть вопросы по данной теме, напишите, пожалуйста на адрес api@hh.ru

    • melodyn
      /#20523225

      Спасибо за уточнение, исправил в статье. С поддержкой контакт держим, но конкретно по данному случаю получился сломанный телефон.

  4. adanilkina
    /#20524781

    Привет! Что касается багов:

    quota_exceeded (квота менеджера на публикацию данного типа вакансии закончилась) —
    квоты менеджера конфигурируются через hh.ru/employer/settings/quotas, последний же раз мы её видели при опечатке standart вместо standard в поле type;

    если вы смогли поймать что-то подобное, мы бы не отказались от подробностей на api@hh.ru,
    т.к. при публикации вакансии с `"billing_type":{"id":"standart","name":"Стандарт"}` в теле запроса – получаю вполне вменяемую ошибку `400 Bad Request bad_json_data – billing_type`

    аналогично со второй ошибкой:
    duplicate (аналогичная вакансия уже опубликована) при использовании флага ignore_duplicates — возникает при совпадающих полях name и area, независимо от наличия флага игнорирования дубликатов.

    при сценарии, когда публикуется одна и таже вакансия, например трижды, и передается флаг `ignore_duplicates=true` — вакансия публикуется без ошибок.

    • melodyn
      /#20524817

      Про дубликаты я узнал отсюда: github.com/hhru/api/issues/392
      Мы внесли соответствующие изменения в код и ошибка пропала.

      По поводу воспроизведения `quota_exceeded` попробуем.

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