Обзор интеграции
Интеграция бэкенда мерчанта с BillBill в рамках этой документации строится на:
- REST Merchant API — HTTPS, JSON, ключ в заголовке
Authorization. - Исходящие вебхуки — BillBill вызывает ваш HTTPS endpoint при наступлении событий (подписка, счёт, платёж и др.).
User API (сессии пользователя, пользовательский checkout) здесь не описывается; при необходимости его можно добавить отдельным разделом.
Базовый URL
По умолчанию в официальном JS-клиенте: https://api.billbill.ru. Для кастомного окружения задайте baseUrl в опциях ApiClient.
Аутентификация
- Выпустите ключ в админ-панели мерчанта.
- Передавайте
Authorization: Bearer <ключ>(режим по умолчанию в@wilix/billbill-client-js). - В User-Agent серверных запросов должна быть подстрока
OpenAPI.
Идемпотентность и ретраи
При сетевых сбоях безопасно повторять чтение; для создания сущностей используйте внешние уникальные идентификаторы там, где API их поддерживает (например, externalEventId у метрик, externalPlanId у планов — проверьте актуальную схему в Swagger).
Клиент @wilix/billbill-client-js экспортирует shouldRetryBillBillError для политики повторов (см. исходник retryPolicy.ts).