# HeadHunter API (hh.ru): POST /vacancies — Публикация вакансии

При успешной публикации списываются услуги работодателя; конкретный пакет задаётся `employer_service_id`, иначе выбирается автоматически. Все вакансии проходят ручную модерацию и появляются в поиске через несколько минут. Успех — `201`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `ignore_duplicates` | query | boolean | нет | Принудительно добавить дубликат |
| `name` | body | string | да | Название |
| `description` | body | string | да | Описание в HTML |
| `area` | body | object | да | Регион |
| `professional_roles` | body | array | да | Профессиональные роли |
| `vacancy_properties` | body | object | нет | Свойства публикации (заменяет устаревшие type и billing_type) |
| `employer_service_id` | body | string | нет | Пакет услуг из suitable_packages[].employer_service_id |
| `salary_range` | body | object | нет | Зарплата (поле salary устарело) |
| `address` | body | object | нет | Адрес |
| `experience` | body | object | нет | Опыт работы |
| `employment_form` | body | object | нет | Тип занятости |
| `work_format` | body | array | нет | Форматы работы |
| `work_schedule_by_days` | body | array | нет | Графики работы |
| `working_hours` | body | array | нет | Рабочие часы в день |
| `key_skills` | body | array | нет | Ключевые навыки |
| `contacts` | body | object | нет | Контакты; при использовании нужен атрибут phones |
| `code` | body | string | нет | Внутренний код вакансии |
| `department` | body | object | нет | Департамент работодателя |
| `manager` | body | object | нет | Менеджер вакансии |
| `previous_id` | body | string | нет | ID архивной вакансии для связи с новой |
| `response_letter_required` | body | boolean | нет | Обязательно сопроводительное письмо |
| `test` | body | object | нет | Тест для вакансии |

## Базовые URL

- Боевой: `https://api.hh.ru`
- Запросы ко всем сайтам группы идут на один адрес; нужный сайт задаётся параметром  (по умолчанию ), локаль: `?host=`

## Авторизация

Тип: OAuth 2.0

OAuth 2.0. Токен передаётся в заголовке `Authorization: Bearer {ACCESS_TOKEN}`.

- Токен пользователя (authorization code): пользователь открывает `https://hh.ru/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}`, затем `authorization_code` из редиректа обменивается на `access_token` и `refresh_token` запросом `POST https://api.hh.ru/token`. Поддерживается PKCE (`code_challenge`, `code_challenge_method=S256`).
- Обновление: `POST https://api.hh.ru/token` с `refresh_token`; refresh-токен одноразовый и работает только после истечения `access_token` (срок — `expires_in`, в секундах).
- Токен приложения (client credentials): срок жизни не ограничен, при повторном запросе прежний отзывается; запрашивать не чаще раза в 5 минут. Актуальный токен виден владельцу на `https://dev.hh.ru/admin`.

Параметры `/oauth/authorize`: `skip_choose_account=true` — не показывать выбор аккаунта, `force_login=true` — всегда показывать форму входа, `role` (`applicant` или `employer`) с `force_role=true` — требовать нужную роль.

В каждом запросе обязателен заголовок `User-Agent` или `HH-User-Agent` (при обоих учитывается `HH-User-Agent`); без него — `400 Bad Request`.

```
User-Agent: MyApp/1.0 (my-app-feedback@example.com)
```

## Нюансы

- Пагинация: `page=N&per_page=M`, нумерация с нуля; ответ — `found`, `per_page`, `pages`, `page`, `items`.
- Неизвестные и недокументированные параметры игнорируются; недокументированные поля в ответах не рекомендуется использовать.
- Длинные ответы сжимаются gzip.
- Поддерживается CORS; для отладки есть `/cors` (HEAD, GET, POST, PUT, DELETE), для JSONP — `?callback=callback_name`.
- Вебхуки: на одно приложение — один URL. Ваш сервер отвечает `2xx` или `409` для дубликата (определяется по `id`). Без ответа за 5 секунд колбэк отправляется повторно; доставка не гарантирована. При долгих сбоях подписка блокируется, при отзыве доступа удаляется.
- Методы `/negotiations/{nid}/messages` устарели — переписка ведётся через `/common/chats`.
- Просмотр резюме с контактами списывает контакт один раз на компанию; если контакты скрыты соискателем, просмотр всё равно спишется — проверяйте `hidden_fields`.

## Сценарии с этим методом

- [Опубликовать вакансию от имени работодателя](https://mcp-everything.ru/integrations/hh-api/scenarios/opublikovat-vakansiyu-ot-imeni.md)

---

Если этого недостаточно — официальная документация: https://api.hh.ru/openapi/redoc
Вся интеграция одним документом: https://mcp-everything.ru/integrations/hh-api.md