Facturation API et reporting

1) Pourquoi votre propre facturation pour l'API

Monétisation transparente : lien d'utilisation → recettes.
L'escalade et le contrôle : quotas, overage, prêts, prix hook par plan.
Précision financière : taxes/TVA, multivalence, actes et documents de clôture.
Confiance des clients : rapports d'utilisation détaillés, webhooks, portail libre-service.

2) Architecture de facturation (haut niveau)

Producteurs (passerelle API, services) → Utilisation Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Portail client/Webhooks.

• Metering - collecte et normalisation de l'utilisation (demandes, prêts, volumes).
• Notation (rating) - estimation du coût de l'événement par prix hêtre/plan.
• La facturation est une agrégation pour la période, la provision, les impôts, les réductions, les prêts.
• Paiements - prélèvements/rappels, deutsching (dunning).
• Rapports - RMR/ARPU/LTV, churn de cohorte, cost-to-serve.
• L'audit est l'idempotence, les journaux immuables.

3) Entités et identifiants

Compte (tenant), Plan, Entitlements (permis/quotas), Événement d'utilisation, Invoice, Note de crédit, Profil d'impôt.
Vital : idempotency_key sur utilisation/invoice/payment, source (gateway/batch), version du schéma de l'événement.

4) Événement de consommation (utilisation) : schéma de référence

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
}

Règles : les événements ne sont ajoutés que ; modifications - via des événements correctifs d'ajustement avec une référence à 'event _ id'.

5) Stockage et couche d'agrégation

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

Факты: `f_usage`, `f_billing`, `f_payments`; dimensions : 'd _ tenant', 'd _ plan', 'd _ endpoint', 'd _ région', 'd _ date'.

5. 3 Exemple d'agrégation SQL d'utilisation → de lignes billiées

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) Prix et rating (évaluation)

Soutenez les modèles : flat, tiered, volume, bundled credits, pay-as-you-go et aussi 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) Facturation : création de comptes

1. Cutoff de la période (par compte localisé).

2. Prorate à l'ap/down-grade du plan (par jour).

3. Notation utilisation + fixation invoice lines.

4. Taxes (TVA/TPS) selon l'emplacement du client et le lieu de prestation des services.

5. Crédits/rabais/coupons.

6. Signature et publication, envoi pour paiement (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) Taxes et multi-devises

TVA/TVA/TPS : conserver le profil fiscal (pays validé par TVA-ID, B2B/B2C).
Taux d'imposition par date (s), reverse charge pour B2B dans l'UE.
Conversion FX : taux à la date de la facture (URE/fournisseur), conserver la source du cours.
Documents : facture, note de crédit, note de débit - avec numéros et séries.

9) Les paiements, le deut et les disputes

PSP (Stripe/Braintree/Adyen) : paiements tokenized, retraits en cas de refus, dunning (1-3-7 jours).
Disputes/chargebacks : fixation des statuts, lien avec la facture, interaction temporelle.
Refunds : partiels/complets, associés à 'payment _ id' et 'invoice _ id'.
Signaux frods : anomalies géo/ASN, surtensions d'utilisation, différentes cartes - drapeaux dans la facturation.

10) Crédits, rabais, crédits SLA

Crédits promotionnels (portefeuille), crédits de service pour violation de la SLA (auto-achat dans la période de suivi).
Coupons : fix/pourcentage, durée minimale, limites de plan/endpoints.
Transparence : dans le portail, montrez le solde des crédits et l'historique des débits.

11) Idempotence et ajustements

Toutes les opérations d'écriture via Idempotency-Key.
Les réglages ne sont effectués qu'à travers les événements adjustments (positifs/négatifs), sans modification de l'original.
Reconnaissance : rapprochement quotidien des usages ↔ rated_lines ↔ invoices ↔ PSP.

12) Sécurité et conformité

HMAC/JWT signature des événements d'utilisation de la passerelle.
mTLS pour ingest, clés individuelles par environnement (prod/stage).
PII-minimisation (ne pas stocker le PAN/courrier inutilement), DSAR/Legal Hold.
Audit-journal immuable (append-only) pour les transactions financières.

13) API du portail de facturation (fragments d'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"

Les en-têtes dans les réponses de l'API principale sont : 'X-Quota-Remaining', 'X-RateLimit-Remaining', 'X-Usage-Period'.

14) Webhooks et événements de facturation

Événements : 'invoice. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Exigences : Signature de webhooks, répétition avec backoff, déduplication par "delivery _ id'.

15) Rapports et métriques d'entreprise

• MRR/ARR (segmentation par plans/géo), ARPU, LTV/CAC, Churn (faux/revenu), Net Revenue Retentation (NRR).
• Utilisation → Revenu : cartes de conversion des « goulets d'étranglement » (où ils reposent sur des quotas).
• Cost-to-Serve : coût de l'infrastructure/demande → marge par plan.

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 : portail libre-service

Inscription, plans, clés, graphiques d'utilisation, factures (PDF/JSON), webhooks.
Mise à niveau/downgrade, anticipation de compte (pro-forma), gestion des méthodes de paiement.
Notifications : « quota <10 % », « dépassement inclus », « facturation facturée/payée ».

17) Test et environnement

Sandbox de facturation : PSP fictifs, taux d'imposition de test.
Tests contractuels d'utilisation d'événements (schéma/champs obligatoires).
Replay-samples dans la stag, tests de régression de prix de hêtre.
Backfill est sûr : seulement via batch-ingest avec idempotence.

18) FinOps et l'économie tarifaire

Comptez les marges sur les endpoints/plans : revenue − cost-to-serve.
Attribuez des opérations « chères » à des crédits et limitez-les à des opérations peu coûteuses.
Surveillez query-cost dans Observability et associez-le à la facturation.

19) Chèque de lancement

• Les schémas 'usage _ event '/' adjustment '/' invoice _ line' sont fixes et versionnés.
• Price-hook testé (flat/tiered/volume), valorate/overage correct.
• Idempotentialité de l'ingestion et des webhooks, audit-log append-only.
• Les taxes/TVA/FX sont correctes, les profils clients sont remplis.
• Portail : utilisation, factures, prêts, webhooks ; Intégration PSP et dunning.
• Rapports DWH (MRR/ARPU/LTV/Churn/NRR), reconnaissance quotidienne.
• Les politiques de crédit SLA et les disputes sont documentées.

20) Erreurs fréquentes et anti-modèles

Il n'y a pas d'idempotence → prise d'usage/double prélèvement.
Le prix « demande » sans crédit pour les endpoints lourds → une marge négative.
Les impôts « sur le lieu de l'entreprise » et non le client → des erreurs de conformité.
Les factures sans détails → les litiges avec les clients.
Il n'y a pas de reconciliation entre les usage↔PSP↔invoysy → les différences de déclaration.

Résultat

La facturation forte pour l'API est une architecture de métallisation d'événements, un prix clair, une idempotence stricte, une facturation correcte avec taxes/FX et des rapports transparents. Liez l'utilisation aux recettes, donnez au client des détails compréhensibles et automatisez tout le chemin - de l'événement à la facture et au dashboard MRR. Cela garantira des revenus prévisibles, moins de disputes et une économie de produit gérée.