Skip to content

Latest commit

 

History

History
348 lines (270 loc) · 22.5 KB

employer_negotiations.md

File metadata and controls

348 lines (270 loc) · 22.5 KB

Переписка (отклики/приглашения) для работодателя

Модель работы, термины и процедуры

Отклики и приглашения соответствуют модели, которая выражается в запросах и ответах API. Если приложение использует модель правильно, то изменение бизнес-логики откликов и приглашений не будет требовать переработки или исправления.

В откликах и приглашениях используются понятия:

  • отклик – объект, порождённый по инициативе соискателя (отклик на вакансию). Отклик всегда происходит одним резюме на одну вакансию.

  • приглашение – объект, порождённый по инициативе работодателя (приглашение на вакансию). Приглашение всегда происходит к одному резюме на одну вакансию.

Кроме процесса появления объекта, работа с откликом или приглашением происходит одинаково.

  • коллекция – набор откликов/приглашений, объединённых по определённым критериям. Коллекции используются, когда в вашем приложении требуется отобразить список откликов/приглашений. Не стоит полагаться на то, что в определённые этапы обработки отклика/приглашения оно будет входить в известные коллекции, так как эта логика может изменяться.

  • соискательское состояние отклика/приглашения – статус отклика/приглашения (поле state), который видит соискатель. Возможные значения выдаются в справочнике negotiations_state и не зависят от вакансии в отклике/приглашении.

  • работодательское состояние отклика/приглашения – статус отклика/приглашения у работодателя. Может отличаться от соискательского. Список возможных статусов зависит от вакансии и работодателя, поэтому список необходимо запрашивать, передавая нужную вакансию.

  • действие по отклику/приглашению – действие, которое можно выполнить над откликом/приглашением. В результате действия работодательское и соискательское состояния отклика/приглашения могут как поменяться, так и остаться прежними.

Не следует путать действие, коллекцию и состояние – они могут быть похожи, но предназначены для разных целей.

Общее описание процесса работы с откликами/приглашениями

Вся работа с откликами/приглашениями происходит в рамках одной выбранной вакансии. Даже у одного работодателя могут быть вакансии с различными правилами работы по откликам/приглашениям.

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

Для создания приглашения необходимо запросить вакансии работодателя, применимые к выбранному резюме. Получить эту информацию можно в списке вакансий работодателя, там же будут указаны необходимые параметры (ключ arguments) и состояние созданного отклика (ключ resulting_employer_state). У разных работодателей и разных вакансий могут быть различные правила и состояния добавляемого отклика. Для каждой пары вакансия + резюме может быть только один отклик/приглашение.

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

Если вам необходимо совершить действие по отклику/приглашению, ориентируйтесь на список действий, который будет доступен в списке (коллекции) откликов/приглашений и в отдельном отклике/приглашении. Если действие приводит к смене состояния по отклику/приглашению, это будет явно указано в ключе resulting_employer_state. Не все действия приводят к смене состояния.

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

Чтобы соискательский отклик считался просмотренным работодателем необходимо сделать одно из следующих действий:

Коллекции и работодательские состояния откликов/приглашений по вакансии

!! Данный метод доступен в OpenAPI

Список откликов/приглашений

!! Данный метод доступен в OpenAPI

Просмотр отклика/приглашения

!! Данный метод доступен в OpenAPI

Просмотр списка сообщений в отклике/приглашении

‼️ Обратите внимание, что методы для работы с сообщениями в рамках отклика/приглашения от имени менеджера работодателя устарели, и новые возможности чатов в них не будут поддерживаться. В связи с этим переписка может некорректно отображаться.

Сообщения в отклике/приглашении могут быть:

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

Для того, чтобы посмотреть список сообщений в отклике необходимо сделать запрос по урлу (поле messages_url), пришедшему в списке откликов/приглашений или в просмотре отклика/приглашения. Например:

GET /negotiations/123456789/messages

Параметры:

Имя Обязательный Принимаемые значения Описание
with_text_only нет true/false Вернуть только те сообщения, которые содержат текст в поле text, по умолчанию: false, т.е. будут возвращены все сообщения

Ответ

Успешный ответ приходит с кодом 200 OK и содержит:

{
   "found": 2,
   "pages": 1,
   "page": 0,
   "per_page": 20,
   "items": [
       {
           "id": "123",
           "text": "Приглашаем вас на нашу вакансию ...",
           "created_at": "2015-05-15T19:23:35+0300",
           "author": {
               "participant_type": "employer"
           },
           "viewed_by_opponent": true,
           "viewed_by_me": true,
           "state": {
               "id": "invitation",
               "name": "Приглашение"
           },
           "address": {
                "building": "10",
                "city": "Москва",
                "description": "Направо под знак",
                "lat": 35.0,
                "lng": 30.0,
                "metro": {
                    "lat": 55.789704,
                    "line_id": "2",
                    "line_name": "Замоскворецкая",
                    "lng": 37.558212,
                    "station_id": "2.34",
                    "station_name": "Динамо"
                },
                "metro_stations": [
                    {
                        "lat": 55.789704,
                        "line_id": "2",
                        "line_name": "Замоскворецкая",
                        "lng": 37.558212,
                        "station_id": "2.34",
                        "station_name": "Динамо"
                    }
                ],
                "street": "ул. Динамо"
            },
            "assessments": [
                {
                    "id": "123",
                    "name": "Динамический тест числовых способностей",
                    "actions": [
                        {
                            "id": "proceed",
                            "name": "Перейти к тестированию",
                            "enabled": true,
                            "alternate_url": "https://hr.zarplata.ru/applicant/assessment/123"
                        }
                    ]
                }
            ]
       },
       {
           "id": "321",
           "text": "Отлично, с удовольствием пройду интервью ...",
           "created_at": "2015-05-15T19:23:35+0300",
           "author": {
               "participant_type": "applicant"
           },
           "viewed_by_me": false,
           "viewed_by_opponent": true,
           "state": {
               "id": "text",
               "name": "Текст"
           },
           "address": null
       }
   ]
}

где:

Имя Тип Описание
found число Количество сообщений в переписке ( ≥ 0 )
pages число Количество страниц с сообщениями ( ≥ 1 )
per_page число Количество сообщений на страницу ( > 0 )
page число Номер текущей страницы ( ≥ 0 )

Сообщения отсортированы в следующем порядке: самое старое - первое, самое новое - последнее.

В элементе items содержатся данные о сообщениях:

Имя Тип Описание
id строка Идентификатор сообщения
viewed_by_me логический Прочитано ли сообщение смотрящим (для сообщений отправленных работодателем всегда true)
viewed_by_opponent логический Прочитано ли сообщение соискателем (для сообщений соискателя всегда true)
created_at строка Дата и время создания сообщения
text строка, null Текст сообщения. null может быть в случае, когда соискатель не оставил сопроводительное письмо к отклику.
state объект Текущее состояние отклика. Возможные значения находятся в справочнике /dictionaries в разделе negotiations_state
author объект Кто автор сообщения
author.participant_type строка Роль автора сообщения. Возможные значения находятся в справочнике /dictionaries в разделе negotiations_participant_type
address объект, null Адрес, привязанный к отклику/приглашению
assessments массив инструменты оценки, привязанные к сообщению

В случае, когда отклик/приглашение не существует или переписка недоступна текущему пользователю возвращается ответ 404 Not Found.

Отправка сообщения в отклике/приглашении

!! Данный метод доступен в OpenAPI

Приглашение соискателя на вакансию

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

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

Для того, чтобы пригласить соискателя нужно выполнить запрос, пришедший в поле negotiations_actions[].url, передав аргументы, содержащиеся в поле arguments, например:

Запрос

POST /negotiations/phone_interview?resume_id=123456&vacancy_id=654321&message=new_msg

Параметры необходимо отправлять в стандартном формате application/x-www-form-urlencoded.

Ответ

Успешный ответ приходит с кодом 201 Created, не содержит тело и содержит заголовок Location, указывающий на созданное приглашение:

HTTP/1.1 201 Created

Location: /negotiations/321

Ошибки

  • 400 Bad Request – ошибка в параметрах запроса.
  • 403 Forbidden – приглашение невозможно.

Дополнительно к HTTP коду сервер может вернуть описание причины ошибки.

Например:

  • already_invited - если отклик между переданными резюме и вакансией уже существует
  • resume_not_found – если переданное резюме было скрыто либо удалено
  • invalid_vacancy - если переданная вакансия была архивирована либо скрыта
  • limit_exceeded - если превышен лимит менеджера на количество приглашений в сутки
  • application_denied - общая ошибка запрета приглашения в случае, когда дополнительная информация недоступна
  • address_not_found – если переданный адрес не существует, либо принадлежит другому работодателю
  • not_enough_purchased_services - не хватает оплаченных услуг, обычно доступа к базе резюме

Действия по отклику/приглашению

!! Данный метод доступен в OpenAPI

Просмотр предпочитаемой сортировки откликов

!! Данный метод доступен в OpenAPI

Изменение предпочитаемой сортировки откликов

Запрос

!! Данный метод доступен в OpenAPI