Часто задаваемые вопросы

Зайдите в кабинет на app.botix.pro/developers, создайте ключ кнопкой «Создать ключ», выберите нужные scopes (например, contacts:read, messages:send) и нажмите «Сгенерировать».

Ключ в формате btx_live_… показывается только один раз — скопируйте его в безопасное хранилище (env-переменные, секрет-менеджер). Восстановить ключ нельзя, можно только отозвать и создать новый.

Публичный API доступен на тарифе «Старт» и выше. На триале — read-only режим (без мутаций) для ознакомления.

API — это сам HTTP-протокол: набор endpoints на https://api.botix.pro/public/v1/*, к которым ваше приложение делает запросы любым HTTP-клиентом (curl, Postman, fetch).

SDK — это обёртка над API на конкретном языке (PHP, Python, Node.js), которая берёт на себя: аутентификацию Bearer, сериализацию JSON, retry на 429/5xx, парсинг ошибок, типизацию ответов. Снаружи делает то же самое, что и API, но кода у вас в 3-5 раз меньше.

Если вы пишете на одном из поддерживаемых языков — берите SDK. Если язык другой или нужен полный контроль над запросом — работайте с API напрямую.

Публичный API доступен на всех тарифах, но с разными лимитами скорости (api_rate_per_minute / api_rate_per_day).

Лимит превышен → 429 RATE_LIMIT_EXCEEDED + заголовки X-RateLimit-Remaining и Retry-After. Подробнее — раздел «Best Practices».

Отдельной изолированной песочницы у BOTIX нет. Вместо неё — 14-дневный триал: создаёте триальный проект на botix.pro, получаете API-ключ и работаете с теми же endpoints https://api.botix.pro/public/v1/*, что и в продакшене.

Важные особенности триала:

• Данные пишутся в production-БД проекта (но привязаны к вашему триал-проекту, не к чужому).
• Доступ read-only: GET-запросы работают, POST/PUT/DELETE возвращают 403 TRIAL_READ_ONLY.
• Лимит 30 запросов/мин и 1 000 запросов/сутки.
• После 14 дней — оплата тарифа или потеря доступа.

Для разработки и отладки этого достаточно. Для нагрузочного тестирования — поднимите платный тариф на месяц и используйте его как pre-prod.

Каждый webhook BOTIX подписан HMAC-SHA256 от raw-тела запроса с секретом, который вы получили при создании подписки в /api/v1/public/v1/webhooks. Подпись приходит в заголовке X-Botix-Signature в формате hex.

Алгоритм проверки:

1. Прочитайте сырое тело запроса (до JSON-парсинга). В PHP — file_get_contents('php://input'), в Node.js — middleware express.raw().
2. Посчитайте hmac_sha256(raw_body, webhook_secret) в hex.
3. Сравните с X-Botix-Signature через constant-time функцию: PHP — hash_equals(), Node.js — crypto.timingSafeEqual(), Python — hmac.compare_digest(). Обычный == уязвим к timing-атакам.

PHP-пример:
CODEBLOCK0

Заголовок Idempotency-Key — стандарт Stripe для защиты от дублей при сетевых сбоях. Если ваш POST /public/v1/messages упал по таймауту — вы не знаете, успел ли BOTIX обработать запрос. Без идемпотентности повторный запрос отправит сообщение дважды.

Как использовать:
CODEBLOCK0

Рекомендация — генерировать UUID v4 на каждую логическую операцию (uniqid() не годится, нужна криптографическая случайность). TTL ключа — 24 часа. В течение этого окна повторный запрос с тем же ключом вернёт сохранённый ответ + заголовок Idempotent-Replayed: 1, без новой отправки. После истечения 24 часов тот же ключ создаст новую операцию, кешированный результат не возвращается.

Поддерживается на всех мутирующих endpoints: /messages, /scenarios/{id}/run, /contacts (создание).

Scopes — это список разрешений ключа. Принцип: минимум необходимого. Если ключ нужен только для чтения контактов — давайте только contacts:read, без :write. Утечка такого ключа = не катастрофа.

Запрос с недостающим scope вернёт 403 INSUFFICIENT_SCOPE с указанием требуемого. Изменить scopes после создания ключа нельзя — отзовите и создайте новый.

Ответ 429 RATE_LIMIT_EXCEEDED приходит с тремя заголовками:

• X-RateLimit-Limit — ваш лимит запросов в минуту
• X-RateLimit-Remaining — сколько осталось до конца окна
• Retry-After — секунд до сброса окна

Правильная стратегия — exponential backoff с jitter. Не повторяйте запрос сразу: получите ещё 429 и попадёте в чёрный список IP. Алгоритм:

1. Получили 429 → подождите max(Retry-After, базовая_задержка) секунд.
2. Каждый следующий ретрай — задержка ×2 + случайный jitter ±20%.
3. Максимум 5 попыток, потом сбрасывайте операцию в очередь или возвращайте ошибку пользователю.

Node.js-пример:
CODEBLOCK0

Public API (api.botix.pro/public/v1/*) — для разработчиков клиента, который пользуется BOTIX. Ключ привязан к одному project_id, работает в рамках лимитов тарифа этого проекта. Доступен всем клиентам по подписке.

Partner API (api.botix.pro/partner/v1/*) — для интеграторов и реселлеров, которые продают BOTIX от своего имени или встраивают платформу в свой SaaS. Один ключ оперирует несколькими project_id сразу (созданными интегратором), есть отдельные endpoints для создания проектов, выставления счетов, выгрузки агрегированной статистики.

Partner API доступен только участникам партнёрской программы — подайте заявку на botix.pro/partners.

White-label интеграция (виджет + кабинет под брендом интегратора) — индивидуальная разработка. Свяжитесь по info@botix.pro, опишите ваш сценарий: где встраивается виджет, нужен ли отдельный субдомен, сколько клиентов планируется. По итогу — коммерческое предложение с разовой суммой за брендирование + ежемесячная подписка на инфраструктуру.

Если вы продаёте BOTIX клиентам и оформляете подписки на свои реквизиты, вы получаете комиссию с каждого активного проекта. Подробные условия, тарифы и форма заявки — на botix.pro/partners.

Внутренний API использовался первой волной интеграторов на ранних этапах BOTIX. С релиза публичного API (v1.0.0) рекомендуется переходить на стабильный контракт https://api.botix.pro/public/v1/*.

Аналоги эндпоинтов и правила совместимости — в документации публичного API и разделе «Версионирование».