API Facturare și raportare

1) De ce facturarea proprie pentru API

Monetizare transparentă: legătură de utilizare → venituri.
Scalabilitate și control: cote, suprascrie, împrumuturi, carte de prețuri în funcție de planuri.
Acuratețe financiară: taxe/TVA, multicurrency, acte și documente de închidere.
Increderea clientilor: rapoarte detaliate de utilizare, carti web, portal self-service.

2) Arhitectura de facturare (nivel înalt)

Producătorii (API gateway, servicii) Folosire Event Bus (Kafka/Queue) Contorizare & Evaluare Facturare DB Facturare/Taxe Plăți (PSP) Raportare DWH Portal Client/Webhooks.

• Contorizare - colectarea și normalizarea utilizării (cereri, împrumuturi, volume).
• Rating - estimarea costului evenimentului conform cartii/planului de preturi.
• Facturare - agregare pentru perioada, profit, impozite, reduceri, credite.
• Plăți - write-off/refands, dating (dunning).
• Raportare - MRR/ARPU/LTV, cohortă, cost-to-service.
• Audit - idempotență, jurnale neschimbătoare.

3) Entități și identificatori

Cont (chiriaș), Plan, Drepturi, Eveniment de utilizare, Factură, Notă de credit, Profil fiscal.
Vital: idempotency_key la utilizare/factură/plată, sursă (gateway/lot), versiunea schemei de evenimente.

4) Eveniment de utilizare: schema de referință

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
}

Reguli: evenimentele sunt doar adăugate; editări - prin intermediul evenimentelor de ajustare corectivă cu referire la "event _ id'.

5) Strat de stocare și agregare

5. 1 OLTP (Facturare DB)

Таблицы: 'chiriaşi', 'planuri', 'plan _ preţuri', 'drepturi', 'utilizare _ evenimente', 'rated _ lines', 'facturi', 'factură _ linii', 'tax _ rate', 'credite', 'plăţi', 'rambursări', 'litigii'.

5. 2 DWH (analiză)

Факты: 'f _ usage', 'f _ billing', 'f _ payments'; dimensiuni: 'd _ tenant', 'd _ plan', 'd _ endpoint', 'd _ region', 'd _ date'.

5. 3 Exemplu de utilizare a agregării SQL → linii facturate

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) Cartea de prețuri și evaluarea (evaluare)

Modele de suport: plat, pe niveluri, volum, credite incluse, pay-as-you-go și suprascriere.

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) Facturare: formarea contului

1. Perioada de întrerupere (după localizarea contului).

2. Rata de la planul de sus/jos-grad (de zi).

3. Evaluarea utilizării + fixarea liniilor de factură.

4. Taxele (TVA/GST) în funcție de locația clientului și punctul de service.

5. Credite/reduceri/cupoane.

6. Semnarea și publicarea, trimiterea spre plată (PSP), cărți web.

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) Impozite și multicurrency

TVA/TVA/GST: păstrați profilul fiscal (țara, TVA-ID valabil, B2B/B2C).
Ratele de impozitare până la data (versiunea), taxa inversă pentru EU B2B.
Conversia FX: rata la data facturării (ERU/furnizor), păstrați sursa ratei.
Documente: factura, nota de credit, nota de debit - cu numere si serii.

9) Plăți, întâlniri și litigii

PSP (Stripe/Braintree/Adyen): plăți tokenizate, retribuții la refuz, dunning (1-3-7 zile).
Litigii/chargebacks: stabilirea statutelor, conectarea la o factură, cronologie de interacțiune.
Rambursări: parțiale/complete, asociate cu 'payment _ id' și' facture _ id'.
Semnale de fraudă: anomalii geo/ASN, explozii de utilizare, carduri diferite - steaguri în facturare.

10) Credite, reduceri, credite SLA

Credite promoționale (portofel), credite de serviciu pentru încălcarea SLA (start auto în perioada următoare).
Cupoane: fixe/dobândă, termen minim, restricții asupra planului/punctelor finale.
Transparență: în portal arată soldul împrumuturilor și istoria reducerilor.

11) Idempotență și ajustări

Toate operațiunile de scriere prin Idempotency-Key.
Ajustări - numai prin ajustări evenimente (pozitive/negative), fără editarea originalului.
Reconciliere: verificarea zilnică a de utilizare facturilor PSP.

12) Siguranță și conformitate

HMAC/JWT evenimente de utilizare semnătură de la gateway.
mTLS pentru ingerare, chei individuale pe mediu (prod/etapă).
Minimizarea PII (nu stocați inutil PAN/mail), DSAR/Legal Hold.
Audit-log neschimbabil (numai pentru adăugare) pentru tranzacțiile financiare.

13) API Portal de facturare (fragmente 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"

Antetele din principalele răspunsuri API sunt „X-Cota-rămasă”, „X-RateLimit-rămasă”, „X-Utilizare-Perioadă”.

14) Webhooks și evenimente de facturare

Evenimente: "factură. a creat „,” factură. finalizat „,” plata. a reuşit 'failed', 'dunning. Încercaţi din nou „,” credit. aplicat „,” litigiu. deschis „închis”.
Cerințe: semnătura cârligelor web, repetarea cu backoff, eliminarea duplicatelor prin 'delivery _ id'.

15) Indicatori de raportare și de afaceri

• MRR/ARR (plan/geo segmentare), ARPU, LTV/CAC, Churn (logo/venituri), Net Revenue Retention (NRR).
• Utilizare → Venituri: carduri de conversie blocaj (în cazul în care acestea rulează în cote).
• Cost-to-Serve: costul infrastructurii/cererii → marja pe planuri.

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 autoservire

Inregistrare, planuri, chei, grafice de utilizare, facturi (PDF/JSON), carti web.
Upgrade/downgrade, previzualizare facturi (pro-forma), gestionarea metodelor de plată.
Notificări: „cotă <10%”, „overidge inclus”, „factură emisă/plătită”.

17) Testarea și mediul

Sandbox de facturare: PSP-uri inactive, ratele de impozitare de testare.
Testarea contractuală a evenimentelor de utilizare (schema/câmpurile obligatorii).
Replay probele prod în cerb, preț teste de regresie fag.
Backfill este sigur: numai prin lot-ingera cu idempotenta.

18) FinOps și economia tarifelor

Luați în considerare marja privind punctele finale/planurile: venituri − cost-to-serve.
Alocați operațiuni „costisitoare” împrumuturilor și limitați în niveluri scăzute.
Monitorizați costul interogării în Observabilitate și link către facturare.

19) Lista de verificare lansare

• The 'usage _ event '/' adjustment '/' facture _ line' schemes sunt angajate și versionate.
• Pret carte testat (plat/nivelat/volum), prorate/suprascrie corect.
• Idempotence de ingestie și webhooks, audit-log append-only.
• Tax/TVA/FX corect, profilurile clienților completate.
• Portal: utilizare, facturi, credite, carti web; Integrarea PSP și dunning.
• DWH raportare (MRR/ARPU/LTV/Churn/NRR), reconciliere zilnic.
• Politicile de credit și dispute SLA sunt documentate.

20) Erori frecvente și anti-modele

Nu există idempotență → utilizare duplicat/dublu write-off.
Prețul „despre cerere” fără împrumuturi pentru puncte finale grele → marjă negativă.
Taxele „la locul companiei”, nu clientul → erori de conformitate.
Facturi fără detalii → disputele clienților.
Nici o reconciliere între usage↔PSP↔invoysy → raportarea discrepanțelor.

Total

Facturarea puternică pentru API-uri este arhitectura contorizării bazată pe evenimente, cartea de prețuri clară, idempotența strictă, facturarea corectă a taxelor/FX și raportarea transparentă. Conectați utilizarea la venituri, oferiți clientului detalii clare și automatizați întreaga călătorie - de la eveniment la factură la tabloul de bord MRR. Acest lucru va oferi venituri previzibile, mai puține dispute și o economie de produs ușor de gestionat.