Автоматические отчёты по Яндекс Директу: как устроены API, PDF и Telegram и что требовать от подрядчика

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

Зачем нужен автоотчёт

Автоматизация окупается, когда клиентов больше двух-трёх. Раз в неделю система:

• снимает статистику Директа;
• добавляет из Метрики отказы и глубину просмотра;
• сравнивает настройки кампаний с прошлой неделей;
• собирает PDF с логотипом и цветами;
• отправляет в чат с клиентом.

Есть два режима: полуручной, когда в понедельник вы пишете агенту «собери отчёт», и полный автомат, когда расписание всё делает само. О том, как ставить задачи нейросети, подробно в статье про работу с нейросетями.

Какую нейросеть брать

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

Как подключить Директ к автоотчёту: пять шагов

Шаг 1. Приложение на oauth.yandex.ru

Это отдельный сайт, не Директ. Входите под логином, к которому нужен доступ.

• Тип приложения — «Для доступа к API или отладки».
• Название — любое, например «Еженедельные отчёты».
• В поиске доступов пишите по-английски: dir и metr. Нужны два права: direct:api и metrika:read.
• Сохраните ClientID и секрет.

Шаг 2. Заявка в Директе

В самом Директе: «Настройки API» → «Мои заявки» → «Новая заявка». Если страница не открывается, примите соглашение об использовании API; в кабинете должна быть хотя бы одна кампания.

• Выберите ClientID, который создали на первом шаге.
• В описании честно напишите: «выгрузка статистики и еженедельные PDF-отчёты клиентам, без управления ставками».
• Рассматривают до 7 дней, на практике часто за 10–15 минут.

Шаг 3. Токен

Только после статуса «одобрена». Откройте под нужным аккаунтом адрес https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID. Полученный токен положите в файл настроек .env. Не храните его в переписке и не отправляйте в общий репозиторий.

Шаг 4. Telegram-бот

• Создайте бота через официальный @BotFather — только с синей галочкой. Команда /newbot, имя, адрес, оканчивающийся на bot, и вы получите токен.
• Один бот может работать на все проекты: просто добавьте его в разные чаты.
• Дайте боту право удалять сообщения: если отправит лишнее, сможет убрать.
• Узнайте chat_id нужного чата, например через бота, который показывает ID.

Шаг 5. Сборка и расписание

Дайте агенту подробное задание: ниша, сайт, токен Директа, цели Метрики, токен бота, chat_id. Пусть не начинает писать код, пока всех данных нет, и не подставляет заглушки. Первый отчёт отправьте вручную и посмотрите, всё ли в порядке. Проект храните в закрытом репозитории, секреты — в .env. Затем поставьте расписание: например, каждый понедельник в 9:00 по Москве.

Что API отдаёт, а что нет

Журнал «История изменений» из интерфейса через API не выгружается. Есть только флаги: менялась ли сама кампания, менялось ли что-то внутри неё, поправил ли Яндекс статистику (часто это антифрод).

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

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

Какие показатели включать: примеры

• Ремонт квартир. Директ: расход, клики, цена клика по кампаниям. Метрика: заявки по цели «Отправил форму» и звонки, цена заявки. Сравнение с прошлой неделей в процентах. Блок «Что меняли» только из снимка.
• Интернет-магазин. Расход и клики по товарным и поисковым кампаниям, заказы и выручка, доля рекламных расходов, топ-5 товаров по выручке, отказы по главным категориям.
• Стоматология. Расход, клики, показы; записи онлайн и звонки, цена записи; доля мобильного трафика и его конверсия; отказы и глубина просмотра по страницам услуг.
• B2B-оборудование. Расход и клики по направлениям; запросы КП, скачивания прайса, звонки; цена запроса КП; фразы с расходом без конверсий за 2 недели.

Раз в месяц сверяйте отчёт с CRM. Если цифры заявок расходятся, сначала чините цели, а не отчёт. Про цели, счётчик и отчёты Метрики — в статье про Яндекс Метрику, а про сводку Директа и CRM — в статье про аналитику поверх Директа.

Чек-лист

• Приложение на oauth.yandex.ru создано, права direct:api и metrika:read выданы.
• Заявка в Директе одобрена, токен получен после одобрения.
• В заявке указано: только статистика и отчёты, без управления ставками.
• Бот создан через официальный BotFather, адрес оканчивается на bot.
• Бот добавлен в чат с клиентом, может удалять сообщения, chat_id известен.
• Первый тестовый PDF отправлен вручную.
• Снимки настроек сохраняются между запусками.
• Секреты только в .env, репозиторий закрытый.
• Расписание стоит на нужный день и час.