Как подключить API Яндекс Директа к Claude и Codex: пошаговая инструкция

Яндекс Директ в Claude и Codex: как подключить API и управлять рекламой запросами

Отчёт о расходах за две недели, список площадок без конверсий, правка ставок: в интерфейсе Директа на такое уходят часы. Если подключить Директ к Claude или Codex через API, то же самое делается одной просьбой обычными словами. Нейросеть сама запрашивает данные, собирает отчёт и показывает, что предлагает изменить.

Так собирают отчёт руками: «Мастер отчётов» в Директе, длинный список группировок и метрик, фильтры, цели, атрибуция. Скриншот кабинета, логин замазан.

Ниже весь путь от рекламного кабинета до первого отчёта: что создать, что вписать в заявку, где взять токен и как не дать нейросети испортить рабочие кампании. Шаги сверены со справкой Яндекса и с кабинетом Директа в ноябре 2026 года, скриншоты — из настоящего кабинета, личные данные на них замазаны. Интерфейс Яндекса меняется, поэтому названия кнопок со временем могут отличаться.

5 шаговот приложения до первого отчёта

~1 часваша работа в первый день

до 7 днейЯндекс проверяет заявку

Что понадобится

Что	Где взять	Зачем
Приложение в Яндекс ID	oauth.yandex.ru	Выдаёт ClientID и Client secret: по ним Яндекс узнаёт ваше подключение
Заявка на доступ к API	Директ Про, меню «Инструменты» → «API», вкладка «Мои заявки»	Пока заявка не одобрена, API не работает с рабочим кабинетом
OAuth-токен	ссылка oauth.yandex.ru/authorize	Ключ, по которому Директ понимает, от чьего имени пришёл запрос
Навык для нейросети	пишете сами, шаблон ниже	Объясняет нейросети, что можно делать сразу, а что только после вашего «да»

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

Этап 1Сегодня, около часа

приложение, заявка, файл для ключей.

Этап 2Пока Яндекс рассматривает заявку, до 7 дней

навык для нейросети и чек-лист проверок.

Этап 3После одобрения

токен, первый запрос на чтение, сверка отчёта с интерфейсом.

Шаг 1. Создайте приложение в Яндекс ID

Шаг 1 из 5

Войдите в Яндекс под логином, на котором работает рекламный кабинет.
Откройте oauth.yandex.ru и нажмите «Создать».
В окне «Какое приложение хотите создать?» выберите «Для доступа к API или отладки» и нажмите «Перейти к созданию».

Первый экран: тип приложения «Для доступа к API или отладки». Названия других приложений аккаунта замазаны.

В поле «Название вашего сервиса» напишите понятное вам название, например «Директ: отчёты». «Почту для связи» Яндекс подставит сам: оставьте ту, которую вы читаете.
В поле «Доступ к данным» начните вводить «Директ» и выберите из списка «Использование API Яндекс.Директа» (direct:api). Справка Директа советует добавить и «Работа с организациями Яндекс ID» (passport:business).
Поле «Redirect URI» для этого типа приложения Яндекс заполняет сам адресом https://oauth.yandex.ru/verification_code. Менять его не нужно, да и нельзя.
Нажмите «Создать приложение». На странице приложения появятся ClientID и Client secret.

Форма создания приложения: название, почта, доступ direct:api, Redirect URI уже заполнен. Почта замазана.

Скопируйте ClientID и Client secret в текстовый файл на своём компьютере. ClientID понадобится в заявке и в ссылке за токеном.

Безопасность

Client secret никому не отправляйте: ни в чат с нейросетью, ни подрядчику в мессенджере.

Вверху страницы Яндекс предлагает пройти верификацию через Госуслуги. Приложение для доступа к API создаётся и без неё.

Шаг 2. Подайте заявку на доступ к API

Шаг 2 из 5

В Директ Про откройте меню «Инструменты» и выберите «API».

Где в Директе вход в API: меню «Инструменты» → «API». Логин замазан.

При первом посещении страницы Директ попросит нажать «Получить доступ к API» и принять пользовательское соглашение.
На странице «Настройки API» перейдите на вкладку «Мои заявки» и нажмите «Новая заявка».

Страница «Настройки API»: вкладки «Параметры», «Мои приложения», «Мои заявки», «Финансовые операции» и кнопка «Новая заявка».

Заполните форму «Заявка на получение полного доступа к Яндекс.Директ» и нажмите «Отправить».

Верх формы заявки: приложение, контакты, компания, кто вы, технические данные, логины, назначение. ClientID замазан.

Как заполнить заявку

Заявку читают сотрудники Яндекса. Им нужно понять, кто вы и что будет делать приложение. Ответ «для работы» ничего не объясняет, такую заявку проще отклонить. Обязательные поля отмечены звёздочкой, и их больше, чем кажется.

Поле	Так не надо	Так надо
application_id	первое попавшееся из списка	ClientID приложения из шага 1
Контакты для службы поддержки	ящик, который никто не открывает	почта, которую вы читаете: туда придут вопросы и ответ
Кто вы	«Другое»	«Прямой заказчик…» для своего кабинета или «Агентство и автоматизируете работу своих сотрудников с кампаниями клиентов»
Язык программирования и протокол	«не знаю»	Python, протокол JSON
Логины в Директе	пусто	логин вашего кабинета, агентству — логины клиентов
Для чего предназначено приложение	ничего не отмечено	«Автоматизировать регулярную работу по управлению кампаниями в Директе»
Основные функции	отмечено всё подряд	то, что будете делать: «Получение статистики и отчетов», «Управление кампаниями и объявлениями», «Управление ставками (биддинг)»
Спецификации, скриншоты интерфейса	пусто, а поле обязательное	простая схема «вы → нейросеть → API Директа → отчёт» или обезличенный пример отчёта

Низ формы: функции приложения, два обязательных описания, обязательный файл со спецификацией или скриншотом, пользовательское соглашение.

Два обязательных описания можно взять за основу и поправить под себя:

Какие новые возможности даёт приложение

Выгружает статистику и отчёты по моим кампаниям за любой период, находит площадки и фразы без конверсий, готовит предложения по ставкам и объявлениям. Изменения в кампаниях применяются только после ручного подтверждения.

Схема взаимодействия с Директом

Скрипт на компьютере владельца аккаунта отправляет JSON-запросы к API Директа версии 5 с OAuth-токеном этого логина. Полученные данные сохраняются локально для отчётов. Запросы на изменение кампаний выполняются только после ручного подтверждения.

Сроки и статус

Яндекс рассматривает заявку до 7 дней. Статус видно на вкладке «Мои заявки»: «одобрена» или «отклонена». Если заявку отклонили, причина будет там же: исправьте заявку и отправьте снова. Пока исправленная заявка на рассмотрении, действуют условия прежней.

Совет

Не ждите одобрения без дела: в это время можно подготовить навык и чек-лист из шага 4.

Шаг 3. Получите токен

Шаг 3 из 5

Когда заявку одобрили:

Войдите в Яндекс под логином рекламного кабинета.
Откройте ссылку, подставив свой ClientID: https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID
Нажмите «Разрешить».
Яндекс откроет страницу, в адресе которой после знака # стоят два параметра: access_token (это и есть токен) и expires_in (срок жизни токена в секундах). Скопируйте токен.

адресная строка после «Разрешить»

https://oauth.yandex.ru/verification_code#access_token=y0_AgAAAAB••••••••••••&token_type=bearer&expires_in=•••••

токен: всё после «access_token=» до знака &срок жизни токена в секундах

Схема: где в адресе токен. Значения условные.

Яндекс токены не хранит. Потеряли — получите новый по той же ссылке.

Где хранить токен

Безопасность

Токен открывает доступ к рекламному кабинету, обращайтесь с ним как с паролем. Не вставляйте токен в сообщение чата: он останется в истории переписки.

Положите токен в переменную окружения или в файл вне папки проекта, а нейросети скажите брать его оттуда.

На Mac переменную можно добавить так, выполнив в терминале:

echo 'export YANDEX_DIRECT_TOKEN="ваш_токен"' >> ~/.zshrc
source ~/.zshrc

Когда токен перестаёт работать

Яндекс отзывает токен, если:

истёк срок его жизни;
вы отозвали доступ приложения в настройках Яндекс ID;
владелец приложения изменил запрошенные права или удалил приложение;
вы сменили пароль, включили или выключили двухфакторную защиту, восстановили доступ к аккаунту или вышли из аккаунта на всех устройствах.

Тогда Директ ответит ошибкой авторизации. Получите новый токен по той же ссылке и обновите переменную.

Шаг 4. Научите нейросеть работать с Директом

Шаг 4 из 5

Claude Code (от Anthropic) и Codex (от OpenAI) — ассистенты, которые работают на вашем компьютере и умеют сами отправлять запросы, если вы это разрешили. Чтобы они делали это одинаково и безопасно, правила записывают в навык.

1Вы

просьба обычными словами.

2Нейросеть

навык и чек-лист превращают просьбу в запрос.

3API Директа

проверяет токен, отдаёт данные.

4Ответ

отчёт или список изменений на ваше «да».

Схема: что происходит после вашей просьбы.

Навык с правилами

Навык — файл с инструкцией, которую нейросеть применяет, когда задача касается Директа. В Claude Code это файл SKILL.md в папке ~/.claude/skills/<название>/ (для всех проектов) или .claude/skills/<название>/ внутри проекта. Навык вызывается командой /название, а ещё Claude подключает его сам, если задача подходит под описание из поля description. В Codex те же правила можно положить в файл AGENTS.md в папке проекта.

Шаблон, который можно скопировать и поправить под себя:

---
name: yandex-direct
description: Работа с Яндекс Директом через API v5: отчёты, площадки, ставки, объявления. Используй, когда просят отчёт по Директу или изменение в кампаниях.
---

# Яндекс Директ через API

1. Токен бери из переменной окружения YANDEX_DIRECT_TOKEN. Не выводи его в ответах и не записывай в файлы.
2. По умолчанию только читай данные: методы get и отчёты. Перед любым изменением ставок, объявлений или кампаний покажи таблицу «было → станет» и жди моего «да».
3. После каждого запроса показывай заголовок Units: потрачено / осталось / суточный лимит.
4. Сохраняй выгрузки в папку data/ с датой в имени файла и не запрашивай повторно то, что уже выгружено.
5. В запросах к отчётам передавай заголовок returnMoneyInMicros: false, чтобы суммы приходили в рублях.
6. Сверяй итоги: расход и клики за период должны совпадать с интерфейсом Директа. Если не совпадают, скажи об этом.
7. Для кабинета клиента агентства добавляй заголовок Client-Login с логином клиента.
8. Проверяя кабинет, иди по чек-листу и в ответе называй номер проверки.

Чек-лист проверок

Сама по себе нейросеть выгружает цифры. Чтобы она находила проблемы, ей нужен ваш список проверок: можно ли верить целям в Метрике, на что обучаются стратегии, куда уходит бюджет на поиске и в РСЯ, какие площадки вы исключаете, какой расход на конверсию считаете нормой. Загрузите чек-лист аудита Директа в чат и попросите сделать из него навык или дополнить шаблон выше. Это удобно сделать, пока заявка на рассмотрении.

Шаг 5. Проверьте подключение запросом на чтение

Шаг 5 из 5

Раньше у API Директа была песочница — копия API с тестовыми кампаниями. В актуальной справке о ней не написано, а на странице «Настройки API» её вкладки нет (посмотрите на скриншот в шаге 2). Поэтому первое подключение проверяйте запросом, который ничего не меняет: списком кампаний или отчётом за прошлую неделю.

Попросите нейросеть: «Запроси список моих кампаний в Директе и покажи заголовок Units. Ничего не меняй». Она отправит примерно такой запрос:

curl -s -D - -X POST https://api.direct.yandex.com/json/v5/campaigns \
  -H "Authorization: Bearer $YANDEX_DIRECT_TOKEN" \
  -H "Accept-Language: ru" \
  -H "Content-Type: application/json" \
  -d '{"method":"get","params":{"SelectionCriteria":{},"FieldNames":["Id","Name","State"]}}'

Если пришёл список ваших кампаний, а в заголовке Units списались баллы, подключение работает. Следующий шаг — отчёт за прошлую неделю и сверка с «Мастером отчётов» в интерфейсе.

Баллы: сколько запросов можно сделать

Каждый запрос к API стоит баллов. Суточный лимит у каждого рекламодателя свой. Он делится на 24 часа: каждый час начисляется 1/24 лимита, и к нему добавляются баллы, не потраченные за предыдущие 23 часа. Баллы кончились — запросы не выполняются до следующего начисления. Одновременно можно отправлять не больше пяти запросов от одного рекламодателя.

Ответ на каждый запрос приходит с заголовком Units из трёх чисел: сколько баллов потрачено на запрос, сколько осталось и каков суточный лимит. Например, Units: 10/20828/64000.

Метод	Что делает	За вызов	За объект
Campaigns.get	список кампаний	10	1
AdGroups.get	группы объявлений	15	1
Ads.get	объявления	15	1
Keywords.get	ключевые фразы	15	1 за каждые 2000 фраз, 3 со статистикой
Bids.get	ставки	15	3 за каждые 2000 фраз
KeywordBids.set	изменить ставки	25	0
Dictionaries.get	справочники	1	0

Совет

Вызов с ошибкой стоит 20 баллов. Поэтому правило 4 из навыка экономит лимит: выгрузили один раз и дальше работаете с файлом.

Агентствам: кабинеты клиентов

Агентство получает токен на свой логин, а в каждом запросе к кабинету клиента указывает заголовок Client-Login с логином клиента. Заголовок Use-Operator-Units: true списывает баллы агентства, а не клиента.

Важно

Прежде чем передавать данные кампаний клиента в нейросеть, проверьте договор с клиентом: разрешено ли это.

Что поручать нейросети

Отчёт за период

Попросите«Собери расход, клики и конверсии по кампаниям за 14 дней и сравни с предыдущими 14»

Под капотом: служба Reports, ответ таблицей в формате TSV

Площадки на исключение

Попросите«Покажи площадки РСЯ с кликами и без конверсий за 30 дней»

Под капотом: отчёт Reports с полем Placement

Ставки

Попросите«Предложи новые ставки по фразам с дорогой конверсией, применишь после моего “да”»

Под капотом: сервисы Bids и KeywordBids

Объявления

Попросите«Подготовь три варианта текста для этой группы и покажи до создания»

Под капотом: сервис Ads

Проверка кабинета

Попросите«Пройди по моему чек-листу и отметь, что не так»

Под капотом: чтение кампаний, групп, фраз и минус-слов

Правила с первого дня

По умолчанию нейросеть только читает. Изменения — списком и после вашего подтверждения.
Первые запросы — только на чтение: списки и отчёты.
Токен не попадает ни в чат, ни в файлы, которые уходят в репозиторий или подрядчику.
На скриншотах для коллег замазаны токены, логины и названия кампаний.
Первые отчёты сверяются с интерфейсом. Нейросеть может ошибиться с периодом, с НДС (параметр IncludeVAT в отчёте) или с единицами денег.

Проверьте себя

Готовность подключения0 %

Приложение в Яндекс ID создано, ClientID и Client secret сохранены в файлВ приложении есть доступ «Использование API Яндекс.Директа» (direct:api)Заявка одобрена, статус виден на вкладке «Мои заявки»Токен получен и лежит в переменной окружения, а не в чатеЗапрос на чтение вернул список кампаний и заголовок UnitsНавык запрещает изменения без вашего подтвержденияПервый отчёт совпал с интерфейсом по расходу и кликам

Сколько времени это сэкономит

Подставьте свои цифры. Числа в полях для примера.

Калькулятор · числа в полях для примера

Отчётов в месяцМинут на отчёт вручнуюМинут с нейросетью, вместе с проверкойСтоимость часа специалиста, ₽

Часов в месяц0

₽ в месяц0

₽ в год0

Часы в месяц = отчётов × (минут вручную − минут с нейросетью) / 60. Калькулятор считает только время на рутину, пользу от более точной настройки рекламы он не учитывает.