Bollo API e reporting

1) Perché un bollo personalizzato per l'API

La monetizzazione trasparente è il collegamento tra usage e ricavato.
Scalabilità e controllo: quote, overage, prestiti, price-book secondo i piani.
Precisione finanziaria: tasse/IVA, moltiplicazione, atti e documenti di chiusura.
Credibilità dei clienti: report usage dettagliati, siti web, portale di autosufficienza.

2) Architettura di billing (ad alto livello)

Producers (API-gateway, servizi) Usage Event Bus (Kafka/Queue) Metering & Rating Billing DB Invoicing/Taxi-Payments (PSP) Reporting DWH Portale client/WWM ebhooks.

• Metering - raccolta e normalizzazione usage (richieste, prestiti, quantità).
• Rating - Stima del costo dell'evento in base a price-book/piano.
• Fatturazione - aggregazione per il periodo, prurito, tasse, sconti, prestiti.
• Pagamenti - prelievi/rimborsi, dating (dunning).
• Rapporti - MRR/ARPU/LTV, churn coorte, cost-to-serve.
• Controllo - Idampotenza, registri invariati.

3) Entità e ID

Account (tenant), Plan, Entitlements (autorizzazioni/quote), Usage Event, Invoice, Credit Note, Tax Profile.
È vitale: idempotency _ key su usage/invoice/payment, source (gateway/batch), versione schema evento.

4) Evento di consumo (usage) - schema di riferimento

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
}

Regole: gli eventi vengono solo aggiunti; modifiche - Tramite adjustment events di regolazione con riferimento a «event _ id».

5) Deposito e livello di aggregazione

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

Факты: `f_usage`, `f_billing`, `f_payments`; le misure sono «d _ tenant», «d _ plan», «d _ endpoint», «d _ region», «d _ date».

5. 3 Esempio di aggregazione 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 (valutazione)

Supportare i modelli 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) Fatturazione: creazione dei conti

1. Cutoff del periodo (in base all'account locale).

2. Progettato per il programma di roadmap (per giorni).

3. Rating usage + fissa invoice lines.

4. Tasse (VAT/GST) sulla posizione del cliente e sul luogo di fornitura del servizio.

5. Prestiti/sconti/buoni.

6. Firma e pubblicazione, invio a pagamento (PSP), webhoop.

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) Tasse e moltiplicazione

IVA/VAT/GST: conserva Tax Profile (paese valida VAT-ID, B2B/B2C).
Aliquote fiscali per data (versione), reverse cargo per B2B nell'UE.
Conversione FX - Corso alla data della fattura (ESV/provider), memorizzare l'origine del corso.
Documenti: fattura, credit note, addebito con numeri e serie.

9) Pagamenti, dating e display

PSP (Stripe/Braintree/Adyen): pagamenti tokenized, retro in caso di rifiuto, dunning (1-3-7 giorni).
Dispute/marcebacks - Fissa gli stati, lega la fattura, timeline di interazione.
Refunds: parziali/completi, associati a «payment _ id» e «invoice _ id».
Segnali di frod: anomalie geo/ASN, picchi usage, mappe diverse - bandiere in bilingue.

10) Prestiti, sconti, prestiti SLA

Crediti promozionali (portafoglio), credits service per violazione della SLA (Auto-Stipula in seguito).
Buoni: fix/percentuale, durata minima, limiti di piano/endpoint.
Trasparenza: il portale mostra il saldo dei crediti e la cronologia dei prelievi.

11) Idampotenza e regolazioni

Tutte le operazioni write tramite Idempotency-Key.
Regolazioni solo attraverso gli eventi adjustments (positivi/negativi), senza modificare l'originale.
Assemblaggio giornaliero usage _ rated _ lines invoices PSP.

12) Sicurezza e compliance

HMAC/JWT firma eventi usage da gateway.
mTLS per ingest, chiavi separate per ambiente (prod/stage).
Riduzione PII (non conservare PAN/posta senza necessità), DSAR/Legale Hold.
Controllo-login invariato (append-only) per le transazioni finanziarie.

13) API del portale di billing (frammenti di 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"

I titoli sono «X-Quota-Remaining», «X-RateLimit-Remaining», «X-Usage-Period».

14) Webhook ed eventi di billing

Eventi dì invoice ". created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Requisiti: firma webhoop, ripetizione backoff, deduplicazione dì delivery _ id ".

15) Report e metriche aziendali

• MRR/ARR (segmentazione dei piani/geo), ARPU, LTV/CAC, Churn, Net Revenue Retention (NRR).
• Usage → Revenue - Mappe di conversione dei colli di bottiglia.
• Cost-to-Serve - Il costo dell'infrastruttura/richiesta è un margine di pianificazione.

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: portale di auto-servizio

Registrazione, piani, chiavi, grafici usage, fatture (PDF/JSON), webhoop.
Upgrade/downgrade, anteprima del conto (pro-form), gestione dei metodi di pagamento.
Le notifiche sono: «quota <10%», «overage incluso», «fattura/pagata».

17) Test e ambienti

Sandbox billing - PSP fittizi, tasse di prova.
Test contract degli eventi usage (schema/campi obbligatori).
Replay prod-sample in stag, test di regressione price-book.
Backfill è sicuro: solo tramite batch-ingest con idumaticità.

18) FinOps ed economia tariffaria

Contate i margini per endpoint/piani: revenue - cost-to-serve.
Assegnate le transazioni «costose» ai prestiti e limitate ai low-tiers.
Monitora query-cost in Observability e collegare il bollettino.

19) Assegno foglio di avvio

• Gli schemi «usage _ event »/« adjustment »/« invoice _ line» sono fissati e versionati.
• Price-book testato (flat/tiered/volume), prolate/overage corretto.
• Idempotence ingestion e webhoop, controllo-login append-only.
• Tasse/IVA/FX sono corretti, i profili dei clienti sono pieni.
• Portale: usage, fatture, prestiti, webhoop; PSP integrazione e dunning.
• Report DWH (MRR/ARPU/LTV/Churn/NRR), riconcisione giornaliera.
• I criteri SLA e i display sono documentati.

20) Errori frequenti e anti-pattern

Nessuna idampotenza per le riprese usage/doppia cancellazione.
Price «richiesta» senza crediti per endpoint pesanti ha un margine negativo.
Le tasse per la società, non per il cliente, sono un errore di compagine.
Le fatture non hanno dettagliato le discussioni con i clienti.

Nessuna reconcilion tra i dati di

Totale

Un forte billing per l'API è un'architettura di metering per eventi, un chiaro price-book, una rigorosa idempotenza, una corretta fattura fiscale/FX e rapporti trasparenti. Collegare l'usage al fatturato, fornire al cliente dettagli chiari e automatizzare l'intero percorso, dall'evento alla fattura e al MRR-dashbord. Ciò garantirà redditi prevedibili, meno display e un'economia controllata del prodotto.