AdPump — API Яндекс Директа: что это, кому нужен и зачем автоматизировать

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

Коротко: API Директа — программный интерфейс для управления рекламой без ручной работы в кабинете.

← Каталог API Директа · Версии API · OAuth и доступ · Сервисы v5 · Лимиты и баллы · Ограничения · Кампании · Группы и объявления · Ключи и ставки · Минус-фразы и площадки · Отчёты · Песочница · Агентства · Примеры JSON · Ошибки · Автоматизация · Документация Яндекса

Содержание

Что такое API
Кому нужен
Архитектура v5
Сущности
Сценарии
С чего начать
Ограничения

Что такое API Директа

API Яндекс Директа — программный интерфейс для управления рекламными кампаниями, группами, объявлениями, ключевыми фразами, ставками и статистикой. Актуальная версия — API v5: JSON over HTTPS, без SOAP.

Каждый вызов — POST на https://api.direct.yandex.com/json/v5/{service} с телом {"method": "...", "params": {...}}. Отчёты выгружаются отдельным endpoint https://api.direct.yandex.com/json/v5/reports. Об API Директа.

API не заменяет весь веб-интерфейс кабинета: часть операций (оплата, визуальные редакторы мастеров) доступна только в UI. Подробнее — в разделе Ограничения.

Интеграция с API требует OAuth-токена и соблюдения лимитов: не более 5 параллельных запросов и учёт суточной квоты баллов.

Рекомендуем начать с песочницы, затем перейти к боевому URL и автоматизации рутинных задач.

Для массовых операций используйте батчи: до 1000 сущностей в одном add и обработку LimitedBy при пагинации.

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

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

Разработчики SaaS и CRM — встраивают управление рекламой в свои продукты: создание кампаний из каталога, синхронизация статистики, алерты по бюджету.
Рекламные агентства — ведут десятки и сотни клиентских аккаунтов через Client-Login и сервис agencyclients.
Директологи и performance-маркетологи — автоматизируют рутины: минусовка, проверки, ставки, отчёты.
Аналитики и BI — выгружают статистику в хранилища данных через Reports API.
In-house команды — строят собственные скрипты на Python, PHP, Node.js для конкретного аккаунта без подписки на сторонние сервисы.

Архитектура API v5

API v5 организован по сервисам. Каждый сервис отвечает за свою сущность и имеет набор методов: get, add, update, delete, suspend и др. Полный список — Сервисы v5.

POST https://api.direct.yandex.com/json/v5/campaigns

Content-Type: application/json; charset=utf-8

Authorization: Bearer <access_token>

Accept-Language: ru

{
  "method": "get",
  "params": {
    "SelectionCriteria": {"States": ["ON", "SUSPENDED"]},
    "FieldNames": ["Id", "Name", "State", "Status"],
    "Page": {"Limit": 100}
  }
}

Авторизация — OAuth 2.0 (OAuth и доступ). Для агентств добавляется заголовок Client-Login. Тестирование — в песочнице на https://api-sandbox.direct.yandex.com/json/v5.

Каждый сервис — отдельный URL: https://api.direct.yandex.com/json/v5/campaigns, https://api.direct.yandex.com/json/v5/keywords и т.д. Метод указывается в JSON-теле, а не в пути.

Ответ содержит result или error. Заголовок Units показывает остаток баллов на день.

Иерархия сущностей

Сущность	Сервис	Описание
Кампания	campaigns	Бюджет, стратегия, расписание, минус-фразы на уровне кампании
Группа объявлений	adgroups	Регионы, тип группы, минус-фразы группы
Объявление	ads	Текст, баннер, ЕПК — после add уходит на модерацию
Ключевая фраза	keywords	Фраза, ставка, статус
Ставка	bids / keywordbids	Ставки на группу или ключ
Корректировка	bidmodifiers	Демография, устройства, площадки РСЯ
Отчёт	reports	Асинхронная выгрузка статистики

Типичный порядок создания: campaigns.add → adgroups.add → ads.add → keywords.add → ожидание модерации → keywords.add / bids.set.

Типовые сценарии использования

Задача	API-методы	Примечание
Создать кампанию с нуля	campaigns.add, adgroups.add, ads.add, keywords.add	См. {lnk('yandex-direct-api-kampanii', 'Кампании')}
Остановить показы на выходных	campaigns.suspend	Мгновенно, без модерации
Массовая минусовка	reports + campaigns.update / adgroups.update	По отчёту поисковых запросов
Сбор статистики	Reports API	TSV/CSV, асинхронно
Проверка баланса	clients.get	Для агентств — с Client-Login
Автоправила ставок	keywordbids.set, bidmodifiers.add	По расписанию cron
Чистка площадок РСЯ	reports + bidmodifiers.add (PLACEMENT)	По отчёту площадок

С чего начать работу

Зарегистрировать OAuth-приложение на oauth.yandex.ru и получить токен (OAuth).
Протестировать запросы в песочнице.
Выполнить тестовый campaigns.get по примерам JSON.
Изучить лимиты и баллы и коды ошибок.
Вывести автоматизацию на боевой среде (сценарии).

Коротко: Для новых интеграций используйте только API v5. Live 4 и API v4 устарели — см. Версии API.

Ограничения — кратко

API имеет квоты на параллельные запросы (до 5 одновременно на приложение) и суточные лимиты баллов (units). При превышении — ошибка 152. Подробности: Лимиты и баллы, Ограничения.

Перейти в инструмент