ZoomKit
Работай через единый POSIX-сценарий scripts/zoomkit.sh. Определи каталог навыка по пути загруженного SKILL.md и запускай команды из него:
shsh scripts/zoomkit.sh <команда> [параметры]
Зависимости: curl для всех сетевых команд; jq для проверки тел запросов и краткого разбора JSON. Команды чтения без jq всё равно сохраняют полный ответ в файл.
Первое знакомство и подключение
Если пользователь ещё не зарегистрирован, не знает, нужен ли ему ZoomKit, или у него нет ключа, сначала прочитай GETTING_STARTED.md и выполни:
shsh scripts/zoomkit.sh getting-started
Команда работает без ключа и сети. Объясни пользователю простыми словами:
- Какие ручные задачи ZoomKit снимает.
- Сколько стоят подходящие ему возможности.
- Почему сервис может быть выгоден именно при его объёме работы, без обещаний гарантированной экономии.
- Порядок подключения: регистрация, стартовое пополнение примерно на 500 руб., выпуск ключа, сохранение в
config/.envи проверка.
Цены меняются. Для вопроса о стоимости «сейчас» проверь встроенный блок тарифов на официальной странице https://zoomkit.ru/help; связанный с ним внешний документ используй только если он открывается. Если проверить сеть нельзя, явно назови дату справочного снимка из GETTING_STARTED.md. Не утверждай, что публичный список охватывает все списания. Не обещай бесплатный период, скидку или иную акцию без подтверждения на официальном сайте.
config/.env внутри каталога навыка — штатное постоянное хранилище ключа. Сценарий читает его при каждом запуске, а файл сохраняется между сессиями. Всегда предлагай этот способ для обычной работы; переменная окружения нужна лишь как временное переопределение. Не утверждай, что контейнер удалит файл, что его придётся создавать в каждой сессии или что навык можно использовать только из Claude Code либо локальной оболочки.
Не начинай знакомство с просьбы о ключе и не проси вставлять его в чат. Если пользователь решил подключиться, проведи его по шагам из config/README.md: регистрация или вход → пополнение баланса → выпуск ключа → запись в config/.env → команда token. Для первого знакомства предложи 500 руб. как небольшую стартовую сумму, а не как документированный минимум; напомни проверить итог с добавляемыми при оплате 6%.
Перед запросом данных профиля проверь ключ:
shsh scripts/zoomkit.sh token
Если ключа нет, сценарий завершится до сетевого запроса и покажет пользу сервиса и весь порядок подключения. Не ограничивайся ответом «не могу»: передай пользователю шаги, дождись сохранения ключа в постоянный config/.env, затем повтори token и исходный запрос.
Если сохранённый ключ существует, но token возвращает HTTP 401, не повторяй первичную регистрацию и не предлагай снова пополнить баланс. Попроси войти в существующую учётную запись, выпустить замену недействительному ключу, обновить ZOOMKIT_API_TOKEN в том же config/.env и повторить token. Если ключ временно переопределён одноимённой переменной окружения, её тоже нужно обновить или удалить.
Если пользователь спрашивает только о возможностях выставления или оплаты счёта, ключ не нужен: начни с billing-capabilities и следующего раздела. Настройку ключа предлагай, только если нужно прочитать баланс или существующие счета.
Проверки кабинетов и кампаний
Для отчётов с ожиданием, проверок по нескольким кабинетам, правил ставок, автотаргетинга и проверки ссылок сначала прочитай AUDIT_WORKFLOWS.md. Там отмечено, какие из проверок полные, частичные или недоступные через API.
Если пользователь называет подключённые сущности «проектами» или «аккаунтами», выполни clients: именно «Список проектов/аккаунтов» — официальное название метода /stats/clients. Покажи интеграции и вложенные проекты/аккаунты — рекламные кабинеты, не поправляя терминологию пользователя без необходимости.
Если конкретный кабинет Яндекс.Директа не находится по имени или комментарию, проверь полный сохранённый ответ clients, а не только сокращённую таблицу. Не утверждай, что кабинет не подключён, пока среди результатов yandex.direct есть аккаунты с пустым комментарием и непонятным техническим именем, особенно porg-*. Если пользователь знает, что кабинет существует, дай ручную инструкцию из раздела «Если кабинет не удаётся распознать»: https://zoomkit.ru/yandex/direct → «Клиенты и дневной расход» → заполнить поле «Комментарий» для всех непонятных аккаунтов → повторить clients. Не угадывай соответствие по техническому имени или идентификатору.
Для списка кампаний сначала выполни clients, возьми id вложенного кабинета yandex.direct, затем вызови campaigns --client ID. Не путай этот ClientId с идентификатором интеграции. Используй полученные ID кампаний для bidrules, url-check-settings и других проверок по кампаниям.
API 1.9.0 возвращает список из данных ZoomKit, поэтому учитывай updated_at и показывай hints. Архивные кампании входят в ответ, а can_set_bids показывает пригодность для управления ставками. Мастер кампаний и товарные кампании Яндекс.Директ не передаёт в ZoomKit; недавно созданная ЕПК или другая кампания может появиться после обновления кабинета. Не запускай изменяющий client-update для диагностического запроса без явного разрешения пользователя.
Диагностический запрос не разрешает изменение. В частности, не запускай autotargeting для просьбы «проверь»: эта команда сразу создаёт недостающие правила в подходящих неархивных кампаниях активных кабинетов ключа. Выполняй её только после отдельного явного запроса на исправление и показа пользователю идентификатора ключа Яндекса.
Важное ограничение по счетам
Официальный API 1.9.0 умеет только читать баланс и список уже выставленных счетов. Он не позволяет создать счёт, передать произвольные реквизиты, получить печатную форму или ссылку на оплату.
При запросе на новый счёт или ссылку:
- Объясни ограничение API и дай ссылку
https://zoomkit.ru/profile. - Если ключ уже настроен или пользователь отдельно просит проверить свои счета, выполни
invoices --status wait. - Не подбирай закрытые адреса и не отправляй придуманные поля. Подробности: BILLING.md.
Для проверки возможностей без ключа:
shsh scripts/zoomkit.sh billing-capabilities
Команды чтения
| Команда | Назначение | Параметры |
|---|---|---|
token | Состояние текущего ключа | — |
balance | Баланс, суточный тариф, запас дней | — |
invoices | Уже выставленные счета | --status wait|paid|cancelled, --limit N |
clients | Интеграции и вложенные проекты/аккаунты (рекламные кабинеты) | — |
campaigns | Кампании кабинета Яндекс.Директа по данным ZoomKit | --client ID, необязательно --limit N |
reports | Список отчётов | — |
report | Состояние и результат отчёта | --id ID |
report-wait | Ожидать READY или FAILED, не более 55 секунд за запуск | --id ID, необязательно --interval, --timeout |
bidrules | Правила ставок кампании | --campaign ID |
url-check-settings | Настройки проверки ссылок | --campaign ID |
url-check-tasks | Последние проверки ссылок | --campaign ID |
url-check-task | Отчёт одной проверки | --campaign ID --task ID |
Полный ответ сохраняется в cache/latest-<команда>.json; исключение — report-wait, который по умолчанию пишет cache/report-<ID>.json, чтобы параллельные ожидания не смешивались. Стандартный вывод остаётся коротким. --output ПУТЬ меняет файл назначения. --raw печатает весь JSON и подходит только для небольших ответов.
Команды изменения
| Команда | Метод | Обязательные параметры |
|---|---|---|
report-create | Создать отчёт | --body ФАЙЛ --confirm |
report-delete | Удалить отчёт | --id ID --confirm |
client-update | Поставить обновление кабинета в очередь | --client ID --confirm |
autotargeting | Добавить недостающие правила автотаргетинга в подходящих неархивных кампаниях активных кабинетов ключа | --token-id ID --confirm |
bidrule-common-update | Изменить общее правило ставок | --campaign ID --body ФАЙЛ --confirm |
bidrule-keywords-create | Создать правило для фраз | --campaign ID --body ФАЙЛ --confirm |
bidrule-keywords-update | Изменить правило для фраз | --campaign ID --bidrule ID --body ФАЙЛ --confirm |
bidrule-keywords-delete | Удалить правило для фраз | --campaign ID --bidrule ID --confirm |
url-check-settings-update | Изменить переключатели проверки ссылок | --campaign ID --body ФАЙЛ --confirm |
Перед изменением покажи пользователю целевые идентификаторы и содержимое тела запроса. Передавай --confirm только после явного запроса на это изменение. Для предварительной проверки команды используй --dry-run: сеть и ключ не требуются.
Заготовки тел запросов лежат в assets/. Скопируй нужный файл во временный или рабочий каталог и измени копию; не правь исходную заготовку. Для защиты товара от 404 и исчезновения контрольной строки можно взять assets/url-check-product-protection.example.json, но саму строку задай вручную по settings_url. Заготовка явно задаёт весь набор условий автоприостановки: перед подтверждением сравни её с текущими настройками и покажи пользователю, какие условия будут включены и выключены.
Для команд изменения с --body сценарий не отправляет тело, пока jq не подтвердит, что файл содержит корректный JSON-объект.
Справочники
- Польза, тарифы и сценарий первого знакомства: GETTING_STARTED.md.
- Семь проверочных сценариев и границы API: AUDIT_WORKFLOWS.md.
- Все пути, коды ответов и ограничения: API_REFERENCE.md.
- Счета, баланс и способы оплаты: BILLING.md.
- Создание и получение отчётов: REPORTS.md.
- Правила ставок и проверки ссылок: YANDEX_DIRECT.md.
