Работа через веб-интерфейс и Коммандер закрывает большинство задач, но если вы управляете десятками аккаунтов или хотите строить собственные отчёты в реальном времени - без API не обойтись. API Яндекс Директа открывает возможности, которые недоступны через интерфейс: программный доступ к данным, автоматизация без ограничений, интеграция с любыми внешними системами. Разберём, что именно можно автоматизировать и с чего начать.
Что такое API Яндекс Директа
API Яндекс Директа - это программный интерфейс, который позволяет управлять рекламными кампаниями и получать данные без использования визуального интерфейса. Запросы к API отправляются по протоколу HTTPS, данные передаются в формате JSON.
Текущая версия - API версии 5 (API v5). Предыдущие версии поддерживаются в режиме совместимости, но все новые возможности добавляются только в пятую версию.
API бесплатен для использования, но требует: - Рекламного аккаунта Яндекс Директа - Регистрации приложения в Яндекс OAuth - Получения токена доступа
Лимиты API. Яндекс ограничивает количество запросов: для большинства методов - 5 запросов в секунду на аккаунт. Для отчётов - отдельная очередь. Эти ограничения важно учитывать при проектировании автоматизации.
Что можно делать через API
API покрывает практически весь функционал Директа. Основные группы методов:
Управление кампаниями
- Создание, редактирование, удаление кампаний
- Получение списка кампаний с фильтрацией по статусу, типу, дате
- Изменение бюджета и стратегий ставок
- Управление расписанием показов
Управление объявлениями и ключевыми словами
- Создание групп объявлений и объявлений
- Массовое изменение текстов, заголовков, ссылок
- Добавление и удаление ключевых слов
- Управление минус-словами на всех уровнях
Получение статистики
Это наиболее востребованная часть API. Методы отчётности позволяют получить: - Показы, клики, расходы по любым срезам - Данные по конверсиям (при интеграции с Метрикой) - CTR, CPC, CPA в любых разрезах - Данные за произвольный период
Управление аудиториями
- Работа с сегментами Метрики
- Управление условиями ретаргетинга
- Настройка корректировок ставок по аудиториям
Практические сценарии автоматизации
Автоматическая выгрузка отчётов
Самый распространённый сценарий - ежедневная выгрузка данных в Google Таблицы или BI-систему. Скрипт раз в сутки запрашивает данные за вчера по всем кампаниям и записывает в таблицу. Руководитель видит дашборд в реальном времени, не тревожа специалиста.
Пример метода: reports.add создаёт запрос на отчёт, reports.get забирает готовый файл. Отчёт может включать до 50 000 строк данных.
Массовое добавление минус-слов
Сценарий: каждую неделю анализируете поисковые запросы, находите нецелевые и добавляете в минус-слова через API. Это быстрее, чем через интерфейс, и позволяет автоматизировать процесс полностью.
Метод adGroups.update или campaigns.update принимает массив минус-фраз. Можно передать список из сотен слов за один запрос.
Управление ставками
Скрипт каждые 15 минут проверяет позиции и CPC по ключевым словам, сравнивает с целевыми значениями и корректирует ставки. Это то, что делают биддеры - при желании можно написать собственный.
Метод bids.set устанавливает ставки для списка ключевых слов. Можно передать до 10 000 ключей за один запрос.
Синхронизация с внешними системами
Популярный сценарий для e-commerce: цены и наличие товаров берутся из базы данных магазина, объявления в Директе автоматически обновляются при изменении ассортимента. Если товар закончился - объявление останавливается. Появился новый товар - создаётся объявление.
Создание кампаний программно
Для агентств, которые запускают однотипные кампании для клиентов одной отрасли: шаблон структуры хранится в коде, параметры клиента подставляются автоматически. Создание кампании из 200 групп с 3 объявлениями каждая занимает минуты, а не дни.
Как начать работу с API
Шаг 1: Регистрация приложения
Зайдите на oauth.yandex.ru и создайте новое приложение. Укажите: - Название приложения - Права доступа: "Яндекс Директ - Управление кампаниями" и/или "Яндекс Директ - Чтение данных" - Callback URL (для веб-приложений)
Получите Client ID и Client Secret.
Шаг 2: Получение токена доступа
Для скриптов, работающих от имени одного аккаунта, удобнее всего OAuth-токен. Его можно получить вручную через интерфейс Яндекса без кода.
Для работы от имени нескольких аккаунтов (агентская схема) нужна полноценная OAuth-авторизация: пользователь переходит по специальной ссылке, даёт разрешение, получает код, который обменивается на токен.
Шаг 3: Первый запрос
Минимальный рабочий пример на Python:
import requests
headers = {
'Authorization': 'Bearer YOUR_TOKEN',
'Client-Login': 'your-login',
'Accept-Language': 'ru'
}
body = {
'method': 'get',
'params': {
'SelectionCriteria': {},
'FieldNames': ['Id', 'Name', 'Status']
}
}
response = requests.post(
'https://api.direct.yandex.com/json/v5/campaigns',
json=body,
headers=headers
)
print(response.json())
Этот запрос вернёт список всех кампаний с ID, именем и статусом.
API для агентств: доступ к клиентским аккаунтам
Агентства могут работать через API с клиентскими аккаунтами без необходимости получать токен каждого клиента отдельно. Для этого используется агентский доступ.
В заголовке запроса указывается логин клиента (Client-Login), а токен используется агентский. Это позволяет одним скриптом обрабатывать десятки аккаунтов последовательно.
Метод agencyClients.get возвращает список всех клиентов агентства - это стартовая точка для автоматической обработки всех аккаунтов разом.
Ограничения и подводные камни
Квоты и лимиты. У каждого метода - свои лимиты. Отчёты обрабатываются в очереди, и при высокой нагрузке время ожидания может составить несколько минут. Планируйте логику с учётом возможных задержек.
Асинхронная работа с отчётами. Отчёты не отдаются мгновенно. Нужно создать запрос, затем периодически проверять статус ("отчёт готов" или "в процессе") и забирать файл только после готовности.
Версионирование. Яндекс периодически обновляет API и устаревает старые методы. Подписывайтесь на обновления документации, чтобы не получить сюрприз в виде сломанного скрипта.
Кодировка и типы данных. Все денежные суммы в API передаются в миллионах долей рублей (microcurrency). Чтобы получить рубли, делите на 1 000 000. Это классическая точка ошибки у тех, кто начинает работу с API.
Доступ только по токену. Не храните токены в открытом коде. Используйте переменные окружения или системы хранения секретов.
Когда API нужен, а когда нет
| Сценарий | Нужен ли API |
|---|---|
| Управление 1-3 аккаунтами | Нет, достаточно Коммандера |
| Ежедневные отчёты по одному клиенту | Нет, хватит Мастера отчётов |
| 10+ аккаунтов с еженедельной отчётностью | Да |
| Интеграция с CRM или ERP | Да |
| E-commerce с динамическим ассортиментом | Да |
| Собственный биддер | Да |
| Разовое создание большой кампании | Нет, лучше импорт из Excel |
Заключение
API Яндекс Директа - мощный инструмент, но с порогом входа. Если вы работаете с Python или JavaScript - освоить базовые операции можно за несколько дней по официальной документации (direct.yandex.ru/api/docs).
Наибольшую отдачу даёт автоматизация рутины: выгрузка отчётов, обновление минус-слов, синхронизация ставок. Именно эти задачи повторяются каждый день и при ручном выполнении съедают часы. Автоматизировав их через API, специалист освобождает время для стратегической работы.