Документация BillBill

Эта документация описывает логику серверного API и сценарии админ-панели платформы BillBill: продукты и планы, подписки, счета, платежи, метрики и интеграцию через Merchant API и исходящие вебхуки.

Интерфейс user-portal здесь не рассматривается. Для встроенного чекаута на стороне вашего продукта используйте отдельные материалы или User API (вне scope этой версии доки).

Для кого

• администраторы мерчанта, настраивающие каталог и биллинг в облаке;
• разработчики бэкенда SaaS или интернет-магазина, подключающие BillBill по API;
• архитекторы, оценивающие модель подписок, usage и процессинг оплат.

Основные возможности

• Каталог: продукты и тарифные планы (основной план, рекуррентные и разовые аддоны).
• Подписки: периоды, пробный период, смена плана, отложенные изменения (pending update).
• Счета и налоги: расчёт строк, скидок, промо-кредитов, НДС (taxPercentage в внутреннем формате).
• Платежи: несколько платёжных шлюзов, создание платежа по счёту, обработка вебхуков шлюза.
• Метрики: лимиты по потреблению, поминутная (usage) тарификация, рекуррентные начисления по метрике; события с внешних систем.
• Документы: HTML-шаблоны счетов (EJS) и PDF (в т.ч. через Gotenberg на стороне API).
• Скрипты: пользовательские JS-сценарии (например, постобработка после приёма события метрики).

Как читать дальше

1. Обзор и сущности — что видно в админке и как сущности связаны.
2. Планы и аддоны — типы планов и периодичность.
3. Биллинг и счета — как собирается сумма счёта.
4. Процессинг оплат — от счёта до шлюза и webhook.
5. Руководства — пошагово в облаке и админке.
6. Рецепты — типовые платежные схемы.
7. Интеграция — ключи, REST, npm-клиент, вебхуки.

Ядро API в репозитории реализовано в Go-модуле с именем unibee; в тексте для пользователей везде используется название продукта BillBill.