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

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

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

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

Скажу сразу: API — это не про то, чтобы «настроить и забыть». Это инструмент для конкретных повторяющихся задач, а не универсальное решение всех проблем аккаунта. Если у вас пять кампаний и правки нужны раз в месяц, скорее всего API не понадобится, и дальше в статье есть раздел о том, когда его точно не стоит внедрять.

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

API (Application Programming Interface) Директа — это стандартный технический интерфейс, через который внешняя программа может читать и изменять данные рекламного аккаунта: список кампаний, ставки, тексты объявлений, минус-слова, статистику показов и кликов. По сути это тот же функционал, что в веб-интерфейсе Директа, но доступный не через клик мышкой, а через программный запрос.

Разница на практике огромная в скорости и масштабе выполняемой работы специалиста. Изменить ставку в одном объявлении можно и руками за пару секунд, никакой автоматизации для этого не требуется вовсе. Изменить ставки в трёхстах объявлениях по правилу «поднять на 15%, если CTR выше среднего» руками — это час-два монотонной, отупляющей работы каждый раз, когда нужно повторить операцию. Через API это один запуск скрипта.

Чем API Директа отличается от API Метрики

Оба API работают по схожим принципам — авторизация через OAuth, обмен данными в структурированном формате, — но решают разные задачи. Если API Метрики нужен, чтобы забирать данные о поведении посетителей сайта и целях, то API Директа — чтобы управлять самой рекламой: не только читать статистику, но и вносить изменения в кампании.

На практике я использую оба API в связке: API Метрики поставляет данные о конверсиях и поведении, API Директа на основе этих данных вносит изменения в ставки и кампании. Разделение ответственности между чтением и записью — не техническая формальность, а разумная защита от ошибок: скрипт, который только читает данные для дашборда в DataLens, физически не может сломать рекламную кампанию, даже если в его логике есть баг.

Как получить доступ к API: токен и OAuth

Технически этот шаг требует минимальных усилий и занимает не больше часа даже у человека, который никогда раньше не работал с API какого-либо сервиса.

Доступ к API Директа получают через OAuth-токен — тот же принцип авторизации, что уже знаком по подключению коннекторов в DataLens. Токен привязывается к конкретному аккаунту Яндекса, у которого есть доступ к рекламному кабинету, и передаётся в каждом запросе к API как подтверждение прав на чтение или изменение данных.

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

Сами запросы к API оформляются в формате JSON — читаемая текстовая структура, которую понимают практически все языки программирования. Это значит, что для работы с API не обязательно писать код с нуля на низкоуровневом языке: подойдёт Python, PHP, JavaScript или любой другой язык с базовой поддержкой отправки HTTP-запросов, что делает порог входа ниже, чем может показаться на первый взгляд человеку без технического образования.

Основные возможности API: что можно автоматизировать

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

Спектр задач, которые решает API, шире, чем кажется на первый взгляд тем, кто раньше работал только через интерфейс.

Последний пункт — синхронизация с остатками на складе — недооценённая, но одна из самых окупаемых задач автоматизации: реклама закончившегося товара не просто бесполезна, она тратит бюджет и портит пользовательский опыт, когда человек кликает по объявлению, а на сайте видит «нет в наличии». Похожая логика синхронизации данных лежит в основе многих сценариев CRM-маркетинга — только там синхронизируются коммуникации с клиентом, а здесь — статус объявления.

Автоматическое управление ставками через API

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

Через API можно реализовать собственную логику управления ставками: например, повышать ставку для товаров с высокой маржой и понижать для низкомаржинальных, даже если по чистой вероятности конверсии низкомаржинальный товар кликабельнее. Такая логика напрямую связана с юнит-экономикой — цель не максимальное количество кликов, а максимальная прибыль с рекламного бюджета. Это не отменяет встроенные автостратегии Директа и модель оплаты за конверсии — скорее дополняет их точными входными параметрами там, где стандартной логики недостаточно.

Массовое редактирование объявлений и кампаний

Массовые правки — то, с чем регулярно сталкивается почти любой специалист, ведущий больше одного крупного аккаунта одновременно.

Ручное редактирование через Директ Коммандер удобнее, чем веб-интерфейс, для разовых массовых правок — например, поменять текст во всех объявлениях с упоминанием сезонной акции. Но Коммандер всё равно требует присутствия человека за компьютером и открытого приложения.

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

Особенно это заметно у агентств, ведущих несколько похожих аккаунтов одновременно: если у трёх клиентов одна и та же сезонная логика — например, отключать вечерние показы по выходным для сегмента B2B-услуг, — правило можно написать один раз и применить сразу ко всем трём аккаунтам через API, вместо того чтобы вручную заходить в каждый аккаунт по отдельности и повторять одинаковые действия.

Автоматические отчёты и выгрузка статистики

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

Именно этот сценарий чаще всего становится первым шагом в связке с DataLens: коннектор Директа в DataLens фактически использует API под капотом, просто без необходимости писать код самостоятельно. Если задача — только сводить данные для дашборда, а не менять кампании, готовый коннектор в DataLens почти всегда проще, чем писать собственный скрипт на голом API.

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

Лимиты API: сколько запросов доступно

Вопрос про лимиты обычно возникает не на старте, а когда автоматизация уже прижилась и её хочется расширить на новые задачи — стоит знать об этом ограничении заранее, чтобы не упереться в него в самый неподходящий момент.

У API Директа есть ограничения на количество запросов — это стандартная защита от перегрузки серверов, характерная для любого публичного API, а не особенность именно Яндекса. Лимит обычно растёт вместе с объёмом рекламных расходов аккаунта: чем больше бюджет и чем крупнее агентство, работающее с несколькими клиентами, тем выше доступный лимит запросов.

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

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

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

Пошаговый алгоритм: с чего начать автоматизацию

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

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

Типичные ошибки при работе с API

Большинство проблем с API возникает не из-за сложности самого интерфейса, а из-за поспешности — желания сразу автоматизировать всё и сразу, минуя осторожные промежуточные шаги.

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

Иллюстративный пример автоматизации на практике

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

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

Похожая логика применима и к управлению ставками: скрипт раз в сутки подтягивает данные о марже по категориям из CRM и пересчитывает целевую цену конверсии для каждой группы объявлений отдельно, вместо единой ставки на весь аккаунт. Это не отменяет встроенные автостратегии Директа полностью — скорее задаёт им более точные входные параметры, учитывающие бизнес-логику, которую сама платформа не может знать.

Стоит подчеркнуть: в обоих примерах человек не исключён из процесса полностью — он задаёт правила и периодически их пересматривает, а рутинное применение этих правил берёт на себя скрипт. Это отличается от полностью автономного управления рекламой, где вообще никто не проверяет, что происходит с бюджетом — такой сценарий рискован даже с хорошо протестированным кодом, потому что рынок и конкуренты меняются быстрее, чем успевает адаптироваться статичная логика скрипта.