API Яндекс Директа: автоматизация для агентства

Как получить доступ: OAuth, токен и кабинет разработчика

Подключение API в 2026 году — трёхшаговый процесс. Порядок зафиксирован в официальной документации:

1. Создать приложение в Яндекс ID с правом direct:api.
2. Подать заявку на доступ в разделе «Настройки API» Директа, указав ClientID приложения.
3. Получить OAuth-токен на каждого пользователя, от имени которого будут идти запросы.

— регистрация и заявка

Важно: страница «Настройки API» доступна только после создания хотя бы одной кампании в веб-интерфейсе Директа; при первом входе нужно принять пользовательское соглашение.

Рассмотрение заявки — до 7 рабочих дней (пн–пт, 10:00–19:00 МСК). На практике при конкретном описании сценария одобрение часто приходит быстрее. — troubleshooting; экспертный гайд Pawetta, август 2026

Регистрация приложения и выдача OAuth-токена

Приложение регистрируется в кабинете разработчика Яндекс API. Для Директа критичен scope direct:api. Если агентство работает с паспортными организациями клиентов, с 2 июня 2025 дополнительно нужен доступ passport:business в настройках OAuth-приложения. — changelog API

После одобрения заявки каждый специалист, который будет вызывать API (руководитель направления, ведущий директолог, разработчик интеграции), получает свой OAuth-токен — не «общий пароль на всех».

Типовой поток авторизации описан в документации Yandex OAuth: redirect на oauth.yandex.ru, обмен кода на токен. Ключевые поисковые запросы вроде «yandex oauth», «oauth token yandex», «как получить oauth token yandex» закрываются именно этой схемой — без передачи логина и пароля от кабинета подрядчику.

API-токен Директа и права доступа для сотрудников агентства

Внутри агентской модели Яндекс Директа управляющий аккаунт (логически — центр управления клиентами) запрашивает данные клиента через заголовок Client-Login — логин рекламодателя. Токен при этом принадлежит представителю агентства, а не клиенту.

Сервис AgencyClients (/json/v501/agencyclients) — методы add, update, get — вызывается без Client-Login в заголовке. — AgencyClients

Изменение с 16 июня 2025: метод AgencyClients.add больше не поддерживается. Регистрация новых клиентов — через addPassportOrganization (доступ по заявке для агентств с большим числом клиентов). С 19 июня 2025 добавлен addPassportOrganizationMember — добавление сотрудника в паспортную организацию клиента. — новость ppc.world

С 20 июня 2025 агентства могут входить в Директ Коммандер через логин паспортной организации — не только через агентский или личный кабинет.

Безопасное хранение ключей при работе с несколькими клиентами

Регламент для агентства:

• OAuth-токены и Client Secret — только в защищённом хранилище (переменные окружения на сервере, секрет-менеджер), не в таблицах, чатах и промптах к ИИ.
• Разделение ролей: read-only токен для отчётности, отдельный контур для записи с human-in-the-loop (dry-run → approve → apply). Паттерн описан в материале Habr про AI-агентов: из чата доступен только read-only MCP с вызовами get; запись — отдельным apply-процессом. — Habr 1079434
• Не передавать пароль от кабинета — только OAuth-представитель; тема раскрыта в нашей статье про мультиаккаунт.
• Песочница для тестов: https://api-sandbox.direct.yandex.com/json/v5/{service} — изолированная среда без веб-интерфейса, данные хранятся около месяца; можно выбрать роль «Агентство» с 3 тестовыми клиентами по 3 кампании. — песочница

Сценарии автоматизации для агентства

Центральный блок для запросов «автоматизация яндекс директ» и «яндекс директ для рекламного агентства». Здесь API перестаёт быть «документацией для программиста» и становится операционным инструментом.

Массовые правки ставок, объявлений и минус-фраз

Типовой кейс: у 15 клиентов в e-commerce нужно поднять ставки на брендовые группы на 10% и добавить одинаковый список минус-фраз после аудита поисковых запросов.

Через API:

1. Reports — выгрузка поисковых запросов за период.
2. Фильтрация в вашем скрипте или таблице.
3. Keywords.update / Bids.set / обновление минус-фраз на уровне группы или кампании.

Pawetta (август 2026) отмечает: «API Директа перестал быть территорией разработчиков: скрипт под свой кабинет теперь собирается за вечер по описанию задачи словами». — блог Pawetta Это не отменяет регламент проверки результата — особенно после массовых операций.

Синхронизация кампаний между аккаунтами клиентов

Агентство часто тиражирует удачную структуру: одна master-кампания → клонирование на региональные аккаунты. API позволяет выгрузить структуру через Campaigns.get, AdGroups.get, Ads.get, трансформировать и залить через add-методы — с учётом лимитов и модерации.

Для онбординга новых клиентов после июня 2025 цепочка изменилась: вместо AgencyClients.add — работа с паспортной организацией. Это нужно заложить в шаблон «подключения клиента», иначе старый скрипт onboarding сломается молча или с неочевидной ошибкой.

Интеграция с системой учёта клиентов, таблицами и no-code

Три уровня зрелости:

Связка с сегментами аудиторий Метрики в Директе — смежный кластер: API Аудиторий + AudienceTargets для загрузки сегментов из системы учёта клиентов.

Автор кейса на vc.ru пишет: «Раньше платил за сторонний [биддер] около 20 тысяч в месяц и не мог влезть в его логику — чёрный ящик. Теперь свой, полностью под моим контролем». In-house автоматизация окупается, когда сценарии стабильны и повторяются каждую неделю.

Когда достаточно правил в кабинете, а когда нужен API

Достаточно кабинета и Коммандера, если:

• клиентов мало (1–3), изменения эпизодические;
• хватает автостратегий и встроенных правил;
• отчётность — стандартные пресеты без сводных дашбордов.

Нужен API, если:

• 10+ клиентов и единый формат отчёта «на завтра к 9:00»;
• массовые однотипные правки (ставки, минус-фразы, креативы);
• синхронизация с остатками, ценами, фидом;
• свой биддер или интеграция с внутренней аналитикой;
• аудит: кто и когда менял ставки — через Changes и ваши логи.

Запрос «ai директолог» в 2026 году часто означает именно связку ИИ для анализа + API для исполнения после проверки человеком, а не полностью автономное управление без контроля.

Типичные ошибки, лимиты запросов и отладка

Ошибки авторизации и просроченные токены

Частые причины:

• заявка на API ещё не одобрена (ждать до 7 рабочих дней);
• токен выдан без scope direct:api или без passport:business для паспортных организаций;
• запрос к данным клиента без Client-Login или с неверным логином;
• токен отозван или истёк — нужен refresh по правилам Yandex OAuth.

Симптом «все три запроса вернули 200 OK, но выводы неверны» — не ошибка авторизации, а ошибка интерпретации данных (типичный кейс с Goals/Conversions в Reports).

Лимиты API и очереди запросов при массовых операциях

Баллы (Units) — индивидуальный суточный лимит, зависит от активности кампаний (показы, клики, расход); пересчёт раз в сутки; начисление по скользящему окну — 1/24 лимита каждый час плюс неизрасходованный остаток за 23 часа. — units

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

Стоимость ошибок:

• ошибка вызова метода — 20 баллов;
• ошибка операции с объектом — 20 баллов за операцию.

Технические лимиты:

• не более 5 параллельных запросов от одного рекламодателя (клиента);
• не более 5 офлайн-отчётов в очереди на пользователя;
• оптимизация: кэш + Changes вместо полных get. — optimize

При массовых операциях на 30 клиентах узкое место — не «медленный интернет», а бюджет баллов × параллелизм × очередь Reports. Планируйте ночные offline-отчёты и дневные лёгкие Changes.check.

FAQ по API Яндекс Директа

Ответы для агентств и интеграторов