/zoomkit

Подключение ZoomKit API

Если аккаунта ещё нет

Сначала посмотрите краткое описание пользы и справочный снимок тарифов:

sh scripts/zoomkit.sh getting-started

Подробное сравнение возможностей и расходов находится в GETTING_STARTED.md. Актуальные цены перед решением проверьте на https://zoomkit.ru/help.

Где хранится ключ

config/.env в каталоге навыка — основной и штатный способ хранения ключа. Файл автоматически читается при каждом запуске и сохраняется между сессиями, поэтому настраивать его заново не нужно. Он исключён из Git и должен иметь права 600.

Переменная окружения ZOOMKIT_API_TOKEN предназначена для разового переопределения, например в автоматизации. Для постоянной обычной работы используйте config/.env.

Зависимости

Для сетевых запросов нужен curl, для проверки тел запросов и кратких таблиц — jq:

command -v curl
command -v jq

На macOS jq можно установить командой brew install jq, в Debian/Ubuntu — sudo apt-get install jq. Без jq команды чтения сохранят полный JSON в cache/, но изменяющие команды с --body будут остановлены до отправки.

1. Зарегистрируйтесь или войдите

Если аккаунта ещё нет, зарегистрируйтесь: https://zoomkit.ru/register. Если аккаунт уже есть, войдите: https://zoomkit.ru/login.

2. Пополните баланс

Откройте профиль: https://zoomkit.ru/profile и пополните баланс. Для первого запуска можно начать с 500 руб.: при справочном тарифе 52 руб. в сутки за управление ставками одного кабинета этого хватит примерно на девять дней.

500 руб. — рекомендуемый небольшой стартовый платёж, а не заявленная минимальная сумма. Перед подтверждением проверьте сумму к оплате: пункт 4.7 публичной оферты предусматривает добавление 6% на этапе оплаты.

3. Создайте ключ

1. Откройте раздел ключей API: https://zoomkit.ru/profile/api
2. Создайте ключ и сразу сохраните его значение.

Ключ даёт доступ к данным и разрешённым действиям владельца профиля. Не отправляйте его в чат, не добавляйте в репозиторий и не записывайте в журналы команд.

4. Сохраните ключ в постоянный файл

Из каталога навыка выполните:

cp config/.env.example config/.env
chmod 600 config/.env

Замените your_api_token_here:

ZOOMKIT_API_TOKEN="ваш_ключ"
ZOOMKIT_API_BASE_URL="https://zoomkit.ru/api/v1"

Файл config/.env исключён из Git. Он находится в постоянном каталоге навыка, переживает смену сессий и не создаётся заново при каждом обращении. Он разбирается как данные и поддерживает только ZOOMKIT_API_TOKEN и ZOOMKIT_API_BASE_URL; команды из него не выполняются. Не добавляйте комментарии после значения.

Непустая переменная окружения ZOOMKIT_API_TOKEN временно переопределяет значение из файла. Пустая переменная не скрывает сохранённый ключ.

Основной адрес API защищён от незаметной подмены. Для отдельного официального стенда явно передайте ZOOMKIT_ALLOW_CUSTOM_API_BASE=1 в окружении. Незащищённый HTTP допустим только для localhost или 127.0.0.1 и дополнительно требует ZOOMKIT_ALLOW_INSECURE_HTTP=1; настоящий ключ в такой проверке не используйте.

5. Проверьте доступ

sh scripts/zoomkit.sh token

Команда покажет название ключа и срок его действия. Если expires_soon равен true, выпустите новый ключ: предупреждение появляется за 10 дней до окончания срока.

После проверки можно запросить расчёты:

sh scripts/zoomkit.sh balance
sh scripts/zoomkit.sh invoices --status wait

Если команда не работает

• 401 — сохранённый ключ отозван, истёк или скопирован неверно. Войдите в существующую учётную запись, выпустите замену в https://zoomkit.ru/profile/api, обновите ZOOMKIT_API_TOKEN в том же config/.env и повторите token. Если ключ временно переопределён одноимённой переменной окружения, обновите или удалите её. Повторное пополнение не требуется только из-за этой ошибки.
• 403 — у владельца ключа нет доступа к объекту или платной возможности.
• 409 — операция конфликтует с уже выполняющейся задачей или состоянием объекта.
• 429 — превышен предел запросов. Подождите до времени из X-RateLimit-Reset.

Общий предел API — 60 запросов в минуту; у отдельных методов он ниже. Сценарий всегда передаёт Accept: application/json, чтобы ошибки авторизации возвращались как JSON, а не перенаправляли на страницу входа.

Для изменяющих команд установите jq: он проверяет синтаксис и объектный тип JSON до отправки. Команды чтения могут работать без jq, сохраняя полный ответ в cache/.

Официальная спецификация: https://zoomkit.ru/docs/api-v1.yaml