Billing API e relatórios

1) Por que o seu próprio billing para API

Monetização transparente: conexão de usage → receita.
Escalabilidade e controle: quotas, overage, empréstimos, price-book de planos.
Precisão financeira: impostos/IVA, multiplicidade, atos e documentos de encerramento.
Credibilidade do cliente: relatórios usage detalhados, webhooks, portal de autoatendimento.

2) Arquitetura de billing (alto nível)

Produções (API, serviços) → Usage Event Ônibus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Portal do cliente/WWments ebhooks.

• Metering - coleta e normalização de usage (pedidos, créditos, volumes).
• Classificação (rating) - estimativa do valor do evento por price-book/plano.
• Faturamento - agregação para o período, pró-rate, impostos, descontos, empréstimos.
• Pagamentos - débitos/refanda, dating (dunning).
• Os relatórios são MRR/ARPU/LTV, churn cômico, cut-to-serve.
• Auditoria - Idempotidade, revistas imutáveis.

3) Entidades e identificadores

Conta (tenant), Place, Entitlents (permissões/quotas), Usage Event, Invoice, Credit Note, Tax Profile.
É vital: idempotency _ key para usage/invoice/payment, fonte (gateway/batch), versão padrão de evento.

4) Evento de consumo (usage): esquema de referência

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
}

Regras: eventos apenas adicionados; editar - através de adjustment events corretivos, referindo-se a 'event _ id'.

5) Armazenamento e camada de agregações

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 (analista)

Факты: `f_usage`, `f_billing`, `f_payments`; medidas: 'd _ tenant', 'd _ place', 'd _ endpoint', 'd _ region', 'd _ data'.

5. 3 Exemplo de agregação 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) Price-book e rating (avaliação)

Suporte flat, tiered, volume, bundled credits, pay-as-you-go e 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) Faturamento: formação de contas

1. Cutoff do período (pelo local da conta).

2. Prorate em um plano de up/down-grade (por dia).

3. Classificação usage + fixação invoice lines.

4. Impostos (VAT/GST) sobre localização do cliente e local do serviço.

5. Créditos/descontos/cupons.

6. Assinar e publicar, enviar para pagamento (PSP), webhooks.

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) Impostos e multiversão

IVA/VAT/GST: guarde Tax Profile (país valente VAT-ID, B2B/B2C).
Taxas de impostos de data (versão), reverse carga para B2B na UE.
Conversão FX: Curso de Data de Fatura (ESV/Provedor), armazene a origem do curso.
Documentos: fatura, credit note, nota de débito - com números e séries.

9) Pagamento, dating e displays

PSP (Stripe/Braintree/Adyen): pagamentos tocenized, retraí quando recusado, dunning (1-3-7 dias).
Disputes/chargebacks: fixação de estatais, ligação com a fatura, interação timeline.
Refunds: parciais/completos, associados a 'payment _ id' e 'invoice _ id'.
Sinais de frod: anomalias geo/ASN, saltos de usage, mapas diferentes - bandeiras em billing.

10) Empréstimos, descontos, créditos SLA

Créditos promocionais (carteira), prestações de crédito por violação de SLA (Auto-Postagem no Período de Observação).
Cupons: fix/percentual, prazo mínimo, restrições de plano/endpoentes.
Transparência: No portal, mostre o balanço dos créditos e o histórico de cancelamentos.

11) Idempotidade e ajustes

Todas as operações write pelo Idempotency-Key.
Ajustes - somente através de eventos adjustments (positivos/negativos), sem editar o original.
Reconciação: usage rated _ lines diários invoices PSP.

12) Segurança e complacência

HMAC/JWT assinatura de eventos usage do gateway.
mTLS para ingest, chaves individuais para o ambiente (prod/estágio).
PII Minimização (não armazenar PAN/correio sem necessidade), DSAR/Legal Hold.
A auditoria-logos é imutável (append-only) para transações financeiras.

13) API do portal de billing (fragmentos de 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"

As respostas da API principal são 'X-Quota-Remaining', 'X-RateLimit-Remaining', 'X-Usage-Period'.

14) Webhooks e eventos de billing

Eventos, 'invoice. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Requisitos: assinatura de webhooks, repetição de backoff, dedução por 'delivery _ id'.

15) Relatórios e métricas de negócios

• MRR/ARR (segmentação por planos/geo), ARPU, LTV/CAC, Churn, Net Revenue Retenção (NRR).
• Usage → Revenue: mapas de conversão de «estreitos» (onde as quotas são definidas).
• Costa-to-Serve: custo de infraestrutura/pedido → margem de planos.

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: portal de autoatendimento

Registro, planos, chaves, gráficos usage, faturas (PDF/JSON), webhooks.
Upgrade/downgrade, pré-teste de conta (pro-forma), gerenciamento de métodos de pagamento.
As notificações são: «quota <10%», «overidge incluído», «fatura parcelada/paga».

17) Testes e ambientes

Sandbox billing - PSP fictício, taxas de teste de impostos.
Testes de eventos usage (padrão/campos obrigatórios).
Replay de prod-sample na esteira, testes de regressão de price-book.
Backfill é seguro, apenas através do batch-ingest com idumpotência.

18) FinOps e economia tarifária

Considere as margens de endpoentes/planos de revenue - cost-to-serve.
Selecione as transações «caras» em empréstimos e limite em low-tiers.
Monitora o query-cost no Observabilidade e vincule-se ao Billing.

19) Folha de cheque de lançamento

• Os circuitos 'usage _ event '/' adjustment '/' invoice _ line' são registrados e versionados.
• O price-book foi testado (flat/tiered/volume), e o pronate/overage está correto.
• Idempotidade de ingestão e webhooks, auditoria-logs append-only.
• Impostos/IVA/FX corretos, perfis de clientes preenchidos.
• Portal: usage, faturas, créditos, webhooks; Integração PSP e dunning.
• Relatórios DWH (MRR/ARPU/LTV/Churn/NRR), recepção diária.
• As políticas de crédito e dispêndio SLA estão documentadas.

20) Erros frequentes e anti-pattern

Não há idempotidade → duplicação usage/duplo cancelamento.
Price sobre pedido sem crédito para endpoint pesados → margem negativa.
Impostos sobre o local da empresa, não sobre o cliente → erros de complacência.
Faturas sem detalhamento → discussões com clientes.
Não há reposição entre usage↔PSP↔invoysy → divergência de relatório.

Resultado

Um forte billing para a API é uma arquitetura de metering de eventos, um acervo de price claro, idempotidade rigorosa, faturamento correto com impostos/FX e relatórios transparentes. Vincule o usage à receita, dê detalhes compreensíveis ao cliente e automatize todo o caminho, desde o evento até a fatura e MRR-dashbord. Isso fornecerá rendimentos previsíveis, menos dispersos e uma economia controlada do produto.