negotiations.md

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

Документация по переписке для работодателя доступна в отдельной статье.

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

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

• Получение списка откликов
• Получение списка активных откликов
• Откликнуться на вакансию
• Просмотр отклика/приглашения
• Скрыть отклик
• Просмотр списка сообщений в отклике
• Отправка нового сообщения
• Редактирование сообщения в отклике

Получение списка откликов

Запрос

GET /negotiations

Помимо стандартных параметров пагинации page и per_page, поддерживаются:

Имя	Обязательный	Описание
order_by	нет	тип сортировки, возможные значения указаны в справочнике negotiations_order
order	нет	направление сортировки. Возможные значения: asc, desc.
vacancy_id	нет	фильтр по id вакансии
status	строка	учитывать только отклики находящиеся в определенном статусе. Возможные значения указаны в справочнике applicant_negotiation_status
has_updates	boolean	учитывать только отклики для которых есть непросмотренные сообщения

По умолчанию отклики сортируются по последнему обновлению от новых к старым.

Ответ

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

{
    "found": 1,
    "pages": 1,
    "per_page": 20,
    "page": 0,
    "items": [
        {
            "id": "123",
            "state": {
                "id": "invitation",
                "name": "Приглашение"
            },
            "hidden": false,
            "created_at": "2013-10-05T19:51:38+0400",
            "updated_at": "2013-10-07T18:30:57+0400",
            "url": "https://api.hh.ru/negotiations/123",
            "resume": {},
            "vacancy": {},
            "has_updates": true,
            "viewed_by_opponent": true,
            "messaging_status": "ok",
            "decline_allowed": true
        }
        // , .....
    ]
}

где:

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

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

Имя	Тип	Описание
id	строка	Идентификатор отклика
state	объект	Текущее состояние отклика. Разрешенные значения находятся в справочнике /dictionaries в разделе negotiations_state
hidden	логический	Скрыт ли текущий отклик (True - отклик скрыт, False - отклик активен)
created_at	строка	Дата и время создания отклика
updated_at	строка	Дата и время последнего обновления отклика
url	строка	Ссылка на полную версию отклика
resume	объект, null	Короткое представление резюме
vacancy	объект, null	Короткое представление вакансии
has_updates	логический	Есть ли непросмотренные сообщения в отклике. Флаг сбрасывается при различных действиях по отклику, например, просмотре списка сообщений.
viewed_by_opponent	логический	Был ли отклик просмотрен работодателем
messaging_status	строка	Текущий статус переписки. Возможные значения находятся в справочнике messaging_status.
decline_allowed	Логический	Возможно ли скрыть отклик вместе с сообщением работодателю об отказе

В объекте вакансии ключи url и alternate_url могут быть null, если вакансия недоступна (удалена).

Получение списка активных откликов

Запрос

Для получения списка активных откликов используйте параметр status=active в запросе списка откликов

GET /negotiations?status=active

До 20.04.20 для запроса активных вакансий использвался ресурс:

GET /negotiations/active

В настоящее время он является устаревшим и поддерживается для обратной совместимости.

Откликнуться на вакансию

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

Запрос

POST /negotiations

Запрос нужно отправить с Content-Type = multipart/form-data и следующими параметрами:

Имя	Обязательный	Описание
vacancy_id	да	Идентификатор вакансии, на которую происходит отклик
resume_id	да	Идентификатор резюме, которым производится отклик
message	да	Сопроводительное письмо к отклику. Является обязательным, если в вакансии указано, что обязательно сопроводительное письмо, максимальная длина - 10000 символов

Ответ

В случае успеха приходит статус 201 Created, а в заголовке Location ответа будет содержаться ссылка на созданный отклик (кроме direct вакансий, см. ниже)

HTTP/1.1 201 Created
...
Location: /negotiations/123
...

Вакансии с прямым откликом

Для вакансий, у которых тип direct, ответ будет приходить с кодом 303 See Other.

HTTP/1.1 303 See Other
...
Location: http://example.com/respond/vacancy
...

Вакансии с типом direct – это вакансии с прямым откликом. У данных вакансий непустой response_url – внешний url на сайт работодателя, который отдается в заголовке Location при попытке откликнуться. Используйте response_url, чтобы предложить пользователю откликнуться на вакансию на сайте работодателя вместо стандартного механизма откликов.

Ошибки

• 400 Bad Request – если указанные вакансия или резюме не существуют; либо для отклика необходимо пройти тест или заполнить сопроводительное письмо; либо работодатель закрыл возможность присылать отклики на вакансию; либо количество откликов в день для пользователя превышено.
• 403 Forbidden - если на указанную вакансию не возможно откликнуться, по причине отсутствия доступа к ней или из-за того, что уже был отклик ранее или если настройки видимости выбранного резюме не позволяют откликнуться на вакансию.

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

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

Запрос

GET /negotiations/{nid}

где nid - идентификатор отклика.

Ответ

Возвращаемый объект полностью идентичен отдельному отклику, получаемому в списке откликов

Скрыть отклик

Для скрытия отклика необходимо выполнить запрос:

DELETE /negotiations/active/{nid}

где:

• nid - идентификатор отклика

Параметры

Имя	Тип	Обязательный	Описание
with_decline_message	логический	нет	Должно ли быть отправлено работодателю сообщение об отказе, по умолчанию false. Возможность отправить сообщение об отказе определяется полем decline_allowed получаемым при запросе списка откликов или одного отклика

Успешный ответ приходит с кодом 204 No Content.

Ошибки

• 403 Forbidden - невозможно отправить сообщение об отказе.
• 404 Not Found - отклик не существует.

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

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

Запрос

GET /negotiations/{nid}/messages

где:

• nid - идентификатор отклика

Параметры

Имя	Тип	Обязательный	Описание
page	число	нет	Номер страницы, значение по умолчанию 0
per_page	число	нет	Количество элементов на страницу, по умолчанию 20

Ответ:

{
    "found": 1,
    "pages": 1,
    "per_page": 20,
    "page": 0,
    "items": [
        {
            "id": "123",
            "viewed_by_me": true,
            "viewed_by_opponent": true,
            "created_at": "2013-10-07T18:30:57+0400",
            "text": "Вас приглашает очень крупный иностранный банк на зарплату, о которой мечтают арабские шейхи",
            "state": {
                "id": "invitation",
                "name": "Приглашение"
            },
            "author": {
                "participant_type": "employer"
            },
            "address": null,
            "assessments": [
                {
                    "id": "123",
                    "name": "Динамический тест числовых способностей",
                    "actions": [
                        {
                            "id": "proceed",
                            "name": "Перейти к тестированию",
                            "enabled": true,
                            "alternate_url": "https://hh.ru/applicant/assessment/123"
                        }
                    ]
                }
            ],
            "editable": false
        },
        {
            "id": "124",
            "viewed_by_me": true,
            "viewed_by_opponent": false,
            "created_at": "2013-10-08T10:12:23+0400",
            "text": "Верблюда и коня мне!",
            "state": {
                "id": "text",
                "name": "Текст"
            },
            "author": {
                "participant_type": "applicant"
            },
            "address": null,
            "editable": false
        }
    ]
}

где:

Имя	Тип	Описание
found	число	Количество найденных сообщений
pages	число	Количество найденных страниц с сообщениями
per_page	число	Количество элементов на страницу
page	число	Номер текущией страницы (начинается с 0)
items	массив	Массив сообщений, см. ниже

Отдельное сообщение имеет следующую структуру:

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

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

Отправка нового сообщения работодателю возможна после того, как работодатель пригласил соискателя на вакансию. Сообщения можно отправлять и в случае отказа после собеседования. Если вакансия была отправлена в архив или соискатель удалил резюме, переписка будет недоступна. Работодатель также может вручную отключить переписку для вакансии.

Запрос

POST /negotiations/{nid}/messages

где:

• nid - идентификатор отклика

Параметры

Имя	Обязательный	Описание
message	да	Текст сообщения

Ответ

Успешный ответ приходит с кодом 201 Created и содержит добавленный комментарий:

{
    "id": "124",
    "viewed_by_me": true,
    "viewed_by_opponent": false,
    "created_at": "2013-10-08T10:12:23+0400",
    "text": "Верблюда и коня мне!",
    "state": {
        "id": "text",
        "name": "Текст"
    },
    "author": {
        "participant_type": "applicant"
    },
    "address": null,
    "editable": false
}

Ошибки

• 404 Not Found - при отсутствии отклика с указанным идентификатором
• 403 Forbidden – если отправить сообщение не удалось

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

Редактирование сообщений в отклике

При некоторых условиях текст сообщения можно редактировать после отправки. Чтобы определить, доступно ли редактирование сообщения, необходимо использовать флаг editable.

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

Запрос

PUT /negotiations/{nid}/messages/{mid}

где:

• nid - идентификатор отклика
• mid - идентификатор сообщения в отклике

Параметры

Имя	Обязательный	Описание
message	да	Текст сообщения

Ответ

В случае успешного обновления текста сообщения вернётся HTTP-статус 204 No Content.

Ошибки

• 403 Forbidden - в случае, когда редактирование сообщения запрещено. Например, принимающая сторона уже успела прочитать сообщение.
• 404 Not Found - если сообщение не было найдено.

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