API Яндекс Директа позволяет управлять кампаниями программно: выгружать статистику, менять ставки, создавать объявления сотнями. Доступ к нему не выдаётся по умолчанию — ниже порядок, который проходит любой разработчик интеграции.
Шаг 1. Создайте OAuth-приложение
Откройте oauth.yandex.ru/client/new и создайте приложение:
- платформа — «Веб-сервисы»;
- Redirect URI — адрес, на который Яндекс вернёт пользователя после входа (для отладки подойдёт https://oauth.yandex.ru/verification_code);
- права —
direct:api(использование API Директа); если нужна статистика Метрики — ещёmetrika:read.
Приложение создаётся сразу. Вы получите ClientID и Client secret.
Шаг 2. Получите OAuth-токен
Токен выдаётся пользователю, который разрешает приложению доступ к своему рекламному аккаунту. Для отладки проще всего открыть в браузере:
https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID
После входа Яндекс покажет токен. В рабочей интеграции используют код подтверждения (response_type=code) и обмен его на токен на сервере — так токен не проходит через браузер.
Токен передаётся в каждом запросе заголовком Authorization: Bearer ТОКЕН. Если вы работаете от имени агентства с клиентским аккаунтом, добавьте заголовок Client-Login.
Шаг 3. Отладьте всё в песочнице
Песочница доступна сразу после создания приложения:
https://api-sandbox.direct.yandex.com/json/v5/
В ней создаётся тестовый кабинет, можно создавать кампании, менять ставки и запрашивать отчёты без реальных денег. Боевой адрес отличается только хостом: api.direct.yandex.com.
Шаг 4. Подайте заявку на боевой доступ
Заявка подаётся из интерфейса Директа: Настройки → «Доступ к API». Модерация обычно занимает несколько рабочих дней. Чаще всего просят:
- описание, что делает приложение и кто им пользуется;
- рабочий сайт сервиса с описанием функциональности;
- политику обработки персональных данных.
Если приложение только для себя, так и напишите — заявки на внутреннюю автоматизацию тоже одобряют.
Шаг 5. Учитывайте баллы API
Каждый вызов расходует баллы рекламного аккаунта. Суточный лимит зависит от расходов аккаунта, а остаток приходит в заголовке ответа Units в виде «потрачено/осталось/лимит». Массовые операции выгоднее делать пачками — один запрос на много объектов стоит дешевле, чем много запросов по одному.
Отчёты формируются в офлайн-режиме: на запрос тяжёлого отчёта API может ответить кодом 201 или 202 — это значит «отчёт готовится, повторите запрос позже».
Частые ошибки
- Код 53 — ошибка авторизации: токен истёк, отозван или выдан другому приложению.
- Код 58 — у приложения нет доступа к API (заявка не подана или не одобрена).
- Код 152 — недостаточно баллов.
- Код 513 — пользователь не подключён к Директу или логин указан неверно.
Полный разбор кодов — в справочнике ошибок API Яндекс Директа.
Когда своя интеграция не нужна
Если цель — работать с Директом через нейросеть (Claude, ChatGPT, Yandex AI Studio), писать код, получать доступ к API и следить за баллами не обязательно. AdCab — готовый MCP-сервер: вход через Яндекс, отчёты, семантика, ставки и чистка РСЯ в чате, а каждое изменение применяется только после вашего подтверждения. Один аккаунт — бесплатно.
Коротко
- OAuth-приложение на oauth.yandex.ru с правом
direct:api. - Токен пользователя, заголовок
Authorization: Bearer. - Отладка в песочнице.
- Заявка на боевой доступ в настройках Директа.
- Контроль баллов и офлайн-отчётов.