/zoomkit

Отчёты статистики

Тело запроса

Для POST /stats/reports обязательны:

• type: CAMPAIGN_ADSET_REPORT, CAMPAIGN_PHRASES_REPORT или CAMPAIGN_QUERIES_REPORT;
• date_start и date_end в формате YYYY-MM-DD;
• clients — от 1 до 20 уникальных значений вида тип:id.

Поддержка типов:

• CAMPAIGN_ADSET_REPORT — все интеграции;
• CAMPAIGN_PHRASES_REPORT — Яндекс.Директ и Google Ads;
• CAMPAIGN_QUERIES_REPORT — только Яндекс.Директ.

Необязательный callback должен быть доступным URL. ZoomKit отправит туда POST после обработки; обработчик должен отвечать асинхронно.

Сначала получи идентификаторы:

sh scripts/zoomkit.sh clients

Скопируй assets/report-request.example.json, измени даты и клиентов, проверь тело без сети, затем создай отчёт:

sh scripts/zoomkit.sh report-create --body /tmp/report-request.json --dry-run
sh scripts/zoomkit.sh report-create --body /tmp/report-request.json --confirm

Жизненный цикл

Успешное создание возвращает 202. Состояния: CREATED, PROCESSED, READY, FAILED.

sh scripts/zoomkit.sh report-wait --id 123

report-wait опрашивает GET /stats/reports/{id} с интервалом 5 секунд, останавливается на READY или FAILED и сохраняет последнее полное состояние в cache/report-<ID>.json. Срок опроса одного запуска — не более 55 секунд; сетевой срок каждого запроса ограничивается оставшимся временем. Небольшая служебная задержка возможна. Если отчёт всё ещё обрабатывается, повтори ту же команду. Интервал можно менять от 1 до 30 секунд, срок ожидания — от 0 до 55:

sh scripts/zoomkit.sh report-wait --id 123 --interval 10 --timeout 50

Отдельного метода ожидания и рекомендованного интервала в API нет; ожидание выполняет сценарий, соблюдая общий предел 60 запросов в минуту. Считать данные готовыми можно только при READY; FAILED — окончательная ошибка обработки.

Если при создании получен 409, не повторяй POST. Возьми conflict_report_id из ответа и ожидай уже существующий отчёт. Если указан callback, ZoomKit уведомит о завершении, но результат всё равно нужно получить командой report; способ проверки подлинности обратного вызова спецификация не описывает.

Готовые отчёты хранятся неделю. Результат может быть крупным, поэтому читай сохранённый cache/report-<ID>.json, не используй --raw без необходимости.

Поле reports — словарь по клиентам. Значение бывает массивом строк статистики либо объектом с error; проверяй ошибку каждого клиента отдельно. Состав строк отчёта в спецификации строго не описан, поэтому не считай пример, включая встречающийся там campaign_id, гарантированной схемой всех показателей.

Создание доступно только при активной платной подписке или через отдельные сторонние решения.