Facturación de API e informes

1) Por qué su propia facturación para la API

Monetización transparente: relación usage → ingresos.
Escalabilidad y control: cuotas, sobrecarga, préstamos, buffet de precios según los planes.
Exactitud financiera: impuestos/IVA, multivalencia, actos y documentos de cierre.
Confianza del cliente: informes de uso detallados, webhooks, portal de autoservicio.

2) Arquitectura de facturación (de alto nivel)

Producers (API gateway, services) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWWMENTS H → Portal del cliente/Webhooks.

• Metering - recolección y normalización de usage (solicitudes, créditos, volúmenes).
• Clasificación (rating): evalúa el costo del evento según el plan/buk de precios.
• Facturación - agregación por período, prorrateo, impuestos, descuentos, préstamos.
• Pagos - cargos/refundiciones, duting (dunning).
• Los informes son MRR/ARPU/LTV, cohorte churn, costo-a-serve.
• Auditoría - idempotencia, registros inmutables.

3) Entidades e identificadores

Cuenta (tenant), Plan, Entitlements (permisos/cuotas), Usage Event, Invoice, Credit Note, Tax Profile.
Vital: idempotency_key en usage/invoice/payment, source (gateway/batch), version del esquema del evento.

4) Evento de consumo (usage): esquema de referencia

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
}

Reglas: sólo se agregan eventos; ediciones - a través de eventos de ajuste correctivos con referencia a 'event _ id'.

5) Almacenamiento y capa de agregaciones

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 (análisis)

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

5. 3 Ejemplo de agregación SQL usage → líneas facturadas

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) Buk de precios y rating (evaluación)

Apoye los modelos: flat, tiered, volume, bundled credits, pay-as-you-go, así como 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) Facturación: generación de cuentas

1. Cutoff del período (por la localización de la cuenta).

2. Prorratear en el plan ap/down-grade (por días).

3. Clasificación usage + fijación invoice lines.

4. Impuestos (VAT/GST) sobre la ubicación del cliente y el lugar de prestación del servicio.

5. Créditos/descuentos/cupones.

6. Firma y publicación, envío de pago (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) Impuestos y facturación múltiple

IVA/VAT/GST: almacenar el perfil Tax (país, VAT-ID válido, B2B/B2C).
Tipos impositivos por fecha (versión), reverse charge para B2B en la UE.
Conversión FX: curso en la fecha de la factura (URE/proveedor), almacena la fuente del curso.
Documentos: factura, nota de crédito, nota de débito - con números y series.

9) Pagos, deuting y dispouts

PSP (Stripe/Braintree/Adyen): pagos tokenized, retiros en caso de rechazo, dunning (1-3-7 días).
Disputes/chargebacks: fijación de estados, ligamento con factura, interacción de línea de tiempo.
Refundidos: parciales/completos, relacionados con 'payment _ id' y 'invoice _ id'.
Señales de Frod: anomalías geo/ASN, ráfagas de usage, diferentes tarjetas - banderas en la facturación.

10) Préstamos, descuentos, créditos SLA

Créditos promocionales (billetera), créditos de servicio por infracción de SLA (autocartera en el período siguiente).
Cupones: fix/porcentaje, plazo mínimo, límites de plan/endpoints.
Transparencia: en el portal, muestre el balance de préstamos y el historial de cargos.

11) Idempotencia y ajustes

Todas las operaciones de escritura a través de Idempotency-Key.
Los ajustes son sólo a través de los eventos adjustments (positivos/negativos), sin editar el original.
Reconciliation: conciliación diaria de usage ↔ rated_lines ↔ invoices ↔ PSP.

12) Seguridad y cumplimiento

HMAC/JWT firma de eventos de uso desde la puerta de enlace.
mTLS para ingest, claves individuales en el entorno (prod/stage).
Minimización PII (no almacenar PAN/correo innecesariamente), DSAR/Legal Hold.
El registro de auditoría es inmutable (append-only) para las transacciones financieras.

13) API del portal de facturación (fragmentos 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"

Los encabezados en las respuestas de la API principal son: 'X-Quota-Remaining', 'X-RateLimit-Remaining', 'X-Usage-Period'.

14) Webhooks y eventos de facturación

Eventos: 'invoice. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Requisitos: firma de webhooks, repetición con backoff, deduplicación por 'delivery _ id'.

15) Informes y métricas del negocio

• MRR/ARR (segmentación por planes/geo), ARPU, LTV/CAC, Churn (logo/rentas), Net Revenue Retention (NRR).
• Usage → Revenue: mapas de conversión de «cuellos de botella» (donde descansan las cuotas).
• Costo-a-Servicio: costo de infraestructura/solicitud → margen por planes.

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 autoservicio

Registros, planes, llaves, gráficos de uso, facturas (PDF/JSON), webhooks.
Upgrade/downgrade, previsualización de la cuenta (pro-forma), gestión de métodos de pago.
Notificaciones: «cuota <10%», «sobremesa incluida», «factura facturada/pagada».

17) Pruebas y entornos

Sandbox de facturación: PSP ficticios, tasas de prueba de impuestos.
Pruebas de contrato de eventos de uso (diagrama/campos obligatorios).
Replay prod samples en stag, pruebas de regresión de haya de precio.
Backfill es seguro: sólo a través de batch-ingest con idempotencia.

18) FinOps y economía de los aranceles

Contar el margen por endpoints/planes: revenue − costa-to-serve.
Destaque las operaciones «caras» en préstamos y limite en low-tiers.
Monitor query-cost en Observabilidad y asocie con facturación.

19) Lista de comprobación de inicio

• Los esquemas 'usage _ event '/' adjustment '/' invoice _ line' están fijos y versionados.
• El buje de precios está probado (flat/tiered/volume), el prorate/overage es correcto.
• Idempotencia ingestion y webhooks, registro de auditoría append-only.
• Los impuestos/IVA/FX son correctos, los perfiles de los clientes están llenos.
• Portal: usage, facturas, créditos, webhooks; Integración PSP y dunning.
• Informes DWH (MRR/ARPU/LTV/Churn/NRR), reconciliación diaria.
• Se han documentado políticas de préstamos SLA y Disputs.

20) Errores frecuentes y anti-patrones

No hay idempotencia → toma usage/doble deducible.
El precio de «solicitud» sin créditos para endpoints pesados → márgenes negativos.
Los impuestos «según el lugar de la empresa» y no el cliente → errores de cumplimiento.
Facturas sin detalles → disputas con clientes.
No hay reconciliación entre usage↔PSP↔invoysy → discrepancias en los informes.

Una fuerte facturación para API es una arquitectura de metering de eventos, un buk de precios claro, idempotencia estricta, facturación de impuestos/FX correcta e informes transparentes. Vincule el uso con los ingresos, dé al cliente detalles claros y automatice todo el camino, desde el evento hasta la factura y el dashboard MRR. Esto proporcionará ingresos predecibles, menos dispouts y una economía de producto manejable.