API-Abrechnung und Reporting

1) Warum eigene Abrechnung für APIs

Transparente Monetarisierung: Kommunikation zwischen Nutzung → Umsatz.
Scalability und Control: Quoten, Overage, Credits, Preisbuch nach Plänen.
Finanzielle Genauigkeit: Steuern/Mehrwertsteuer, Mehrwährungen, Urkunden und Abschlussdokumente.
Kundenvertrauen: Detaillierte Usage-Reports, Webhooks, Self-Service-Portal.

2) Abrechnungsarchitektur (High Level)

Hersteller (API-Gateway, Dienste) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Kundenportal/Webhooks.

• Metering - Sammlung und Normalisierung der Nutzung (Anfragen, Kredite, Volumen).
• Bewertung (Rating) - Bewertung des Wertes der Veranstaltung nach Preis Buche/Plan.
• Rechnungsstellung - Aggregation für den Zeitraum, pro Rate, Steuern, Rabatte, Kredite.
• Zahlungen - Abschreibungen/Refands, Dating (Dunning).
• Berichterstattung - MRR/ARPU/LTV, Kohortenkirche, Cost-to-Serve.
• Audit - Idempotenz, unveränderliche Protokolle.

3) Entitäten und IDs

Account (tenant), Plan, Entitlements (Berechtigungen/Kontingente), Usage Event, Invoice, Credit Note, Tax Profile.
Wichtig: idempotency_key auf Usage/Invoice/Payment, Source (Gateway/Batch), Version des Ereignisschemas.

4) Verbrauchsereignis (Nutzung): Referenzschema

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
}

Regeln: Ereignisse werden nur hinzugefügt; Bearbeitungen - durch Korrekturanpassungsereignisse mit Bezug auf 'event _ id'.

5) Speicher und Aggregationsschicht

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

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

5. 3 Beispiel für die SQL-Aggregation 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) Preisbuch und Bewertung (Bewertung)

Unterstützen Sie die Modelle: flat, tiered, volume, bundled credits, pay-as-you-go sowie 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) Rechnungsstellung: Rechnungsstellung

1. Zeitraum-Cutoff (nach Konto-Locale).

2. Pro Rate bei Up/Down-Grade-Plan (nach Tagen).

3. Usage Rating + Invoice Lines Fixierung.

4. Steuern (VAT/GST) nach Kundenstandort und Leistungsort.

5. Gutschriften/Rabatte/Gutscheine.

6. Signieren und Veröffentlichen, Senden gegen Zahlung (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) Steuern und Mehrwährungen

MwSt./MwSt./GST: Tax Profile (Land, gültige VAT-ID, B2B/B2C) aufbewahren.
Steuersatz nach Datum (Version), Reverse Charge für B2B in der EU.
FX-Conversion: Kurs zum Rechnungsdatum (ERU/Anbieter), Kursquelle speichern.
Dokumente: Rechnung, Gutschrift, Lastschrift - mit Nummern und Serien.

9) Zahlungen, Dating und Dispute

PSP (Stripe/Braintree/Adyen): Tokenisierte Zahlungen, Retrays bei Ausfall, Dunning (1-3-7 Tage).
Disputes/chargebacks: Statusfixierung, Verknüpfung mit Rechnung, Interaktionszeitlinie.
Refunds: partiell/vollständig, verknüpft mit 'payment _ id' und 'invoice _ id'.
Betrugssignale: Geo/ASN-Anomalien, Usage-Bursts, verschiedene Karten - Flaggen in der Abrechnung.

10) Kredite, Rabatte, SLA-Kredite

Promo-Credits (Wallet), Service-Credits für SLA-Verletzung (Autotransport in der Spur. Zeitraum).
Coupons: Fix/Prozentsatz, Mindestlaufzeit, Plan-/Endpoint-Limits.
Transparenz: Zeigen Sie im Portal den Saldo der Kredite und die Historie der Abschreibungen an.

11) Idempotenz und Anpassungen

Alle Schreibvorgänge über Idempotency-Key.
Anpassungen - nur durch Adjustments-Ereignisse (positiv/negativ), keine Bearbeitung des Originals.
Reconciliation: die tägliche Verifizierung usage ↔ rated_lines ↔ invoices ↔ PSP.

12) Sicherheit und Compliance

HMAC/JWT signiert Usage-Ereignisse vom Gateway.
mTLS für ingest, separate Schlüssel für das Medium (prod/stage).
PII-Minimierung (PAN/Mail nicht unnötig speichern), DSAR/Legal Hold.
Das Audit-Log ist für Finanztransaktionen unveränderlich (append-only).

13) Billing Portal API (OpenAPI Fragmente)

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"

Überschriften in den Antworten der Haupt-API: „X-Quota-Remaining“, „X-RateLimit-Remaining“, „X-Usage-Period“.

14) Webhooks und Billing-Events

Veranstaltungen: 'invoice. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Anforderungen: Signatur von Webhooks, Wiederholung mit Backoff, Deduplizierung durch 'delivery _ id'.

15) Geschäftsberichterstattung und Metriken

• MRR/ARR (Segmentierung nach Plänen/Geo), ARPU, LTV/CAC, Churn (Logo/Revenue), Net Revenue Retention (NRR).
• Usage → Revenue: Konversionskarten für Engpässe (wo sie auf Quoten ruhen).
• Cost-to-Serve: Kosten der Infrastruktur/Anfrage → Marge nach Plänen.

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: Self-Service-Portal

Registrierung, Pläne, Schlüssel, Nutzungsgrafiken, Rechnungen (PDF/JSON), Webhooks.
Upgrade/Downgrade, Kontovorschau (pro-forma), Verwaltung der Zahlungsmethoden.
Meldungen: „Quote <10%“, „Overage included“, „invoice fakturiert/bezahlt“.

17) Prüfung und Umgebung

Sandbox-Abrechnung: fiktive PSPs, Teststeuersätze.
Vertragstests usage-events (Schema/Pflichtfelder).
Replay-Prod-Samples im Stag, Preisbuch-Regressionstests.
Backfill ist sicher: nur über Batch-Ingest mit Idempotenz.

18) FinOps und die Tarifökonomie

Lesen Sie die Marge für Endpoints/Pläne: Revenue − Cost-to-Serve.
Ordnen Sie „teure“ Transaktionen in Kredite ein und beschränken Sie sich auf Low-Tiers.
Überwachen Sie die Abfrage-Kosten in Observability und verknüpfen Sie sie mit der Abrechnung.

19) Start-Checkliste

• Die Schemata 'usage _ event '/' adjustment '/' invoice _ line' sind fixiert und versioniert.
• Preisbuch geprüft (flat/tiered/volume), prorate/overage korrekt.
• Idempotenz von ingestion und Webhooks, audit-log append-only.
• Steuern/MwSt./FX korrekt, Kundenprofile ausgefüllt.
• Portal: Nutzung, Rechnungen, Kredite, Webhooks; PSP-Integration und Dunning.
• DWH-Reporting (MRR/ARPU/LTV/Churn/NRR), Reconciliation täglich.
• Die SLA-Kredit- und Disputationspolitik ist dokumentiert.

20) Häufige Fehler und Anti-Muster

Keine Idempotenz → doppelte Nutzung/doppelte Abschreibung.
Preis „pro Anfrage“ ohne Kredite für schwere Endpunkte → negative Marge.
Steuern „am Sitz des Unternehmens“, nicht des Kunden → Compliance-Fehler.
Rechnungen ohne Details → Streitigkeiten mit Kunden.
Keine reconciliation zwischen den usage↔PSP↔invoysy → Diskrepanzen in der Berichterstattung.

Summe

Starke Abrechnung für APIs ist eine ereignisgesteuerte Metering-Architektur, ein klares Preisbuch, strenge Idempotenz, korrekte Rechnungsstellung mit Steuern/FX und transparente Berichterstattung. Verknüpfen Sie die Verwendung mit dem Umsatz, geben Sie dem Kunden klare Details und automatisieren Sie den gesamten Weg - von der Veranstaltung über die Rechnung bis hin zum MRR-Dashboard. Dies wird vorhersehbare Einnahmen, weniger Streitigkeiten und eine überschaubare Produktökonomie ermöglichen.