API Яндекс Директа: как получить токен и что доступно

Есть ли API у Яндекс Директа и кому он нужен

• Есть, официальный, с документацией на yandex.ru/dev/direct. Доступ выдаётся по заявке.
• Кому доступен: пользователю Директа — рекламодателю, представителю, агентству или клиенту агентства с нужными правами. Пользователь должен принять пользовательское соглашение API.
• Зачем рекламодателю: выгружать статистику в свои отчёты и CRM, массово менять ставки и объявления по правилам, синхронизировать объявления с каталогом товаров.
• Зачем разработчику и агентству: собственные инструменты — оптимизаторы ставок, генераторы кампаний, сквозная аналитика, интеграции с ИИ-агентами.
• Кому не нужен: если у вас один кабинет и задача — раз в неделю поправить ставки и посмотреть отчёт, API избыточен. Хватит интерфейса или Коммандера.

Что доступно через API Директа

Полный список сервисов и методов — в документации. Не всё, что есть в интерфейсе, есть в API, поэтому перед разработкой проверьте, есть ли в API то, ради чего вы его подключаете.

Версии: v5 и v501

Основная версия API — пятая (v5), запросы в формате JSON или SOAP. Единая перфоманс-кампания поддерживается в версии v501: по документации ЕПК, её группы и объявления создаются через сервисы по адресу https://api.direct.yandex.com/v501/. Если ваша интеграция написана под v5 и работает со старыми типами кампаний, для ЕПК её придётся дорабатывать. Отличия на уровне объявлений есть: например, в ЕПК-группах текстовые объявления не поддерживают визитку.

Как получить токен API Яндекс Директа

1. 1

   Зарегистрируйте приложение на Яндекс OAuth

   Откройте oauth.yandex.ru, перейдите к созданию приложения и выберите вариант «Для доступа к API или отладки». В списке доступов добавьте «Использование API Яндекс Директа» (direct:api). После сохранения Яндекс выдаст ClientID и Client secret — они нужны для получения токена.

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

2. 2

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

   Войдите в Директ, откройте страницу настроек API и создайте заявку: укажите ClientID приложения и опишите, что оно делает. По документации срок рассмотрения заявки — до 7 дней. Одобренная заявка обязательна для запросов к реальным данным.

3. 3

   Пока ждёте — включите песочницу

   Песочница — тестовая среда, изолированная от реальных кампаний и денег. Включается на странице настроек API, вкладка «Песочница»: выбираете роль (клиент или агентство), валюту и создание тестовых кампаний. Запросы в неё идут на отдельный адрес — api-sandbox.direct.yandex.com.

4. 4

   Получите OAuth-токен

   Токен выдаётся пользователю Директа для вашего приложения. Для себя и небольшой команды достаточно отладочного токена, полученного вручную: пользователь открывает страницу авторизации Яндекса с ClientID приложения и нажимает «Разрешить». Для сервиса с многими пользователями токен получают автоматически — приложение перенаправляет пользователя на Яндекс и принимает токен или код подтверждения. Оба способа описаны в документации о токенах.

5. 5

   Отправьте первый запрос

   Токен передаётся в HTTP-заголовке Authorization при каждом запросе. Начните с безопасного чтения — получите список кампаний через сервис Campaigns. В ответе придёт заголовок Units с расходом баллов: так вы сразу увидите свой лимит.

6. 6

   Ограничьте доступ по IP

   На странице настроек API можно указать разрешённые IP-адреса — запросы с других адресов выполняться не будут. Если интеграция работает с одного сервера, включите это сразу.

Токен — это доступ к кабинету с правами пользователя, который его выдал: с ним можно менять ставки, запускать кампании и тратить бюджет. Не храните его в коде, в общих таблицах и в переписке и не вставляйте в чат с нейросетью. Когда токен становится недействительным и как его отозвать — в разделе об отзыве токенов документации Яндекс ID.

Лимиты API: баллы и ограничения

Директ ограничивает нагрузку не числом запросов в минуту, а баллами. Каждый вызов метода и каждый обработанный объект стоят баллы; когда они заканчиваются, запросы перестают выполняться.

• Лимит индивидуальный. Каждому рекламодателю или агентству выдаётся суточный лимит баллов; он зависит от активности кампаний — количества показов и кликов. У нового кабинета без трафика лимит скромный.
• Скользящее окно. Суточный лимит разделён на 24 часовых интервала: потраченные баллы возвращаются не в полночь, а по мере того как проходят сутки с момента расхода.
• Остаток виден в каждом ответе. Заголовок Units содержит три числа: израсходовано запросом / доступный остаток / суточный лимит — например, Units: 10/20828/64000.
• Запись дороже чтения. Примеры из документации: Campaigns.add — 10 баллов за вызов и 5 за каждый объект; Ads.update — 20 за вызов и 20 за объект; Keywords.get — 15 за вызов и 3 за каждые 2000 фраз.
• Ошибки тоже стоят баллов — запрос с ошибкой метода списывает 20. Скрипт, который в цикле повторяет неверный запрос, сожжёт дневной лимит за минуты.
• Агентствам: по умолчанию баллы списываются с клиента, в чьём кабинете выполняется запрос; заголовок Use-Operator-Units: true переключает списание на само агентство.

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

Директ Коммандер: когда API не нужен

«Яндекс Директ Коммандер» ищут не реже, чем «API Яндекс Директа», и не случайно: большинству API нужен не для разработки, а чтобы быстро поправить сотни объявлений. Для этого у Яндекса есть Директ Коммандер — программа для Windows и macOS для управления кампаниями: массовое редактирование, создание кампаний загрузкой объявлений и фраз из файлов, встроенный подбор ключевых фраз. Вход — под своим логином Директа, регистрировать приложение и подавать заявку не нужно.

Как подключить Директ к ИИ без токена и заявки

Типичный сценарий выглядит так: человек получает токен, вставляет его в промпт или в самодельный скрипт и просит нейросеть «оптимизировать кампании». Работает до первой ошибки. Токен остаётся в истории чата и в логах. Агент, который не знает про баллы, опрашивает API в цикле и упирается в лимит. Агент, которому не задали рамок, поднимает бюджет, потому что «так конверсий больше». А под ЕПК ещё и нужна версия v501, о которой модель может не знать.

MCP-сервер Яндекс Директа стоит между ИИ и API. Вы один раз авторизуетесь через свой аккаунт Яндекса в кабинете BotB2B, в разделе «Интеграции» — регистрировать приложение и подавать заявку на доступ к API не нужно. Токены хранятся на платформе; Claude, ChatGPT, Cursor или Claude Code получают инструменты — «покажи расход и конверсии по кампаниям», «останови объявления с низким CTR», «поправь ставки», — а не доступ к кабинету. Перед API Директа и Метрики стоит ограничитель частоты, который гасит шквал запросов из-за ошибки в сценарии. Каждый вызов инструмента виден в чате, доступ по каждому подключению отзывается отдельно. В том же коннекторе — Метрика и Яндекс Аудитории: цели, конверсии и сегменты доступны агенту без второго токена. MCP-серверы подключаются по выбранному тарифу; рекламный бюджет остаётся в Директе.

Если управлять из чата не хочется вовсе, поверх тех же инструментов работает ИИ-директолог: он ведёт кампании по расписанию в рамках подтверждённого вами лимита расходов. А посмотреть, что происходит в кабинете сейчас, можно без единой правки — это аудит Директа в режиме чтения. Пошаговое подключение коннектора к ИИ-клиенту — в инструкции как подключить MCP; аналогичный разбор для Авито — API Авито: как получить ключ.

Частые вопросы