/zoomkit

Проверочные сценарии ZoomKit

Источники: официальная спецификация ZoomKit API 1.9.0 и справка ZoomKit. Используй этот справочник для проверок по кабинетам и кампаниям.

Краткая матрица

1. Отчёт с ожиданием

1. Получи клиентов командой clients.
2. Подготовь тело из assets/report-request.example.json и проверь report-create --dry-run.
3. После явного запроса пользователя создай отчёт с --confirm.
4. Возьми возвращённый id и выполни report-wait --id ID.
5. При CREATED или PROCESSED продолжай ограниченное ожидание; при READY читай cache/report-<ID>.json; при FAILED остановись и сообщи ошибку.

При 409 используй conflict_report_id, не создавай дубликат. Подробности: REPORTS.md.

2. Подключённые кабинеты и списания

clients — это официальный «Список проектов/аккаунтов». Он возвращает интеграции, их идентификаторы, логины и ошибки, а внутри — проекты/аккаунты, то есть рекламные кабинеты. Он не возвращает enabled, paid, billed или стоимость отдельного кабинета. balance показывает только общий daily_tariff.

Если нужный кабинет Яндекс.Директа не найден по имени или комментарию, это ещё не доказывает, что он не подключён: агентские кабинеты могут иметь непонятные имена вида porg-* и пустой комментарий. Проверь в полном файле ответа именно записи yandex.direct, не сопоставляй такие аккаунты наугад и следуй ручной инструкции «Если кабинет не удаётся распознать».

В API нет метода отключения кабинета или всего логина от списаний. Не подменяй его командами client-update или bidrule-common-update: первая обновляет данные, вторая управляет биддером одной кампании.

Для ручного действия направь пользователя в интерфейс Яндекс.Директа ZoomKit: https://zoomkit.ru/yandex/tokens. Старый официальный снимок показывает действие «Убрать ключ», но не подтверждает, что оно прекращает списания или отключает один кабинет. Не предлагай его как доказанный способ управления тарифом; уточни текущее действие у support@zoomkit.ru. До и после подтверждённого ручного изменения можно сравнить общий daily_tariff, но срок пересчёта тарифа в API не документирован.

3. Настройки ставок и правила

Выполни campaigns --client ID для каждого нужного кабинета yandex.direct. Затем для каждой пригодной кампании выполни bidrules --campaign ID. Ответ содержит стратегию поиска и сетей, предупреждения, общее правило и правила по фразам. common.id = null означает, что правило ещё не сохранено; ошибка доступа или отсутствующее поле означает «неизвестно», а не «правила нет».

API показывает search_traffic_volume, search_increase_percent, search_max_bid и способ расчёта верхней границы. Он не возвращает фактически выставленную ставку каждой фразы или историю её изменения.

Список campaigns берётся из данных ZoomKit и может отставать: покажи updated_at и hints. Архивные кампании входят в ответ, но у архивных и завершённых can_set_bids равен false. Мастер кампаний и товарные кампании не возвращаются. Недавно созданную ЕПК или другую обычную кампанию можно синхронизировать через client-update, но это отдельное изменение, которое расходует баллы и требует явного разрешения пользователя.

4. Биддер без автотаргетинга

Получи список командой campaigns --client ID. Однако точно определить нужные кампании только по ответам API нельзя: в BidRule нет документированного признака типа правила автотаргетинга.

Не определяй тип по значению match: спецификация этого не гарантирует. Для просьбы «проверь» не вызывай autotargeting, потому что это изменяющий POST.

Если пользователь отдельно просит исправить пробелы, autotargeting --token-id ID --confirm создаст только недостающие правила в неархивных кампаниях активных кабинетов, где биддер на поиске включён. Существующие правила команда не меняет. Ответ created показывает число созданных правил, но не их кампании. --token-id — ID интеграции yandex.direct из clients.

5. Кампании без проверки ссылок

Для каждого нужного кабинета выполни campaigns --client ID. Затем для каждого полученного ID выполни url-check-settings --campaign ID и проверь check_urls_enabled. Значение false означает, что проверка выключена; true — включена; ошибка, отсутствие поля, 403 или 404 — состояние неизвестно.

Учитывай updated_at, hints и ограничения списка кампаний. Пустая история url-check-tasks ничего не доказывает: старые задачи удаляются через двое суток.

6. Ручная строка и защита от 404

Сначала выполни url-check-settings --campaign ID. Команда покажет текущую строку, смысл check_urls_substring_must_present и точный settings_url.

• Если страница товара остаётся успешной, но товар исчезает, задай в интерфейсе устойчивую строку доступности и режим «ошибка при отсутствии».
• Если страница содержит явное «нет в наличии», задай эту строку и режим «ошибка при наличии».
• Открой именно settings_url; текстовый блок text_settings через API доступен только на чтение. Запасной ручной путь по официальной анимации: «Яндекс.Директ» → список кампаний → «Изменить» или карандаш → «Проверка ссылок». Анимация может показывать старую раскладку интерфейса.
• Для автоматической остановки включи suspend_urls_if_substring вместе с общими check_urls_enabled и suspend_urls_enabled.
• Для HTTP 404 строка не нужна: через API можно включить suspend_urls_if_400_499.

Заготовка переключателей: assets/url-check-product-protection.example.json. Она намеренно задаёт все условия автоприостановки: включает только HTTP 4xx и строковое правило, а перенаправления, 5xx, прочие ошибки и числительные выключает. Сначала прочитай текущие настройки, покажи точную разницу и меняй их только после явного подтверждения. Текстовые поля в тело не добавляй — сценарий заблокирует их до сети.

7. Ответы проверок ссылок

1. url-check-tasks --campaign ID покажет проверки от новых к старым.
2. Для нужной записи выполни url-check-task --campaign ID --task ID.
3. Различай in_progress, clean, has_problems и no_data.
4. При has_problems покажи группу, тип, URL, объявление и сообщение; отдельно назови число приостановленных и возобновлённых объектов.

Проблема может иметь тип redirect, error, exception, format, metrika, time, rules, numerals или title_over_54, но поле не является закрытым перечислением — допускай новые значения. Полный JSON находится в cache/latest-url-check-task.json. API не возвращает публичную ссылку на отчёт; взять её можно только в интерфейсе.