API Яндекс.Директ: как получить токен, настроить доступ и автоматизировать кампании

Что такое API Яндекс.Директа и кому он нужен

Yandex Direct API (актуальная версия v5, путь запросов — v501) — бесплатный HTTPS-интерфейс: вы отправляете POST-запросы с JSON-телом на адреса вида https://api.direct.yandex.com/json/v501/{сервис}. В ответ приходят структурированные данные о кампаниях, объявлениях, ключевых фразах, ставках и статистике.

API нужен, когда объём операций перестаёт помещаться в интерфейс:

• Агентствам и in-house командам — единый скрипт на 15–50 аккаунтов: пауза кампаний при нулевом остатке, ночная корректировка ставок, выгрузка отчётов в дашборд.
• E-commerce и маркетплейсам — синхронизация остатков SKU с объявлениями: товар закончился → объявление на паузе.
• Аналитикам — регулярные Reports в TSV, стыковка с сквозной аналитикой и целями Метрики для заявок.
• Интеграторам — связка Директа с системами учёта клиентов, антифродом, no-code (n8n) или AI-обёртками поверх API.

Чем API не является: это не замена стратегии и не волшебная кнопка «запустить рекламу». Сначала в кабинете должна быть хотя бы одна кампания (требование для заявки на доступ), а базовая настройка Яндекс.Директа или пошаговый запуск в 2026 остаются фундаментом.

API vs ручная работа vs Директ Коммандер. Коммандер закрывает массовое редактирование офлайн-файлами — без кода. API — когда нужна логика: «если CPA выше порога три дня подряд — снизить ставку на 15 %» или «каждое утро в Telegram — расход и конверсии по клиентам». Для разовой выгрузки и правки 200 фраз Коммандер часто быстрее; для ежедневной автоматизации без участия человека — API.

Как получить OAuth-токен для Яндекс.Директа

Токен яндекс директ — это не «пароль от кабинета», а OAuth-access token: строка, которую приложение подставляет в заголовок Authorization: Bearer . Один токен = один пользователь Директа; права приложения не шире прав этого пользователя в интерфейсе.

Полный путь доступа — три этапа (официальная документация Яндекса):

1. Зарегистрировать OAuth-приложение в Яндекс ID.
2. Подать заявку на доступ к API в настройках Директа.
3. Получить api токен яндекс директ для каждого пользователя, от имени которого идут запросы.

Регистрация приложения в Yandex OAuth

Перейдите в консоль разработчика Яндекс ID и создайте приложение с типом «Для доступа к API или отладки».

Обязательные параметры:

• Права (scope): direct:api — доступ к API Директа. С июня 2025 года для работы с организациями рекомендован дополнительный scope passport:business.
• Client ID и Client secret — это и есть то, что в быту называют яндекс директ api ключ в паре с токеном: секрет приложения храните отдельно от access token.
• Redirect URI — для отладки: https://oauth.yandex.ru/verification_code; для production — ваш HTTPS-callback.

Запишите Client ID и Client secret в менеджер секретов (не в репозиторий и не в общий чат).

Пошаговое получение токена (authorization code flow)

Есть два режима — ручной (отладка) и автоматический (боевые интеграции).

Ручной (debug token) — для первого знакомства и тестов в песочнице:

1. Откройте в браузере:

https://oauth.yandex.ru/authorize?response_type=token&client_id=<ВАШ_CLIENT_ID>

1. Разрешите доступ под нужным логином Директа.
2. Токен появится в адресной строке или на странице подтверждения.

Автоматический (production) — как получить oauth token yandex для сервера:

1. Пользователь переходит по ссылке с response_type=code.
2. Ваш backend получает code на Redirect URI.
3. POST на https://oauth.yandex.ru/token с grant_type=authorization_code, code, client_id, client_secret.
4. В ответе — access_token и refresh_token для продления без повторного логина (grant_type=refresh_token).

Яндекс рекомендует завести отдельного представителя в Директе и выдавать токен именно ему — так проще отозвать доступ, не трогая личный аккаунт владельца бизнеса.

Заявка на API. Пока заявка не одобрена, токен сам по себе не откроет API. В настройках API на вкладке «Мои заявки» опишите сценарий: какие методы, как часто, для скольких аккаунтов. В форме просят конкретику — расплывчатое «автоматизация управления кампаниями» часто отклоняют. Условие: в аккаунте уже есть минимум одна кампания в Директ Про. Срок рассмотрения — до 7 рабочих дней (не рассчитывайте на «пару часов»).

Типичные ошибки при получении токена

Частая путаница: «api ключ яндекс директ» в поиске — это два разных объекта: Client secret (секрет приложения) и Bearer access token (пропуск пользователя). В заголовках запросов к Директу используется только Bearer.

API-ключ и настройка доступа к Яндекс.Директу

После одобрения заявки настройте яндекс директ настройки api в кабинете: вкладка «Параметры» — ограничение по IP (whitelist). Для агентства это критично: скрипт с VPS должен ходить только с разрешённых адресов.

Условия доступа (кратко):

• Пользователь принял соглашение об использовании API.
• Приложение авторизовано через OAuth.
• Заявка одобрена модерацией.
• Для клиента агентства: права API = права в веб-интерфейсе (read-only → только чтение).

Агентский кабинет: заголовок Client-Login: логин_клиента обязателен при запросах к данным клиента. Заголовок Use-Operator-Units: true — списание баллов с агентского пула Units; без него баллы списываются с клиента.

Роли, права и лимиты запросов

API Директа использует систему баллов Units — не «запросов в секунду», а параллелизма и суточного бюджета операций.

Подтверждённые правила (официальная документация):

• Не более 5 одновременных запросов от одного рекламодателя (не 5 RPS).
• Суточный лимит индивидуальный — зависит от активности кампаний (показы, клики, расход); начисление по скользящему 24-часовому окну.
• В заголовке ответа: Units: списано/остаток/суточный_лимит (пример: 10/20828/64000).
• Ошибка вызова метода — 20 баллов; ошибка операции с объектом — 20 баллов на операцию.
• Нехватка баллов — код 152.

Тарифы методов (фрагмент): Campaigns.get — от 10 + 1 за объект; Ads.add — 20 + 20 за объявление; Keywords.get — 15 + 3 за каждые 2000 фраз в статистике. Перед массовым Ads.add на 1000 объявлений прикиньте: порядка 40 000+ баллов только на создание — плюс риск по 20 баллов за каждую ошибку валидации. Отладку гоняйте на минимальных выборках и в песочнице.

Проверка доступа: первый тестовый запрос

После токена и одобрения заявки проверьте доступ вызовом Campaigns.get с минимальным FieldNames:

POST https://api.direct.yandex.com/json/v501/campaigns
Authorization: Bearer <ваш_токен>
Content-Type: application/json; charset=utf-8

{
  "method": "get",
  "params": {
    "SelectionCriteria": {},
    "FieldNames": ["Id", "Name", "Status"]
  }
}

Для агентства добавьте Client-Login. Успешный ответ с массивом Campaigns — доступ работает. Пустой массив при успехе — кампаний нет или они в формате, который API не отдаёт (например, чистый Мастер кампаний).

Песочница: URL https://api-sandbox.direct.yandex.com/... — изолированная среда без влияния на прод. Активируется в интерфейсе Директа; удобно для отладки без риска для бюджета.

Документация API Яндекс.Директа: с чего начать

Официальная яндекс директ api документация — на портале yandex.ru/dev/direct. Стартовые разделы: «Регистрация», «Токен», «Доступ», «Units», «Песочница», changelog.

Для маркетолога без глубокого кода полезен обзор Яндекс Реклама Edu — что такое API и зачем бизнесу; для интеграции — разделы с примерами на Python (python3-requests-token, python3-requests-points).

Основные сервисы и методы (кампании, объявления, отчёты)

Структура API: сервис → метод. Типовой набор для автоматизация яндекс директ:

Reports API: формат TSV; ставки и расходы в микрорублях (1 ₽ = 1 000 000). Для тяжёлых отчётов — processingMode: offline.

Версии API и миграция на актуальные методы

Актуальный путь — v501. Следите за changelog — ключевые изменения 2024–2026:

• Июль 2026: массовая миграция ТГО → комбинаторные в ЕПК; ads.add с TextAd → RESPONSIVE_AD.
• Сентябрь 2025: стратегия MAX_PROFIT для ТГО и ЕПК.
• Июнь 2025: scope passport:business; стратегии с несколькими целями.
• Ноябрь 2025: BidModifiers.toggle устарел.
• campaigns.update: параметр DailyBudget перестаёт работать (проверяйте актуальную дату в доке).

Перед автозаливом обновите скрипты под комбинаторные — иначе массовое создание объявлений упрётся в устаревшие типы.

Карта «API vs интерфейс» 2026 — главный вопрос после миграции:

Автоматизация кампаний через API Яндекс.Директа

Когда ручная работа и Коммандер перестают масштабироваться, автоматизация яндекс директ через API даёт предсказуемый цикл: данные → решение → действие → лог.

Сценарии: массовые правки, выгрузка статистики, управление ставками

Три типовых сценария агентской практики:

1. Ежедневный Reports → алерт. Ночной cron запрашивает отчёт по расходу и конверсиям; при отклонении от плана — сообщение в Telegram или Slack. Стыкуется с отчётами Директа и целями в Метрике.

1. Массовая чистка площадок РСЯ. Выгрузка статистики по площадкам → фильтр по CPA/отказам → BidModifiers или минус-площадки пакетом. Альтернатива без кода — периодическая работа в Коммандере; API выигрывает при еженедельном цикле на 20+ аккаунтах.

1. Синхронизация остатков SKU → pause ads. Остаток ноль на складе → ads.suspend для связанных объявлений. Критично для товарных кампаний и фидов — но не для кампаний чистого Мастера.

Дополнительно: массовое обновление UTM, перезапуск объявлений после модерации, выгрузка в BI для оценки эффективности.

Пример на Python: структура запроса и обработка ответа

Минимальный каркас (библиотека requests; на проде — retry, лог Units, обработка 152):

import requests

TOKEN = "..."  # из secrets manager
CLIENT_LOGIN = "client-login"  # для агентства

url = "https://api.direct.yandex.com/json/v501/campaigns"
headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Client-Login": CLIENT_LOGIN,
    "Accept-Language": "ru",
    "Content-Type": "application/json; charset=utf-8",
}
body = {
    "method": "get",
    "params": {
        "SelectionCriteria": {"States": ["ON"]},
        "FieldNames": ["Id", "Name", "Status"],
    },
}

resp = requests.post(url, json=body, headers=headers)
units = resp.headers.get("Units", "")
data = resp.json()

if "error" in data:
    print(f"API error: {data['error']} | Units: {units}")
else:
    for camp in data["result"].get("Campaigns", []):
        print(camp["Id"], camp["Name"])

Готовые community-клиенты (tapi-yandex-direct и аналоги) ускоряют старт, но официальная позиция Яндекса — JSON + ваш HTTP-клиент. В 2025–2026 появились MCP/CLI-обёртки (mcp-server-yandex-direct, yadirect-agent) с режимом plan → confirm → execute — удобно для ИИ в Директе, если политика безопасности это допускает.

Когда API, а когда Директ Коммандер или eLama

Честный вывод: API не окупается, если реклама — один кабинет и пять кампаний с редкими правками. Окупается при регулярных операциях, нескольких клиентах или жёсткой связке с учётной системой.

Интеграция API с системами учёта клиентов, аналитикой и маркетплейсами

Интеграция яндекс директ с внешним контуром — типичный запрос зрелого performance-маркетинга.

Связка с Яндекс.Метрикой и целями

API Директа не подменяет Метрику: конверсии и атрибуция живут в связке Метрики и Директа. Схема:

• В Директе — UTM и счётчик Метрики на объявлениях (счётчик метрики).
• Через Reports API — расход, клики, иногда офлайн-конверсии.
• В системах учёта клиентов — лиды с метками; склейка в учёт клиентов, Директ и Метрика.

Для API-отчётов закладывайте задержку: асинхронные Reports (202) и микрорубли в выгрузке.

Антифрод и внешние сервисы

Отдельный низкочастотный запрос — интеграция антифрод с яндекс директ: сторонние системы анализируют клики и площадки, решения о корректировках часто возвращаются в Директ через API (минус-площадки, снижение ставок). Яндекс директ интеграция с маркетплейсами обычно идёт через фиды и товарные кампании в UI; API помогает синхронизировать статусы объявлений с остатками на складе маркетплейса, если есть собственная middleware.

Безопасность: хранение токенов, отзыв и ротация

Api токен яндекс директ — полноценный ключ к бюджету клиента. Минимальный чек-лист агентства:

1. Отдельный представитель в Директе под интеграцию; не личный логин директора.
2. Secrets manager или env на сервере — не git, не скриншоты, не общие таблицы.
3. Refresh token — автоматическое продление; мониторинг отзыва (пользователь мог отключить приложение в Яндекс ID).
4. IP whitelist в настройках API.
5. Песочница перед выкаткой на прод.
6. Логирование без записи полного токена в plain text.
7. Ротация Client secret при утечке; перевыпуск токенов при смене сотрудника.

При увольнении интегратора — отзыв токена в Яндекс ID и смена Client secret, если секрет мог скомпрометироваться. Запросы «отозваны токены яндекс» в поддержку — крайняя мера; проще отключить приложение в настройках доступа.

Обучение и курсы по API Яндекс.Директа

Запрос api яндекс директ курсы встречается редко (десятки показов в месяц), но логичен для команды, где маркетолог и разработчик говорят на разных языках. План обучения:

• Маркетологу — обучение рекламе в Директе + обзор Edu по API.
• Разработчику — официальные примеры Python, песочница, changelog.
• Совместно — один пилотный клиент, один сценарий (например, утренний отчёт), документирование ошибок Units.

Не обязательно «курс за 40 часов» — достаточно внутреннего playbook: токен, Client-Login, первый get, один Reports, деплой на cron.

Если команда поднимает API с нуля и хочет увереннее читать changelog, Units и отчёты Reports — имеет смысл пройти Больше о маркетинге в моем Telegram. Пригодится маркетологу и разработчику на одном пилотном клиенте: токен, песочница, первый Campaigns.get и один сценарий на cron.