Биллинг API и отчетность

1) Зачем собственный биллинг для API

Прозрачная монетизация: связь usage → выручка.
Скалируемость и контроль: квоты, overage, кредиты, прайс-бук по планам.
Финансовая точность: налоги/НДС, мультивалютность, акты и закрывающие документы.
Доверие клиентов: детализированные usage-отчеты, вебхуки, портал самообслуживания.

2) Архитектура биллинга (высокоуровнево)

Producers (API-шлюз, сервисы) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Портал клиента / Webhooks.

• Метеринг — сбор и нормализация usage (запросы, кредиты, объемы).
• Рейтинг (rating) — оценка стоимости события по прайс-буку/плану.
• Инвойсинг — агрегация за период, прорейт, налоги, скидки, кредиты.
• Платежи — списания/рефанды, дейтинг (dunning).
• Отчетность — MRR/ARPU/LTV, когортный churn, cost-to-serve.
• Аудит — идемпотентность, неизменяемые журналы.

3) Сущности и идентификаторы

Account (tenant), Plan, Entitlements (разрешения/квоты), Usage Event, Invoice, Credit Note, Tax Profile.
Жизненно важно: idempotency_key на usage/invoice/payment, source (gateway/batch), version схемы события.

4) Событие потребления (usage): эталонная схема

json
{
"event_id": "use_01HXYZ...",
"idempotency_key": "key_6a2f-2025-11-03T18:02:09Z",
"occurred_at": "2025-11-03T18:02:05Z",
"ingested_at": "2025-11-03T18:02:09Z",
"tenant_id": "t_123",
"api_key_id": "k_456",
"plan_id": "pro-2025",
"endpoint": "POST /v1/reports/run",
"unit": "credit",
"quantity": 5,
"region": "eu-west-1",
"metadata": { "request_id": "r_789", "ip": "203. 0. 113. 5" },
"signature": "hmac_sha256_base64(...)",
"schema_version": 2
}

Правила: события только добавляются; правки — через корректирующие adjustment events со ссылкой на `event_id`.

5) Хранилище и слой агрегаций

5.1 OLTP (Billing DB)

Таблицы: `tenants`, `plans`, `plan_prices`, `entitlements`, `usage_events`, `rated_lines`, `invoices`, `invoice_lines`, `tax_rates`, `credits`, `payments`, `refunds`, `disputes`.

5.2 DWH (аналитика)

Факты: `f_usage`, `f_billing`, `f_payments`; измерения: `d_tenant`, `d_plan`, `d_endpoint`, `d_region`, `d_date`.

5.3 Пример SQL-агрегации usage → billed lines

sql
-- 1) Reduce usage per day by units create materialized view mv_daily_usage as select tenant_id, plan_id, endpoint, date_trunc ('day', occurred_at) d,
unit, sum(quantity) qty from usage_events where occurred_at >=:period_start and occurred_at <:period_end group by 1,2,3,4,5;

-- 2) Price book (tiered) applicable
select u. tenant_id, u. plan_id, u. d, u. unit, u. qty,
p. tier_from, p. tier_to, p. price_per_unit,
least(greatest(u. qty - p. tier_from + 1, 0), p. tier_to - p. tier_from + 1) as billable_units,
price_per_unit least(...) as amount from mv_daily_usage u join plan_prices p on p. plan_id = u. plan_id and p. unit = u. unit and u. qty >= p. tier_from;

6) Прайс-бук и rating (оценка)

Поддержите модели: flat, tiered, volume, bundled credits, pay-as-you-go, а также overage.

yaml plan_id: pro-2025 currency: USD units:
request:
tiers:
- { from: 1, to: 250_000, price_per_1k: 2. 5 }
- { from: 250_001, to: 1_000_000, price_per_1k: 2. 0 }
credit:
flat: { price_per_unit: 0. 001} # 1 credit = $0. 001 overage:
policy: "postpaid"
rounding: "ceil_1k"
minimum_commit: 99 # basic subscription/month

7) Инвойсинг: формирование счетов

1. Cutoff периода (по локали аккаунта).

2. Прорейт при ап/даун-грейде плана (по дням).

3. Рейтинг usage + фиксация invoice lines.

4. Налоги (VAT/GST) по локации клиента и месту оказания услуг.

5. Кредиты/скидки/купоны.

6. Подписание и публикация, отправка на оплату (PSP), вебхуки.

json
{
"line_id": "invln_01",
"type": "usage",
"description": "API requests (first 250k)",
"unit": "request",
"quantity": 250000,
"unit_price": 0. 0025,
"amount": 625. 00,
"currency": "USD",
"tax_rate": "VAT20",
"amount_tax": 125. 00
}

8) Налоги и мультивалютность

НДС/VAT/GST: храните Tax Profile (страна, валидный VAT-ID, B2B/B2C).
Налоговые ставки по дате (версии), reverse charge для B2B в ЕС.
FX-конверсия: курс на дату инвойса (ECB/провайдер), храните источник курса.
Документы: инвойс, credit note, дебет-нота — с номерами и сериями.

9) Оплаты, дейтинг и диспуты

PSP (Stripe/Braintree/Adyen): tokenized платежи, ретраи при отказе, dunning (1-3-7 дней).
Disputes/chargebacks: фиксация статусов, связка с инвойсом, таймлайн взаимодействия.
Refunds: частичные/полные, связаны с `payment_id` и `invoice_id`.
Фрод-сигналы: гео/ASN-аномалии, всплески usage, разные карты — флаги в биллинге.

10) Кредиты, скидки, SLA-кредиты

Промо-кредиты (кошелек), service credits за нарушение SLA (автозачет в след. период).
Купоны: фикс/процент, минимальный срок, ограничения по плану/эндпоинтам.
Прозрачность: в портале показывайте баланс кредитов и историю списаний.

11) Идемпотентность и корректировки

Все write-операции через Idempotency-Key.
Корректировки — только через события adjustments (положительные/отрицательные), без правки оригинала.
Reconciliation: ежедневная сверка usage ↔ rated_lines ↔ invoices ↔ PSP.

12) Безопасность и комплаенс

HMAC/JWT подпись usage-событий от шлюза.
mTLS для ingest, отдельные ключи на среду (prod/stage).
PII-минимизация (не хранить PAN/почту без необходимости), DSAR/Legal Hold.
Аудит-лог неизменяемый (append-only) для финансовых операций.

13) API портала биллинга (фрагменты OpenAPI)

yaml paths:
/v1/billing/usage:
get:
summary: Usage breakdown parameters: [ {name: from, in: query}, {name: to, in: query}, {name: unit, in: query} ]
responses: {"200": {description: OK}}
/v1/billing/invoices:
get: { summary: List invoices }
/v1/billing/invoices/{id}:
get: { summary: Get invoice (PDF/JSON) }
/v1/billing/credits:
get: { summary: Credit wallet balance }
/v1/webhooks/billing:
post:
summary: Billing webhooks description: "invoice. created, invoice. finalized, payment. succeeded, credit. applied"

Заголовки в ответах основного API: `X-Quota-Remaining`, `X-RateLimit-Remaining`, `X-Usage-Period`.

14) Вебхуки и события биллинга

События: `invoice.created`, `invoice.finalized`, `payment.succeeded|failed`, `dunning.retry`, `credit.applied`, `dispute.opened|closed`.
Требования: подпись вебхуков, повтор с backoff, дедупликация по `delivery_id`.

15) Отчетность и метрики бизнеса

• MRR/ARR (сегментация по планам/гео), ARPU, LTV/CAC, Churn (лого/доходный), Net Revenue Retention (NRR).
• Usage → Revenue: карты конверсии «узких мест» (где упираются в квоты).
• Cost-to-Serve: стоимость инфраструктуры/запроса → маржа по планам.

sql
-- MRR by invoice dates select date_trunc ('month', invoice_date) m, sum (recurring_amount) mrr from f_billing group by 1;

-- ARPU select m, sum(total_amount)/nullif(count(distinct tenant_id),0) arpu from f_billing_monthly group by 1;

-- Cohort by month of activation select cohort_month, month_since_start, sum (total_amount) revenue from f_billing_cohorts;

16) DevEx: портал самообслуживания

Регистрация, планы, ключи, usage-графики, инвойсы (PDF/JSON), вебхуки.
Апгрейд/даунгрейд, предпросмотр счета (pro-forma), управление методами оплаты.
Уведомления: «квота <10%», «оверидж включен», «инвойс выставлен/оплачен».

17) Тестирование и окружения

Sandbox биллинга: фиктивные PSP, тестовые ставки налогов.
Contract-тесты usage-событий (схема/обязательные поля).
Replay прод-сэмплов в стаге, регрессионные тесты прайс-бука.
Backfill безопасно: только через batch-ingest с идемпотентностью.

18) ФинОпс и экономика тарифов

Считайте маржу по эндпоинтам/планам: revenue − cost-to-serve.
Выделяйте «дорогие» операции в кредиты и ограничивайте в low-tiers.
Мониторьте query-cost в Observability и связывайте с биллингом.

19) Чек-лист запуска

• Схемы `usage_event`/`adjustment`/`invoice_line` зафиксированы и версионируются.
• Прайс-бук протестирован (flat/tiered/volume), prorate/overage корректны.
• Идемпотентность ingestion и вебхуков, аудит-лог append-only.
• Налоги/НДС/FX корректны, профили клиентов заполнены.
• Портал: usage, инвойсы, кредиты, вебхуки; PSP интеграция и dunning.
• DWH-отчетность (MRR/ARPU/LTV/Churn/NRR), reconciliation ежедневный.
• Политики SLA-кредитов и диспутов задокументированы.

20) Частые ошибки и анти-паттерны

Нет идемпотентности → дубли usage/двойное списание.
Прайс «про запрос» без кредитов для тяжелых эндпоинтов → отрицательная маржа.
Налоги «по месту компании», а не клиента → ошибки комплаенса.
Инвойсы без детализации → споры с клиентами.
Нет reconciliation между usage↔PSP↔инвойсы → расхождения в отчетности.

Итог

Сильный биллинг для API — это событийная архитектура метеринга, четкий прайс-бук, строгая идемпотентность, корректный инвойсинг с налогами/FX и прозрачная отчетность. Свяжите usage с выручкой, дайте клиенту понятные детали и автоматизируйте весь путь — от события до инвойса и MRR-дашборда. Это обеспечит предсказуемые доходы, меньше диспутов и управляемую экономику продукта.