Click.ru Tools

Инструменты для работы с Click.ru API — платформы для управления рекламными кампаниями. Репозиторий содержит скрипты для автоматизации рутинных задач маркетингового агентства.

📂 Состав

Скрипт	Назначение
daily_budget_report.py	Мониторинг бюджетов Яндекс.Директ: прогноз по балансу кабинета и алерты с разбивкой по плательщикам
client_report.py	Клиентский отчёт по кабинету Директ в .xlsx: выбор суб-пользователя и кабинета, статистика по неделям через прокси к API Директа, сводка в конце

🚀 Быстрый старт

1. Клонируйте репозиторий

git clone https://github.com/antonbru/clickru-tools.git
cd clickru-tools

2. Настройте конфигурацию

cp config.example.json config.json

Отредактируйте config.json — укажите ваш мастер-токен Click.ru API:

{
    "clickru": {
        "token": "ваш_токен_clickru_api",
        "base_url": "https://api.click.ru/V0"
    }
}

Как получить токен: зайдите в Click.ru → Профиль → API → сгенерируйте мастер-токен.

Для client_report.py дополнительно установите зависимости:

pip install -r requirements.txt

Или задайте токен через переменную окружения:

export CLICKRU_TOKEN="ваш_токен"

3. Запустите отчёт

# Только проблемные кабинеты (запас < 3 дней на кабинете)
python daily_budget_report.py

# Все кабинеты, включая с нормальным бюджетом
python daily_budget_report.py --all

# С явным указанием пути к конфигу
python daily_budget_report.py -c /путь/к/config.json

📊 Пример вывода

📊 Бюджеты Директ — 14.07.2026
==================================================

🔴 Кофейня «Аромат» — Основной кабинет
   Баланс кабинета:            0 ₽ (Директ: aroma-123456-abcd)
   Расход в день:          4 454 ₽ (ср. за 2 дн.)
   Последние траты:     2026-07-28
   Прогноз:                 0.0 дн. — ЗАКОНЧИЛИСЬ
   Плательщики (28 256 ₽ всего):
   • BUSINESS (ООО «ГУЖЕР»): 27 750 ₽
   • BUSINESS (ООО «ВЕРАНДА»): 506 ₽
   💡 На балансе плательщиков есть 28 256 ₽ — нужно пополнить кабинет

🟡 ООО «СтройДом» — Поисковая реклама
   Баланс кабинета:        5 000 ₽ (Директ: stroydom-654321-efgh)
   Расход в день:          6 500 ₽ (вчера)
   Прогноз:                 0.8 дн. — МЕНЕЕ 1 ДНЯ
   💡 Баланс плательщиков пуст — нужно пополнить баланс в Click.ru

⚪ ООО «Ромашка» — РСЯ
   Баланс кабинета:       12 000 ₽ (Директ: romashka-789012-ijkl)
   Расход в день:     НЕТ ДАННЫХ
   ⚠️  вчера: HTTP 500; неделя: HTTP 500
   💡 Баланс плательщиков пуст — нужно пополнить баланс в Click.ru

==================================================
⚠️  Требуют пополнения: 2 каб. (🔴 1 — закончились, 🟠 1 — менее 1 дня)
❓ 1 каб. — нет данных по статистике, прогноз не рассчитан

📊 Клиентский отчёт в xlsx (client_report.py)

Собирает статистику по одному кабинету Яндекс.Директ с группировкой по неделям (показы, клики, расход, CTR, процент отказов, конверсии) и сохраняет отчёт в .xlsx со сводкой в конце.

# Интерактивно: выбор суб-пользователя → кабинета → периода (недель)
python client_report.py

# Без интерактивного выбора
python client_report.py --user 42 --account 500 --weeks 4

# Явное имя файла
python client_report.py --weeks 13 --out report.xlsx

Как работает:

1. GET /users → список суб-пользователей, интерактивный выбор (или --user).
2. GET /accounts → активные кабинеты Директ, интерактивный выбор (или --account).
3. Период — вопрос при запуске, по умолчанию 4 недели (до вчерашнего дня, МСК); задаётся флагом --weeks.
4. Статистика — через прокси Click.ru к API Директа: POST {base_url}/api_proxy/yandex_direct?url=https://api.direct.yandex.com/json/v5/reports с заголовком Client-Login (логин кабинета). Отчёт CAMPAIGN_PERFORMANCE_REPORT по каждой неделе (от понедельника) с разбивкой по типам площадок (AdNetworkType) и кампаниям (CampaignId/CampaignName), ответ прокси — TSV. Если неделю получить не удалось, она помечается «нет данных» и причина выводится в stderr — отчёт продолжает строиться.
5. Конверсии: цель оптимизации каждой кампании берётся из Strategy.<тип>.GoalId (v5 campaigns); названия целей — через v4 GetStatGoals (прокси документирован для v5/v501, поэтому если v4 не сработает — в отчёте покажутся только ID целей).
6. Производные метрики — взвешенные агрегаты строк отчёта: CTR = клики/показы, CPC = Σ(AvgCpc·клики)/клики, средняя позиция показа и % отказов и глубина просмотра — средневзвешенные по показам (без поля Sessions точные агрегаты Метрики из строк Директа не восстановить). Если к кампаниям не подключён счётчик Метрики, колонки «отказы», «глубина просмотра» и «конверсии» равны 0, о чём в отчёте есть примечание.
7. В конце таблиц — сводка: итоги за период (суммы, общий CTR, средневзвешенный % отказов), среднее за неделю, итоги по каждой кампании.

Структура .xlsx (один лист «Отчёт»):

• Таблица «Неделя × Кампания × Тип площадки»: колонки Неделя, Кампания, Тип площадки (поиск, сети и пр.), Показы, Клики, CTR %, Расход ₽, CPC ₽, Ср. позиция показа, Отказы %, Глубина просмотра, Конверсии; в конце — строка «ИТОГО за период»;
• цель оптимизации кампании (название цели конверсии, на которую настроена кампания) показывается в скобках у названия кампании.

Путь прокси к API Директа по умолчанию — {base_url}/api_proxy/yandex_direct (эндпоинт POST /api_proxy/yandex_direct?url=<url директа> + заголовок Client-Login). При необходимости переопределяется через config.json → clickru.direct_proxy_url или env CLICKRU_DIRECT_PROXY_URL.

🔧 Как работает

1. Авторизация: скрипт получает ID мастер-пользователя через GET /user
2. Обход суб-пользователей: получает список всех USER-аккаунтов через GET /users
3. Сбор балансов: для каждого пользователя:
   • GET /accounts → фильтрует активные кабинеты Яндекс.Директ
   • Рядом с балансом кабинета выводится логин кабинета в Яндекс.Директ (serviceLogin) — видно, к какому кабинету Директа относится сумма
   • GET /users/payers → собирает балансы плательщиков с разбивкой по каждому
4. Статистика расходов: через GET /stat/v2:
   • Основной расчёт — по вчерашнему дню
   • Если вчера расхода не было (например, выходной) — среднее за 7 дней
   • В таком случае выводится дата последних трат — видно, когда реклама реально шла
   • Если статистику получить не удалось (сбой API, неразбираемый CSV) — кабинет помечается ⚪ «НЕТ ДАННЫХ» и показывается всегда, чтобы сбой данных не выглядел как «всё в порядке»
5. Прогноз: баланс_кабинета / дневной_расход — считается только от денег на кабинете, а не от суммы с плательщиками. Если расходов нет вовсе — выводится «нет расходов»
6. Плательщики: показываются только с положительным балансом, BLOCKED (налоговый резерв) и нулевые не выводятся
7. Алерты:
   • 🔴 ≤ 0 дней — деньги закончились
   • 🟠 < 1 дня — критически мало
   • 🟡 < 3 дней — требуется пополнение
   • 🟢 ≥ 3 дней — норма (скрыто по умолчанию)
   • ⚪ нет данных по статистике — прогноз не рассчитан (показывается всегда)
8. Рекомендация:
   • Есть деньги на плательщиках → «нужно пополнить кабинет»
   • Плательщики пусты → «нужно пополнить баланс в Click.ru»
9. Время: даты отчёта («вчера», «неделя») считаются по Москве (UTC+3), а не по времени сервера, где крутится cron
10. Лимиты API: 5 запросов/с и 3600/час. При HTTP 429 скрипт сам ждёт (по заголовку X-RateLimit-Reset) и повторяет запрос; остальные ошибки выводятся в stderr и помечают кабинет как «нет данных», а не маскируются

⚙️ Автоматизация (cron)

Для ежедневного запуска добавьте в crontab:

# Каждый день в 9:00 по Москве
0 6 * * * cd /путь/к/clickru-tools && python daily_budget_report.py >> /var/log/clickru-report.log 2>&1

📦 Зависимости

• daily_budget_report.py — только стандартная библиотека Python 3.8+.
• client_report.py — плюс openpyxl для генерации .xlsx:

pip install -r requirements.txt

🧪 Тесты

Тесты работают без сети и токена — только unittest/mock:

python3 -m unittest test_daily_budget_report.py test_client_report.py

test_client_report.py не требует openpyxl (xlsx проверяется через mock-API); тест с реальным openpyxl выполняется, если он установлен.

Покрытие test_daily_budget_report.py: классификация алертов (границы 🔴/🟠/🟡/🟢), парсеры CSV (включая битые строки), даты МСК, ретраи HTTP 429, устойчивость к BOM, сценарии «нет данных» (⚪), фолбэк на недельное среднее, сбой плательщиков, nullable balance.

Покрытие test_client_report.py: выбор суб-пользователя/кабинета, разбиение на недели, агрегация и сводка, payload и разбор ответа прокси (обёртка Click.ru, пустой отчёт, ошибки API), сбой отдельной недели, детект Метрики, сборка xlsx.

🔗 Полезные ссылки

• Документация Click.ru API
• Справка Click.ru
• Swagger API

📄 Лицензия

MIT