Биллинг
Использование, кошелёк и ежемесячные счета через API; что происходит с организацией при неоплате подписки.
Все чтения требуют scope billing:read.
| Метод | Путь | Ответ |
|---|---|---|
GET | /billing/usage | Использование квот за период |
GET | /billing/wallet | Баланс кошелька и транзакции |
GET | /billing/invoices?limit= | Счета, новые первыми (limit 1–100, по умолчанию 24) |
GET | /billing/invoices/{id} | Счёт в JSON |
GET | /billing/invoices/{id}.pdf | Счёт в PDF |
Счета
Один счёт в месяц на организацию (period = YYYY-MM): использованный объём,
блоки превышения, движения кошелька. Подписка выставляется платёжным
провайдером и здесь только упоминается.
Строки (lines[].kind): included (использованный объём, сумма 0), overage
(завершённые блоки × цена блока — ровно то, что списано с кошелька), wallet_debit
(прочие списания), wallet_credit (возвраты; пополнения — с суммой 0),
subscription_ref (ссылка на подписку провайдера).
Статусы: draft (период открыт), paid (период закрыт, кошелёк покрыл
превышение), issued (часть превышения не собрана), void. Счёт за закрытый месяц
создаёт ежедневная задача планировщика; повторный запуск обновляет только draft.
POST /billing/invoices/generate?period=&organization_id= — операция оператора
платформы (нужен x-platform-admin-token).
Неоплата (dunning)
| Состояние | Эффект |
|---|---|
active | Обычная работа |
past_due | Ничего не отключается; владельцам — одно письмо и уведомление, баннер в консоли |
suspended | Организация работает как Free: поиск в лимитах Free, платные функции — 402 FEATURE_NOT_AVAILABLE с details.reason = "past_due" |
past_due → suspended через BILLING_GRACE_DAYS (по умолчанию 7 дней).
Успешная оплата сразу возвращает active и тариф. Сбои платежей сообщают Stripe,
Lemon Squeezy, Polar и Dodo Payments; Creem, Robokassa и Tochka — пока нет.