# SuperJob API: Найти компанию работодателя

Сценарий из mcp-everything. Актуально на 2026-10-24.

Карточка компании: описание, отрасль, число вакансий и сотрудников.

1. Найди компанию: GET /2.0/clients/ с keyword — названием, частью названия или адресом сайта. Чтобы видеть и компании без открытых вакансий, передай all = 1.
2. Получи подробности: GET /2.0/clients/{id}/ — description, industry, vacancy_count, staff_count, логотип.
3. Вакансии компании ищи через GET /2.0/vacancies/ с нужными фильтрами.

```bash
curl -G https://api.superjob.ru/2.0/clients/ -H "X-Api-App-Id: $SJ_APP_KEY" --data-urlencode 'keyword=Яндекс'
curl https://api.superjob.ru/2.0/clients/<id>/ -H "X-Api-App-Id: $SJ_APP_KEY"
```

## Базовые URL

- Боевой: `https://api.superjob.ru`
- Формат: `https://api.superjob.ru/:version/method_name/:params`

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

Тип: OAuth 2.0

- Секретный ключ приложения передаётся в каждом запросе в заголовке `X-Api-App-Id`.
- Для методов с авторизацией — `Authorization: Bearer <access_token>`.
- Авторизация пользователя: `GET https://www.superjob.ru/authorize/` (`client_id`, `redirect_uri`, `state`) → код → `https://api.superjob.ru/2.0/oauth2/access_token/` (`code`, `client_id`, `client_secret`, `redirect_uri`).
- Обновление: `GET https://api.superjob.ru/2.0/oauth2/refresh_token/` (`refresh_token`, `client_id`, `client_secret`).
- Для desktop-приложений — вход по паролю `POST /2.0/oauth2/password/`.

## Методы сценария

### GET /2.0/vacancies/ — Поиск вакансий

Также поддерживается POST. Контакты в вакансиях — только с авторизацией. В ответе: `objects`, `total`, `more`, при опечатке — `corrected_keyword`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `X-Api-App-Id` | header | string | да | Секретный ключ приложения |
| `keyword` | query | string | нет | Поиск по всему тексту вакансии |
| `keywords` | query | array | нет | Расширенный поиск: блок, тип совпадения, исключаемые слова |
| `town` | query | string | нет | Город (название или ID) |
| `t` | query | array | нет | ID городов |
| `o` | query | array | нет | ID областей |
| `c` | query | array | нет | ID стран |
| `m` | query | array | нет | ID станций метро |
| `catalogues` | query | string | нет | Отрасли (ключи из справочника каталогов) |
| `payment_from` | query | integer | нет | Зарплата от |
| `payment_to` | query | integer | нет | Зарплата до |
| `no_agreement` | query | integer | нет | 1 — скрыть вакансии «по договорённости» |
| `experience` | query | integer | нет | Опыт работы |
| `type_of_work` | query | integer | нет | Тип занятости |
| `place_of_work` | query | integer | нет | Место работы |
| `education` | query | integer | нет | Образование |
| `period` | query | integer | нет | Период публикации: 24 часа, 3 дня, неделя или всё время |
| `order_field` | query | string | нет | date или payment |
| `order_direction` | query | string | нет | asc или desc (по умолчанию) |
| `page` | query | integer | нет | 0–500, по умолчанию 0 |
| `count` | query | integer | нет | 1–100, по умолчанию 20 |

### GET /2.0/clients/ — Поиск компаний

В ответе `objects` (`id`, `title`, `link`, `description`, `vacancy_count`, `staff_count`, `industry`, `client_logo`, `is_blocked`), `total`, `more`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `id_client` | query | integer | нет | ID компании |
| `keyword` | query | string | нет | Название, часть названия или URL компании |
| `town` | query | string | нет | Город |
| `all` | query | integer | нет | 1 — включая компании без вакансий |

### GET /2.0/clients/{id}/ — Компания по ID

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `id` | path | integer | да | ID компании |

## Нюансы

- Через API можно получить не больше 500 записей выдачи (`page` × `count`).
- В поиске вакансий массив `ids` — не больше 500 ID.
- Параметры `published`, `published_all`, `archive`, `not_archive` работают только при авторизации работодателя при поиске своих вакансий.
- Ошибки авторизации дополнительно возвращают машиночитаемый `error` (например, `invalid_token`) и заголовок `X-Oauth-Error`.
- Документация помечена как актуальная для версии 2.20; свежая версия — `https://api.superjob.ru/doc/`.

## Другие сценарии

- [Найти вакансии по запросу](https://mcp-everything.ru/integrations/superjob/scenarios/nayti-vakansii-po-zaprosu.md)
- [Авторизовать пользователя и показать контакты вакансии](https://mcp-everything.ru/integrations/superjob/scenarios/avtorizovat-polzovatelya-i-pokazat.md)

---

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