HH.ru Integration Landscape — май 2026

artifacts/hh-integration-landscape-2026.html · hr-tech · 2026-05-27

TL;DR. Прямой URL spb.hh.ru — это только UI. Для интеграции нужны три домена: api.hh.ru (endpoints), dev.hh.ru (регистрация OAuth-приложений), github.com/hhru/api (документация + OpenAPI). После 15 декабря 2025 публичный API для соискателей закрыт — остались анонимные read-only endpoints, employer-side API и серая зона UI-эмуляции.
Содержание
  1. Контекст: водораздел 15.12.2025
  2. Decision tree: какой канал выбрать
  3. MCP-варианты — 3 пути
  4. OAuth flow — диаграмма
  5. Что доступно / что закрыто
  6. Legal landscape
  7. Practical recipe
  8. Caveats и открытые вопросы

1. Контекст: водораздел 15 декабря 2025

HH.ru исторически имел открытый публичный API через OAuth 2.0 — с тремя уровнями доступа (anonymous, application, user). На основе этого API выросла экосистема: ATS-интеграции (Huntflow, Talantix), скрипты автоматизации, AI-ассистенты, MCP-серверы для LLM-агентов.

15 декабря 2025 года HH одним движением закрыл одну сторону этой экосистемы — сторону соискателя. Официальная мотивация: борьба с мошенничеством и нерелевантными авто-откликами. Эффект: любая интеграция, действующая от имени кандидата, перестала работать.

До 15.12.2025. Открытый API: job-seeker apply, чтение своих negotiations, AI-ассистенты-кандидаты, авто-отклики через official channel.
15.12.2025. Закрытие public job-seeker API. Затронуты POST /negotiations, action-endpoints на стороне соискателя.
Декабрь 2025 — Q1 2026. Волна архивирования third-party клиентов (@sargonpiraev/hh-api-client archived 23.04.2026).
Май 2026. Остаются: anonymous read-only API, employer-side API, серая зона UI-эмуляции. Готовый MCP-сервер gmen1057/headhunter-mcp-server покрывает поиск, но action-tool'ы под риском.

2. Decision tree: какой канал выбрать

Выбор интеграционного канала однозначно определяется стороной (employer vs job-seeker) и action vs read-only. Поток ниже работает как чек-лист.

На чьей стороне сценарий? employer / job-seeker / public employer public read-only job-seeker action Employer OAuth + API vacancies, negotiations, resume search, webhooks Anonymous endpoints /vacancies, /dictionaries, /areas — без OAuth Готов нарушать ToS + 152-ФЗ? только личный риск нет да Manual / no automation ручные отклики через UI; единственный легальный путь UI emulation (серая зона) Playwright / Puppeteer; штрафы 150K–5M руб Хочешь готовое решение? ATS vs собственная интеграция да нет ATS Huntflow, Talantix, etc. Custom + MCP OpenAPI + MCP SDK обёртка LLM-агенту нужен инструмент? MCP vs direct HTTP да нет gmen1057 MCP search/dict/areas tools работают Direct HTTP User-Agent + curl/httpx/fetch Легенда легально и работает серая зона / риск недоступно / запрещено решение

3. MCP-варианты — три пути

1. gmen1057/headhunter-mcp-server

готовое action под риском

Python 3.10+, MIT, 10 tools. Поиск, vacancy, employer, similar, areas, dictionaries, resumes*, apply*, negotiations*.

Идеально для: read-only job-search assistant, агент-агрегатор.

Слабое место: hh_apply_to_vacancy и hh_get_negotiations — это job-seeker API, частично заблокированы 15.12.2025.

2. Apify-обёртки (scraper MCP)

серая зона

Готовые MCP-endpoints от easyapi/hh-ru-job-scraper и scrapestorm. Работают через HTML-парсинг, а не официальный API.

Идеально для: когда anonymous endpoints не хватает, риск приемлем.

Слабое место: нарушение ToS HH, периодические поломки от антибот-мер.

3. Собственная реализация

полный контроль

OpenAPI HH (api.hh.ru/openapi/redoc) → генерируешь клиент → оборачиваешь в MCP tools через @modelcontextprotocol/sdk или mcp (Python).

Идеально для: production employer-сценарии, кастомные workflows.

Слабое место: требует разработки и поддержки.

Pre-flight check для gmen1057. Перед production-использованием — прогнать каждый из 10 tool'ов на актуальном API. hh_search_vacancies, hh_get_areas, hh_get_dictionaries — анонимные, должны работать. hh_apply_to_vacancy, hh_get_negotiations — практически наверняка нет на стороне соискателя.

Конфиг Claude Code для gmen1057

{
  "mcpServers": {
    "headhunter": {
      "type": "stdio",
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/headhunter-mcp-server/server.py"],
      "env": {
        "HH_CLIENT_ID": "...",
        "HH_CLIENT_SECRET": "...",
        "HH_APP_TOKEN": "...",
        "HH_REDIRECT_URI": "https://your-domain.com/oauth/callback"
      }
    }
  }
}

4. OAuth flow — диаграмма

Два сценария авторизации. Application — для server-to-server без участия пользователя. User (authorization code) — для действий от имени конкретного employer-менеджера.

Регистрация dev.hh.ru/admin → client_id, secret A. Application flow (server-to-server) POST https://hh.ru/oauth/token grant_type=client_credentials client_id=... & client_secret=... → access_token (для anonymous-расширенных endpoints) B. User flow (authorization code grant) — для employer-менеджера / соискателя 1. Redirect пользователя на: https://hh.ru/oauth/authorize?response_type=code&client_id=...&redirect_uri=... 2. Юзер логинится в HH, разрешает доступ → редирект на redirect_uri?code=<auth_code> 3. Обмен кода на токены: POST /oauth/token grant_type=authorization_code & code=... → access_token + refresh_token (для user-context действий)
Обязательно во всех запросах. Header Authorization: Bearer <token> для авторизованных + header User-Agent: AppName/Version (contact@email) для всех, включая anonymous. Без User-Agent ответ 400. Только домен api.hh.ru — m.hh.ru deprecated для OAuth.

5. Что доступно / что закрыто

Endpoint / возможность Авторизация Статус Кому применимо
GET /vacancies — поиск anonymous открыт все
GET /vacancies/{id} — детали anonymous открыт все
GET /vacancies/{id}/similar_vacancies anonymous открыт все
GET /dictionaries, /areas, /industries anonymous открыт все
GET /employers/{id} — публичная info anonymous открыт все
POST /vacancies — создание employer OAuth открыт employer
GET /negotiations на свои вакансии employer OAuth открыт employer
GET /resumes — поиск кандидатов employer OAuth + подписка открыт employer
Webhook subscriptions на employer-события employer OAuth открыт employer
POST /negotiations — отклик соискателя user OAuth (job-seeker) закрыт 15.12.2025 —
Программное чтение своих переписок user OAuth (job-seeker) закрыт 15.12.2025 —
AI-агент от имени кандидата user OAuth (job-seeker) закрыт 15.12.2025 —
HTML-скрейпинг страниц — запрещён ToS всегда —
Штрафы 152-ФЗ (после ужесточения 2025).

Разрешено через API

Запрещено

7. Practical recipe

7.1 Минимальный read-only тест (без регистрации)

curl -H 'User-Agent: TestApp/0.1 (test@example.com)' \
  'https://api.hh.ru/vacancies?text=python&area=2&per_page=5'
# area=2 — Санкт-Петербург; area=1 — Москва

7.2 Регистрация приложения (для OAuth)

1. Аккаунт на hh.ru (employer или соискатель)
2. dev.hh.ru/admin → «Создать приложение» → название, описание, redirect_uri
3. Получаешь client_id, client_secret, опционально app_token
4. Соглашение разработчика: dev.hh.ru/admin/developer_agreement

7.3 Production employer-интеграция через MCP

  1. Скачать OpenAPI: curl https://api.hh.ru/openapi/openapi.json > hh-openapi.json
  2. Сгенерировать клиент: openapi-generator-cli generate -i hh-openapi.json -g typescript-fetch -o ./client
  3. Реализовать OAuth flow (authorization code) с redirect-callback'ом
  4. Обернуть нужные endpoint'ы в MCP tools через @modelcontextprotocol/sdk
  5. Добавить в ~/.claude.json с переменными окружения для токенов
  6. Rate-limit: ориентир ≤ 3000 запросов/сутки на токен (community-эмпирика)

8. Caveats и открытые вопросы

Откуда это построено