API Директа перестал быть территорией разработчиков: скрипт под свой кабинет теперь собирается за вечер по описанию задачи словами. Разбираю, как получить доступ и что писать в заявке, как выглядят запросы и ответы, что такое баллы и почему они кончаются, и где API избыточен.
- Подключение бесплатное, ограничение — в баллах: суточный лимит зависит от активности кампаний.
- Порядок доступа: приложение в Яндекс ID с правом direct:api → заявка в Директе с ClientID.
- Страница настроек API открывается только после создания хотя бы одной кампании в вебе.
- Актуальный адрес сервисов — /json/v501/, метод всегда POST, тело в JSON.
- Ошибка вызова стоит 20 баллов, поэтому отладку гоняют на минимальных выборках.
Что такое API Директа и что через него делают
API Яндекс Директа — программный интерфейс для управления кампаниями без веб-интерфейса. Через него внешние приложения добавляют и правят кампании, объявления и ключевые фразы, задают ставки и выгружают статистику. Подключение и использование бесплатные: платите вы только за саму рекламу.
Раньше это была история для разработчиков: чтобы получить пользу от API, нужно было писать код. Сейчас порог упал — скрипт под свой кабинет собирается за вечер в Claude Code или Cursor по описанию задачи словами.
| Задача | Через какие сервисы | Что даёт |
|---|---|---|
| A/B-тест сотен вариантов текста | Ads.add и Ads.update | Генерация вариантов и загрузка пачками. Руками это недели, скриптом — вечер |
| Чистка площадок РСЯ по расписанию | Reports плюс корректировки | Площадка отключается по правилу до того, как успела слить бюджет |
| Выгрузка статистики в свою систему | Reports | Отчёт в TSV по расписанию: в BI, в таблицу, в дашборд |
| Синхронизация с остатками на складе | Ads и Keywords | Товара нет — объявление остановлено. Без ручных проверок |
| Кампании по пересечениям аудиторий | RetargetingLists и AdGroups | Комбинаторика сегментов, которую руками собирать день |
| Ежедневный контроль изменений | Changes | Кто и что поменял в кампаниях с прошлой проверки |
Как получить доступ: приложение и заявка
Доступ выдаётся конкретному приложению. Порядок такой: сначала регистрируете приложение в Яндекс ID, потом подаёте заявку на доступ к API в самом Директе.
На практике всё бывает быстрее. В канале я писал, как это выглядело у меня: в форме заявки просят скриншоты приложения и описание принципов работы — ответы на эти вопросы пишет Claude, скриншот прикладывается из кабинета. Поддержка отвечает за пару часов, в том числе ночью, и доступ можно получить в тот же день.
Из поста в моём канале: как быстро подключить Claude к Яндекс Директу
OAuth-токен: как получить и чем он ограничен
Авторизация идёт по протоколу OAuth 2.0. Токен — это код, который разрешает приложению доступ к данным конкретного пользователя Директа, и указывать его нужно в каждом запросе.
| Что | Как |
|---|---|
| Один токен — один пользователь | Для каждого пользователя Директа, от имени которого идут запросы, нужен свой токен |
| Права наследуются | Приложению доступно ровно то, что доступно самому пользователю |
| Отладочный токен | На этапе отладки его получают вручную от имени тестового пользователя |
| Автоматическое получение | В рабочем приложении пользователь проходит по ссылке Яндекс ID и нажимает «Разрешить» |
Как выглядит запрос и ответ
API состоит из веб-сервисов: у каждого свой адрес и свой набор методов. Запросы идут по HTTPS методом POST, данные — в JSON или SOAP/XML.
Типовой запрос на получение списка кампаний выглядит так:
В ответе приходит результат и служебные заголовки. Главный из них — Units: в нём видно, сколько баллов списалось, сколько осталось и каков суточный лимит.
Почти у всех методов один и тот же набор: add, update, delete, get. Плюс специфические — например moderate у сервиса Ads для отправки объявлений на модерацию.
Конструктор запроса и расчёт баллов
Чтобы не листать документацию ради тела запроса и стоимости операции, собрал переключатель по основным сервисам.
Считать баллы до запуска стоит всегда: массовая загрузка объявлений через Ads.add обходится в 20 баллов за вызов плюс 20 за каждое объявление, и тысяча объявлений съедает заметную часть суточного лимита.
Из чего состоит API
Сервисов больше двадцати. Ниже — те, с которыми работают чаще всего.
| Сервис | За что отвечает | Типовые задачи |
|---|---|---|
Campaigns | Кампании | Создание, правка, остановка и запуск, архив |
AdGroups | Группы объявлений | Структура внутри кампании, регионы группы |
Ads | Объявления | Тексты, ссылки, отправка на модерацию, статусы |
Keywords | Ключевые фразы и автотаргетинги | Добавление, правка, ставки, продуктивность |
KeywordBids | Ставки | Управление ставками по фразам и группам |
Reports | Статистика | Отчёты в TSV с нужными полями и группировками |
Changes | Проверка изменений | Что поменялось с прошлой синхронизации |
Dictionaries | Справочники | Регионы, часовые пояса, валюты и прочее |
RetargetingLists | Условия ретаргетинга | Сегменты и условия подбора аудитории |
NegativeKeywordSharedSets | Наборы минус-фраз | Общие минус-слова на уровне аккаунта |
Feeds | Фиды | Товарные фиды для динамических и товарных кампаний |
AgencyClients | Клиенты агентства | Заведение и настройка клиентских аккаунтов |
Баллы: лимиты и как их не проесть
Баллы — способ регулировать нагрузку на серверы. Суточный лимит индивидуальный и зависит от активности кампаний: чем больше показов, кликов и расхода, тем выше лимит.
| Правило | Деталь |
|---|---|
| Начисление по скользящему окну | В начале каждого часа начисляется 1/24 суточного лимита, неизрасходованное за прошлые 23 часа остаётся доступным |
| Списание за ошибки | Ошибка вызова метода — 20 баллов, ошибка операции с объектом — 20 баллов за операцию |
| Пять параллельных запросов | Больше одновременных запросов от одного рекламодателя API не принимает |
| Чьи баллы тратятся | У агентства это зависит от заголовка Use-Operator-Units: с ним — баллы агентства, без него — клиента |
| Где смотреть остаток | Заголовок Units в ответе на каждый запрос |
get по одному объекту вместо одной выборки на тысячу. Стоимость вызова платится каждый раз — тысяча вызовов вместо одного превращает 15 баллов в 15 000.Статистика через сервис Reports
Отчёты живут отдельно от остальных сервисов. Запрос отправляется на адрес /json/v501/reports, параметры передаются в теле, а сам отчёт приходит в формате TSV в кодировке UTF-8.
| Что | Как устроено |
|---|---|
| Формат ответа | TSV — таблица с разделителями-табуляциями, удобно грузится в любую систему |
| Онлайн и офлайн | В зависимости от объёма и заголовков сервер отдаёт отчёт сразу или ставит в очередь |
| Поля и группировки | Набор полей задаётся в запросе: кампании, группы, фразы, площадки, устройства |
| Период | Задаётся датами или предустановленным диапазоном |
Именно на Reports держится большинство рабочих сценариев: выгрузка в BI, ежедневные проверки площадок, контроль стоимости конверсии по срезам. Всё остальное — управление объектами — обычно строится уже поверх этих данных.
Когда API не нужен
API оправдан на объёме и регулярности. Если задача разовая или её закрывает штатный инструмент, проще обойтись без него.
| Задача | Чем закрыть | Комментарий |
|---|---|---|
| Массовые правки текстов и фраз | Директ Коммандер | Бесплатная программа, разбор здесь |
| Отчёты и срезы статистики | Мастер отчётов в кабинете | Группировки, фильтры, выгрузка — без единой строки кода |
| Автоматизация ставок и правил | Готовые сервисы и биддеры | Работают через тот же API, но настройка идёт мышкой |
| Разовая выгрузка в таблицу | Отчёты Директа и Метрики | Если задача разовая, API обычно избыточен |
Шесть проблем, на которых спотыкаются
Почти все обращения по API сводятся к шести ситуациям — от невозможности подать заявку до внезапно кончившихся баллов.
| Проблема | Как выглядит | В чём дело |
|---|---|---|
| Нет доступа к странице настроек API | Страница просто не открывается | В аккаунте должна быть создана хотя бы одна кампания в веб-интерфейсе |
| Заявка отклонена | Статус «отклонена» в списке заявок | Описание приложения слишком общее. В заявке нужны конкретные сведения о том, что делает приложение |
| Ошибка авторизации | Ответ с кодом 53 или 58 | Токен просрочен, выдан другому пользователю или не тот ClientID. Токен получается на каждого пользователя отдельно |
| Недостаточно баллов | Ошибка 152 | Суточный лимит исчерпан. Баллы начисляются по 1/24 в час, поэтому часть операций стоит перенести |
| Пятый параллельный запрос | Часть запросов отваливается | Ограничение — не более пяти одновременных запросов от одного рекламодателя |
| Списались баллы за неудачный запрос | Остаток тает, результата нет | Ошибка вызова стоит 20 баллов, ошибка операции с объектом — тоже 20. Отладка идёт на минимальных выборках |
Частые вопросы
Что такое API Яндекс Директа
API Директа платный
Как получить доступ к API Директа
Почему не открывается страница настроек API
Как получить токен для API Директа
Что такое баллы в API Директа
Какой адрес у API Директа
Сколько запросов можно отправлять одновременно
Можно ли работать с API без программиста
Чем API отличается от Директ Коммандера
Главное
API Директа даёт то, чего нет ни в кабинете, ни в Коммандере: собственные правила, расписание и интеграции с внешними системами. Подключение бесплатное, а весь путь до первого запроса — это приложение в Яндекс ID с правом direct:api и заявка с конкретным описанием задачи. Дальше начинается арифметика баллов: суточный лимит зависит от активности кампаний, ошибки тоже стоят денег в баллах, а цикл с тысячей одиночных запросов вместо одной выборки съедает лимит за минуты. Порог входа сейчас низкий — скрипт пишется в связке с моделью по описанию словами, но понимать, что такое токен, метод и баллы, всё равно нужно.
Автоматизирую рекламу и SEO на живых проектах, пишу об этом в Telegram. Нужен аудит кампаний или помощь с автоматизацией — напишите через бриф.