# Zoomkit

> Набор утилит и инструкций для автоматизации Яндекс.Директа через ZoomKit: проверка рекламных ссылок и страниц на ошибки, настройка зануления автотаргетинга на поиске и управление ставками с пересчётом каждые 30 минут. Используй, когда нужно настроить или использовать ZoomKit для работы с Яндекс.Директом, получить список подключённых проектов или аккаунтов, отчёты и состояние кабинетов или кампаний, либо узнать тарифы, баланс и счета сервиса.

- Skill: `artwist-polyakov/zoomkit` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add artwist-polyakov/zoomkit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/artwist-polyakov/zoomkit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: artwist-polyakov (https://skillmd.com/u/artwist-polyakov)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/artwist-polyakov/zoomkit

---


# ZoomKit

Работай через единый POSIX-сценарий `scripts/zoomkit.sh`. Определи каталог навыка по пути загруженного `SKILL.md` и запускай команды из него:

```sh
sh scripts/zoomkit.sh <команда> [параметры]
```

Зависимости: `curl` для всех сетевых команд; `jq` для проверки тел запросов и краткого разбора JSON. Команды чтения без `jq` всё равно сохраняют полный ответ в файл.

## Первое знакомство и подключение

Если пользователь ещё не зарегистрирован, не знает, нужен ли ему ZoomKit, или у него нет ключа, сначала прочитай [GETTING_STARTED.md](references/GETTING_STARTED.md) и выполни:

```sh
sh scripts/zoomkit.sh getting-started
```

Команда работает без ключа и сети. Объясни пользователю простыми словами:

1. Какие ручные задачи ZoomKit снимает.
2. Сколько стоят подходящие ему возможности.
3. Почему сервис может быть выгоден именно при его объёме работы, без обещаний гарантированной экономии.
4. Порядок подключения: регистрация, стартовое пополнение примерно на 500 руб., выпуск ключа, сохранение в `config/.env` и проверка.

Цены меняются. Для вопроса о стоимости «сейчас» проверь встроенный блок тарифов на официальной странице `https://zoomkit.ru/help`; связанный с ним внешний документ используй только если он открывается. Если проверить сеть нельзя, явно назови дату справочного снимка из `GETTING_STARTED.md`. Не утверждай, что публичный список охватывает все списания. Не обещай бесплатный период, скидку или иную акцию без подтверждения на официальном сайте.

`config/.env` внутри каталога навыка — штатное постоянное хранилище ключа. Сценарий читает его при каждом запуске, а файл сохраняется между сессиями. Всегда предлагай этот способ для обычной работы; переменная окружения нужна лишь как временное переопределение. Не утверждай, что контейнер удалит файл, что его придётся создавать в каждой сессии или что навык можно использовать только из Claude Code либо локальной оболочки.

Не начинай знакомство с просьбы о ключе и не проси вставлять его в чат. Если пользователь решил подключиться, проведи его по шагам из [config/README.md](config/README.md): регистрация или вход → пополнение баланса → выпуск ключа → запись в `config/.env` → команда `token`. Для первого знакомства предложи 500 руб. как небольшую стартовую сумму, а не как документированный минимум; напомни проверить итог с добавляемыми при оплате 6%.

Перед запросом данных профиля проверь ключ:

```sh
sh scripts/zoomkit.sh token
```

Если ключа нет, сценарий завершится до сетевого запроса и покажет пользу сервиса и весь порядок подключения. Не ограничивайся ответом «не могу»: передай пользователю шаги, дождись сохранения ключа в постоянный `config/.env`, затем повтори `token` и исходный запрос.

Если сохранённый ключ существует, но `token` возвращает `HTTP 401`, не повторяй первичную регистрацию и не предлагай снова пополнить баланс. Попроси войти в существующую учётную запись, выпустить замену недействительному ключу, обновить `ZOOMKIT_API_TOKEN` в том же `config/.env` и повторить `token`. Если ключ временно переопределён одноимённой переменной окружения, её тоже нужно обновить или удалить.

Если пользователь спрашивает только о возможностях выставления или оплаты счёта, ключ не нужен: начни с `billing-capabilities` и следующего раздела. Настройку ключа предлагай, только если нужно прочитать баланс или существующие счета.

## Проверки кабинетов и кампаний

Для отчётов с ожиданием, проверок по нескольким кабинетам, правил ставок, автотаргетинга и проверки ссылок сначала прочитай [AUDIT_WORKFLOWS.md](references/AUDIT_WORKFLOWS.md). Там отмечено, какие из проверок полные, частичные или недоступные через API.

Если пользователь называет подключённые сущности «проектами» или «аккаунтами», выполни `clients`: именно «Список проектов/аккаунтов» — официальное название метода `/stats/clients`. Покажи интеграции и вложенные проекты/аккаунты — рекламные кабинеты, не поправляя терминологию пользователя без необходимости.

Если конкретный кабинет Яндекс.Директа не находится по имени или комментарию, проверь полный сохранённый ответ `clients`, а не только сокращённую таблицу. Не утверждай, что кабинет не подключён, пока среди результатов `yandex.direct` есть аккаунты с пустым комментарием и непонятным техническим именем, особенно `porg-*`. Если пользователь знает, что кабинет существует, дай ручную инструкцию из раздела [«Если кабинет не удаётся распознать»](references/YANDEX_DIRECT.md#если-кабинет-не-удаётся-распознать): `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 умеет только читать баланс и список уже выставленных счетов. Он не позволяет создать счёт, передать произвольные реквизиты, получить печатную форму или ссылку на оплату.

При запросе на новый счёт или ссылку:

1. Объясни ограничение API и дай ссылку `https://zoomkit.ru/profile`.
2. Если ключ уже настроен или пользователь отдельно просит проверить свои счета, выполни `invoices --status wait`.
3. Не подбирай закрытые адреса и не отправляй придуманные поля. Подробности: [BILLING.md](references/BILLING.md).

Для проверки возможностей без ключа:

```sh
sh 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](references/GETTING_STARTED.md).
- Семь проверочных сценариев и границы API: [AUDIT_WORKFLOWS.md](references/AUDIT_WORKFLOWS.md).
- Все пути, коды ответов и ограничения: [API_REFERENCE.md](references/API_REFERENCE.md).
- Счета, баланс и способы оплаты: [BILLING.md](references/BILLING.md).
- Создание и получение отчётов: [REPORTS.md](references/REPORTS.md).
- Правила ставок и проверки ссылок: [YANDEX_DIRECT.md](references/YANDEX_DIRECT.md).