Overview

BILLZ 2.0 Public API 2026.08

Публичный REST API BILLZ 2.0 для интеграций (eCommerce, маркетплейсы, BI, боты). ## Аутентификация

Создайте ключ интеграции в UI: Настройки → Настройки компании → Ключи интеграции.
POST /v1/auth/login с телом {"secret_token": "<ключ>"} → access_token + refresh_token.
Все остальные запросы: заголовок Authorization: Bearer <access_token>.
По истечении access-токена — POST /v2/auth/refresh с refresh_token. Только этому методу нужен заголовок platform-id со значением 7d4a4c38-dd84-4902-b744-0488b80a4c01; остальным методам он не нужен. Повторное использование уже использованного refresh-токена отзывает всю семью сессий. ## Синхронные и асинхронные методы Часть методов (создание продажи, изменение баланса клиента, складские операции) выполняется асинхронно: ответ 200 {"message": "<correlation_id>"} означает, что запрос принят, а не что операция завершена. Чтобы дождаться результата в том же HTTP-ответе, передайте Billz-Response-Channel: HTTP — заголовком или query-параметром ?Billz-Response-Channel=HTTP. Максимальное ожидание — 600 секунд, затем 408 с error.code = TIMEOUT; у экспорта отчётов в Excel ожидание короче — 100 секунд. Какие методы асинхронные — помечено на каждом методе. ## Права доступа Ключ интеграции открывает базовые методы. Чувствительные методы требуют выданных прав (роль ключа + права в разделах), иначе — 403. ## Ограничения

Rate limit на периметре: около 2 запросов в секунду с одного IP, при превышении — 429.
Прямая отдача фото товаров с CDN BILLZ на сторонние сайты запрещена — кэшируйте медиа у себя.
IP/гео-ограничений нет, но эвристический анализатор трафика может заблокировать IP при признаках DDoS или ботового трафика.

BILLZ API changes

https://t.me/billz_api_changes

Information

OpenAPI version: 3.0.3

Authentication

BearerAuth

JWT access token, полученный через POST /v1/auth/login. Срок жизни — 15 дней.

Security scheme type: http

Bearer format: JWT

Overview

BILLZ 2.0 Public API 2026.08

Operations

Authentication

BearerAuth