Білінг API і звітність

1) Навіщо власний білінг для API

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

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

Producers (API-шлюз, сервіси) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Revoicing/Taxes porting 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-конверсія: курс на дату інвойсу (ЄСВ/провайдер), зберігайте джерело курсу.
Документи: інвойс, 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↔invoysy → розбіжності в звітності.

Підсумок

Сильний білінг для API - це подієва архітектура метерингу, чіткий прайс-бук, сувора ідемпотентність, коректний інвойсинг з податками/FX і прозора звітність. Зв'яжіть usage з виручкою, дайте клієнту зрозумілі деталі і автоматизуйте весь шлях - від події до інвойсу і MRR-дашборду. Це забезпечить передбачувані доходи, менше диспутів і керовану економіку продукту.