Мониторинг бюджетов Яндекс Директа через API: 250 строк Python вместо ежедневной ручной проверки

Шесть компаний в одном холдинге, у каждой свой аккаунт в Яндекс Директе, свой бюджет, свои кампании. Каждый день нужно заходить в шесть разных интерфейсов, смотреть расход, прикидывать в голове прогноз на месяц, сверять с планом. На это уходит 30-40 минут ежедневно, а если забыл проверить пару дней подряд, можно улететь в перерасход на сотню тысяч.

Я написал скрипт на Python, который подключается к API Директа, собирает расход по всем шести аккаунтам, сравнивает с месячным планом и показывает, где проблема. 250 строк кода, минута на запуск. При первом же прогоне нашёл перерасход, о котором никто не подозревал.

Проблема: шесть аккаунтов, ноль контроля

Промышленный холдинг, шесть юрлиц, у каждого свой сайт и свой рекламный аккаунт. Общий месячный бюджет на Директ порядка 400 000 рублей.

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

Подключение API: это не так просто, как кажется

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

Семь этапов получения доступа

Главный совет: не пишите в заявке «хочу получать данные». Распишите конкретно: «Скрипт запрашивает отчёт ACCOUNT_PERFORMANCE_REPORT по полю Cost за текущий месяц, сравнивает с плановым бюджетом, формирует сводку для менеджера». Чем конкретнее, тем быстрее одобрят.

Архитектура скрипта

Скрипт устроен просто. Конфиг с клиентами, функция запроса к API, функция расчёта отклонений, вывод результата. Никаких фреймворков, базы данных, веб-интерфейса. Запускается из терминала, выводит таблицу.

Ключевые формулы

Логика простая, но именно её не хватает, когда проверяешь бюджеты вручную:

# План на сегодня (линейный)
plan_today = monthly_budget / days_in_month * today.day

# Отклонение от плана
deviation = (actual_spent - plan_today) / plan_today * 100

# Прогноз на конец месяца
projected = (actual_spent / today.day) * days_in_month

# Безопасный дневной бюджет
safe_daily = (monthly_budget - actual_spent) / days_left

Безопасный дневной бюджет — самая полезная метрика. Если видишь, что safe_daily для конкретного клиента стал 500 рублей при обычном расходе 3000, значит, пора резать кампании прямо сейчас.

Что показал первый запуск

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

Три компании перерасходовали мартовский бюджет. Одна — на 65%. Это 45 000 рублей сверх плана только по одному аккаунту. По трём суммарно — больше 90 000 рублей перерасхода за месяц.

Почему это произошло? Автостратегии Директа оптимизируются под конверсии, но не следят за месячным бюджетом. Дневной лимит кампании — это не то же самое, что контроль месячного плана. Если в какой-то день конверсий было много, Директ спокойно потратит больше дневного бюджета (да, он это делает). А за месяц эти «небольшие превышения» складываются в десятки тысяч.

Что скрипт считает по каждому клиенту

Не просто «факт vs. план». Скрипт даёт четыре метрики, которые показывают полную картину:

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

Техническая реализация

Конфиг клиентов

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

CLIENTS = {
    "company-a.ru": {
        "login": "company_a_login",
        "budget": 70_000,
        "name": "Компания А",
    },
    # ... ещё 5 клиентов
}

Запрос к Reports API

Яндекс Reports API работает асинхронно. Отправляешь запрос на формирование отчёта, получаешь статус 201 или 202 (отчёт готовится), ждёшь, повторяешь. Когда готово — статус 200 и TSV-данные в теле ответа.

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Client-Login": client_login,  # переключение между аккаунтами
    "processingMode": "auto",
    "returnMoneyInMicros": "false",
}

# Если статус 201/202 --- ждём и повторяем
while response.status_code in (201, 202):
    wait = int(response.headers.get("retryIn", 5))
    time.sleep(wait)
    response = requests.post(url, headers=headers, json=body)

Между запросами к разным клиентам — пауза 3 секунды. Яндекс ограничивает частоту запросов, и без паузы можно получить блокировку.

Обработка ошибок

API может вернуть ошибку, пустой ответ или невалидные данные. Скрипт обрабатывает каждый случай: логирует ошибку, помечает клиента как «ОШИБКА API» в итоговой таблице и продолжает работу по остальным. Один упавший аккаунт не ломает весь отчёт.

Что я бы добавил дальше

Скрипт решает главную задачу — видеть все бюджеты в одном месте за секунды. Но есть куда развивать:

• Автозапуск по расписанию — cron-задача каждое утро, результат в Telegram-бот или на почту. Чтобы не запускать руками.
• Алерты по порогу — если отклонение больше 20%, скрипт сам отправляет уведомление. Не нужно читать весь отчёт.
• История в базе — записывать расход каждый день, строить графики. Видеть тренд, а не только текущую точку.
• Автоматическое снижение ставок — через Bids API можно снижать ставки, когда бюджет уходит за план. Но это уже требует осторожности.

Выводы

Если у вас больше двух-трёх аккаунтов в Директе, ручной контроль бюджетов — это просто лотерея. Рано или поздно пропустите перерасход. API + Python решает эту задачу раз и навсегда.

Я собрал шаблоны, которые использую в работе с клиентами: медиаплан, учёт рабочего времени, аналитические отчёты. Скачайте бесплатно на странице шаблонов.

Шаблоны для маркетинга

Профессиональные шаблоны для организации работы:
медиапланирование, учёт времени, аналитические отчёты

E-mail *

Получить материалы

Поставив галочку, вы даете согласие на обработку персональных данных. Подробнее об обработке данных в Политике.