Rozliczenia i sprawozdawczość API

1) Dlaczego własny rachunek za API

Przezroczysta monetyzacja: link użytkowania → przychody.
Skalowalność i kontrola: kwoty, nadwyżki, pożyczki, księga cen zgodnie z planami.
Dokładność finansowa: podatki/VAT, wielokrotność, akty prawne i dokumenty zamknięcia.
Zaufanie klienta: szczegółowe raporty użytkowania, haki internetowe, portal samoobsługowy.

2) Architektura rozliczeniowa (wysoki poziom)

Producenci (brama API, usługi) → Użycie Event Bus (Kafka/kolejka) → Metering & Rating → Billing DB → Fakturowanie/Podatki → Płatności (PSP) → Raportowanie DWH → Portal klienta/Webhooks.

• Pomiary - zbieranie i normalizacja użytkowania (zapytania, pożyczki, wolumeny).
• Rating - oszacowanie kosztu zdarzenia zgodnie z księgą cenową/planem.
• Fakturowanie - agregacja za okres, zysk, podatki, rabaty, kredyty.
• Płatności - odpisy/odpisy, randki (dunning).
• Sprawozdawczość - MRR/ARPU/LTV, kohorta churn, cost-to-serve.
• Audyt - idempotencja, niezmienne dzienniki.

3) Podmioty i identyfikatory

Konto (najemca), plan, uprawnienia, zdarzenie dotyczące użytkowania, faktura, nota kredytowa, profil podatkowy.
Ważne: idempotency_key do użycia/faktury/płatności, źródło (brama/partia), wersja schematu zdarzeń.

4) Zdarzenie dotyczące użytkowania: system referencyjny

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
}

Zasady: zdarzenia są tylko dodawane; edycje - poprzez korektę zdarzeń z odniesieniem do 'event _ id'.

5) Warstwa magazynowo-agregacyjna

5. 1 OLTP (Billing DB)

Тавлина: „najemcy”, „plany”, „plan _ prices”, „entitlements”, „usage _ events”, „rated _ lines”, „faktury”, „faktury _ lines”, „tax _ rates”, „credits”, „payments”, „refunds”, „disputes”.

5. 2 DWH (analityka)

Макта: 'f _ usage', 'f _ billing', 'f _ payments'; wymiary: 'd _ lokator', 'd _ plan', 'd _ endpoint', 'd _ region', 'd _ date'.

5. 3 Przykład zastosowania agregacji SQL → linie rozliczeniowe

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) Księga cen i ocena (rating)

Modele wsparcia: płaskie, wielopoziomowe, wolumen, kredyty wiązane, pay-as-you-go i override.

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) Fakturowanie: tworzenie konta

1. Okres cutoff (według lokalizacji konta).

2. Wskaźnik w górę/w dół (w dzień).

3. Ocena użytkowania + mocowanie linii faktur.

4. Podatki (VAT/GST) według lokalizacji i punktu obsługi klienta.

5. Kredyty/zniżki/kupony.

6. Podpisywanie i publikowanie, wysyłanie płatności (PSP), haki internetowe.

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) Podatki i wielokrotność

VAT/VAT/GST: prowadzenie profilu podatkowego (kraj, ważny identyfikator VAT, B2B/B2C).
Stawki podatkowe według daty (wersja), odwrotne obciążenie dla EU B2B.
Konwersja FX: kurs na dzień faktury (ERU/dostawca), zachować źródło kursu.
Dokumenty: faktura, nota kredytowa, nota debetowa - z numerami i seriami.

9) Płatności, randki i spory

PSP (Stripe/Braintree/Adyen): płatności tokenizowane, przekłady dotyczące odmowy, dunning (1-3-7 dni).
Spory/obciążenia zwrotne: ustalanie statusów, powiązanie z fakturą, harmonogram interakcji.
Refundacje: częściowe/pełne, związane z 'payment _ id' i' fakturą _ id'.
Sygnały oszustwa: anomalie geo/ASN, wybuchy użytkowania, różne karty - flagi w rozliczeniach.

10) Kredyty, zniżki, kredyty SLA

Kredyty promocyjne (portfel), kredyty usługowe za naruszenie SLA (auto start w następnym okresie).
Kupony: stałe/odsetki, minimalny termin, ograniczenia dotyczące planu/punktów końcowych.
Przejrzystość: w portalu pokazano saldo pożyczek i historię umorzeń.

11) Idempotencja i korekty

Wszystkie operacje pisania za pośrednictwem Idempotence-Key.
Korekty - tylko poprzez ustawienia zdarzeń (dodatnie/negatywne), bez edycji oryginału.

Uzgadnianie: codzienna weryfikacja sposobu użycia

12) Bezpieczeństwo i zgodność

Imprezy z użyciem sygnatury HMAC/JWT z bramy.
mTLS do spożycia, indywidualne klawisze na środowisko (prod/stage).
Minimalizacja PII (nie przechowywać niepotrzebnie PAN/mail), DSAR/Legal Hold.
Dziennik audytu niezmienny (tylko dodatek) dla transakcji finansowych.

13) Portal rozliczeniowy API (fragmenty 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"

Nagłówki głównych odpowiedzi API to „X-Quota-Remaining”, „X- Limit-Remaining”, „X-Usage-Period”.

14) Haki internetowe i wydarzenia rozliczeniowe

Wydarzenia: "faktura. created ',' faktura. sfinalizowana płatność „,”. udało się "ogarnąć", "dunning. ponowna próba ',' kredyt. zastosowany „,” spór. otwarte „przegrane”.
Wymagania: podpis haków webowych, powtarzanie z backoff, deduplication by 'delivery _ id'.

15) Sprawozdawczość i wskaźniki biznesowe

• MRR/ARR (plan/segmentacja geo), ARPU, LTV/CAC, Churn (logo/dochód), retencja dochodów netto (NRR).
• Użycie → Przychody: wąskie gardła karty konwersji (gdzie napływają do kwot).
• Koszt obsługi: koszt infrastruktury/żądanie → marża na plany.

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 samoobsługowy

Rejestracja, plany, klucze, wykresy użytkowania, faktury (PDF/JSON), haki internetowe.
Upgrade/downgrade, podgląd faktury (pro-forma), zarządzanie metodą płatności.
Powiadomienia: „kontyngent <10%”, „uwzględnione koszty ogólne”, „wystawiona/wypłacona faktura”.

17) Badania i środowisko

Rachunki za piaskownicę: obojętne dostawcy, stawki podatku testowego.
Testy kontraktowe zdarzeń eksploatacyjnych (schemat/wymagane pola).
Powtórz próbki prod w jelicie, testy regresji buka.
Zasypka jest bezpieczna: tylko przez partię z idempotencją.

18) FinOps i ekonomika taryf

Należy rozważyć marżę punktów/planów końcowych: dochody − koszty do obsługi.
Przeznaczenie „kosztownych” operacji na pożyczki i ograniczenie w niskich poziomach.
Monitoruj koszt zapytania w obszarze Obserwowalność i link do rozliczeń.

19) Lista kontrolna startu

• „Użycie _ event ”/„ korekta ”/„ faktura _ line” są realizowane i zmieniane.
• Przetestowana książka cenowa (płaska/wielopoziomowa/objętość), poprawna prorate/override.
• Idempotence ingestion i webhooks, audit-log-append-only.
• Podatek/VAT/FX poprawne, profile klientów wypełnione.
• Portal: korzystanie, faktury, kredyty, haki internetowe; Integracja PSP i wydobycie.
• Raportowanie DWH (MRR/ARPU/LTV/Churn/NRR), codzienne pojednanie.
• Zasady kredytu i sporów SLA są udokumentowane.

20) Częste błędy i anty-wzory

Brak idempotencji → podwójne użycie/podwójne umorzenie.
Cena „o żądanie” bez pożyczek dla ciężkich punktów końcowych → ujemna marża.
Podatki „w miejscu firmy”, a nie klient → błędy zgodności.
Faktury bez szczegółów → spory z klientem.
Brak uzgadniania pomiędzy użyciem, a PSP, a fakturą → zgłaszanie rozbieżności.

Razem

Mocne rozliczenia dla API to architektura pomiarowa oparta na zdarzeniach, przejrzysta księga cen, ścisła idempotencja, prawidłowe fakturowanie podatkowe/FX i przejrzyste sprawozdawczość. Link wykorzystanie do przychodów, dać klientowi jasne szczegóły i zautomatyzować całą podróż - od wydarzenia do faktury do deski rozdzielczej MRR. Zapewni to przewidywalne dochody, mniejszą liczbę sporów i zarządzaną gospodarkę produktową.