Public API — подключение и проверка

REST API для интеграции с ImpactBot из вашей системы: клиенты, метки, воронки, рассылки, таблицы и исходящие вебхуки.

Базовый адрес — `https://api.impactbot.ru/public/v1`. Полное описание маршрутов с примерами тел и ответов живёт на странице /api-docs в продукте; она собирается из одного описания с этой статьёй, и контрактный тест сверяет его с деревом маршрутов — маршрут, которого нет в коде, туда не попадёт.

Что нужно заранее

Проект ImpactBot и тариф, в котором доступ к API включён. Иначе любой запрос отвечает `402` с кодом `FEATURE_NOT_AVAILABLE`.
Роль администратор в проекте: только она может выпустить и отозвать ключ.
Ваш сервер, который будет ходить в API. Ключ — серверный секрет; в браузер и в мобильное приложение его класть нельзя.

Права и доступы

Ключ выпускается в разделе Проект → Настройки, блок API-ключа. У ключа есть scopes — они и определяют, что ключом можно сделать:

`clients:read`, `clients:write` — чтение карточек и работа с метками;
`messages:send` — отправка сообщения клиенту;
`flows:read`, `flows:write` — список воронок и их запуск;
`broadcasts:write` — создание рассылок;
`tables:read`, `tables:write` — таблицы и строки;
`admin` — включает всё перечисленное.

Права наследуются: `flows:write` открывает и `flows:read`, `tables:write` — и `tables:read`. Если ключу не хватает права, ответ `403` с кодом `INSUFFICIENT_SCOPE`, и в теле указано поле `required` с нужным scope — угадывать не придётся.

Проект в запросах не передаётся ни параметром, ни в теле: он определяется по самому ключу. У ключа может быть срок жизни; после его истечения ответ `401` с кодом `API_KEY_EXPIRED` и датой в поле `expiredAt`.

Подключение и вебхук

Ключ передаётся заголовком:

X-API-Key: <ваш ключ>

Форма `Authorization: Bearer <тот же ключ>` тоже принимается. Отдельного эндпоинта обмена логина на токен нет — JWT для публичного API не выдаётся.

Небезопасные методы принимают заголовок Idempotency-Key (произвольная строка до 255 символов, UUID необязателен). Повтор в течение 24 часов с тем же ключом, путём и телом отдаёт сохранённый ответ и помечает его заголовком `Idempotency-Replayed`. Тот же ключ с другим телом — `409` `IDEMPOTENCY_KEY_REUSED`. Ответы с ошибкой не сохраняются, поэтому повторить неудавшийся запрос можно тем же ключом.

Исходящие вебхуки регистрируются вручную — сами они не появятся: `POST /webhooks` со scope `admin` и телом `{ "url": "...", "events": ["message.received"] }`. Адрес обязан быть `https`, без логина и пароля в URL и не должен указывать во внутреннюю сеть, иначе `400`. Список — `GET /webhooks`, удаление — `DELETE /webhooks/:id`.

Лимит — 100 запросов в минуту на ключ. В ответах есть `X-RateLimit-Limit`, `X-RateLimit-Remaining` и `X-RateLimit-Reset`, при превышении — `429` с `Retry-After`.

Проверка

Самый дешёвый пробный запрос — список клиентов; он ничего не меняет:

curl -H "X-API-Key: <ваш ключ>" \
  https://api.impactbot.ru/public/v1/clients?limit=1

Ожидаемый ответ — `200` и тело вида `{ "success": true, "data": { "clients": [...], "pagination": {...} } }`. Ответы по таблицам приходят без обёртки `success/data` — это отдельная форма, и её стоит учесть в разборе.

Дальше проверьте право на запись тем эндпоинтом, который вам нужен, с заголовком `Idempotency-Key`: повторный вызов с тем же ключом обязан вернуть тот же ответ, а не создать вторую сущность.

Частые ошибки

`401` `API_KEY_EXPIRED`. Срок ключа вышел — выпустите новый; дата истечения есть в теле ответа.
`403` `INSUFFICIENT_SCOPE`. Ключ выпущен без нужного права. Scope добавляется только выпуском нового ключа.
`402` `FEATURE_NOT_AVAILABLE`. Тариф проекта не включает доступ к API.
`501` `PLATFORM_NOT_SUPPORTED`. Прямая отправка сообщения работает только для Telegram; для остальных площадок запускайте воронку.
`409` `IDEMPOTENCY_IN_PROGRESS`. Первый запрос с этим ключом ещё выполняется — повторите через секунду.
`400` `FILTER_TOO_WIDE` или `UNKNOWN_FILTER_FIELD`. В запросе строк больше пяти `filter[…]` либо поля нет в таблице.
`400` `UNKNOWN_FIELD`. В теле строки поле, которого в таблице нет: неизвестные колонки не создаются молча.
Запрос с `project_id`. Такого параметра нет ни на одном маршруте — проект берётся из ключа.