API Faturalandırma ve Raporlama

1) Neden API için kendi faturalandırma

Şeffaf para kazanma: kullanım bağlantısı - gelir.
Ölçeklenebilirlik ve kontrol: kotalar, geçersiz kılma, krediler, planlara göre fiyat defteri.
Finansal doğruluk: vergiler/KDV, çok para birimi, eylemler ve kapanış belgeleri.
Müşteri güveni: ayrıntılı kullanım raporları, webhook'lar, self servis portal.

2) Fatura mimarisi (üst düzey)

Üreticiler (API ağ geçidi, hizmetler) - Kullanım Etkinlik Veri Yolu (Kafka/Sıra) - Ölçüm ve Derecelendirme - Faturalandırma DB - Faturalandırma/Vergiler - Ödemeler (PSP) - Raporlama DWH - Müşteri Portalı/Web Kitapları.

• Ölçme - kullanımın toplanması ve normalleştirilmesi (talepler, krediler, hacimler).
• Derecelendirme - fiyat kitabına/planına göre etkinliğin maliyetinin tahmini.
• Faturalama - dönem için toplama, kar, vergiler, indirimler, krediler.
• Ödemeler - yazma-off/refands, escort (dunning).
• Raporlama - MRR/ARPU/LTV, kohort churn, hizmet maliyeti.
• Denetim - idempotence, değişmeyen günlükler.

3) Varlıklar ve tanımlayıcılar

Hesap (kiracı), Plan, Yetkiler, Kullanım Olayı, Fatura, Kredi Notu, Vergi Profili.
Hayati: Kullanım/fatura/ödeme, kaynak (ağ geçidi/toplu iş), olay şemasının sürümü idempotency_key.

4) Kullanım olayı: referans şeması

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
}

Kurallar: olaylar sadece eklenir; Düzenlemeler - 'event _ id' referansıyla düzeltici ayarlama olayları yoluyla.

5) Depolama ve toplama katmanı

5. 1 OLTP (Faturalandırma DB)

Таблицы: 'kiracılar', 'planlar', 'plan _ fiyatlar', 'haklar', 'kullanım _ olaylar', 'rated _ lines', 'faturalar', 'fatura _ lines', 'vergi _ oranları', 'krediler', 'ödemeler', 'geri ödemeler', 'anlaşmazlıklar'.

5. 2 DWH (analitik)

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

5. 3 SQL toplama kullanımı örneği - faturalandırılmış çizgiler

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) Fiyat kitabı ve derecelendirme (derecelendirme)

Destek modelleri: düz, katmanlı, hacim, birlikte verilen krediler, kullandıkça öde ve geçersiz kılma.

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) Faturalama: hesap oluşumu

1. Kesme süresi (hesap yerel ayarına göre).

2. Yukarı/aşağı dereceli planda (güne göre) puan.

3. Kullanım derecesi + fatura hatlarının sabitlenmesi.

4. Müşterinin bulunduğu yere ve hizmet noktasına göre vergiler (KDV/GST).

5. Krediler/indirimler/kuponlar.

6. İmzalama ve yayınlama, ödeme için gönderme (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) Vergiler ve çok para birimi

KDV/KDV/GST: Vergi Profilini saklayın (ülke, geçerli KDV-ID, B2B/B2C).
Tarihe göre vergi oranları (sürüm), AB B2B için ters ücret.
FX dönüşümü: fatura tarihindeki oran (ERU/sağlayıcı), oranın kaynağını saklayın.
Belgeler: fatura, kredi notu, borç notu - numaralar ve serilerle.

9) Ödemeler, tarihleme ve anlaşmazlıklar

PSP (Stripe/Braintree/Adyen): tokenize ödemeler, reddetme üzerine geri ödemeler, dunning (1-3-7 gün).
Anlaşmazlıklar/ters ibrazlar: durumları düzeltme, bir faturaya bağlama, etkileşim zaman çizelgesi.
Geri ödemeler: Kısmi/tam, 'payment _ id've' invoice _ id'ile ilişkili.
Dolandırıcılık sinyalleri: coğrafi/ASN anomalileri, kullanım patlamaları, farklı kartlar - faturalandırmada bayraklar.

10) Krediler, indirimler, SLA kredileri

Promosyon kredileri (cüzdan), SLA'nın ihlali için hizmet kredileri (bir sonraki dönemde otomatik başlangıç).
Kuponlar: Sabit/faiz, minimum vade, plan/uç noktalardaki kısıtlamalar.
Şeffaflık: Portalda kredilerin bakiyesini ve yazıların tarihini gösterir.

11) Idempotency ve ayarlamalar

Tüm yazma işlemleri Idempotency-Key üzerinden yapılır.
Ayarlamalar - sadece orijinal düzenleme olmadan, ayarlamalar olaylar (pozitif/negatif) aracılığıyla.
Mutabakat: PSP ↔ kullanım rated_lines ↔ ↔ faturalarının günlük olarak doğrulanması.

12) Güvenlik ve uyumluluk

Ağ geçidinden HMAC/JWT imza kullanım olayları.
Yutmak için mTLS, ortam başına ayrı anahtarlar (prod/stage).
PII minimizasyonu (PAN/postayı gereksiz yere saklamayın), DSAR/Legal Hold.
Finansal işlemler için denetim günlüğü değiştirilemez (yalnızca ek).

13) Fatura Portalı API'si (OpenAPI parçaları)

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"

Ana API yanıtlarındaki üstbilgiler 'X-Kontenjan-Kalan', 'X-RateLimit-Kalan', 'X-Kullanım-Dönemi'dir.

14) Webhook'lar ve faturalandırma etkinlikleri

Olaylar: 'fatura. yaratılmış ',' fatura. Kesinleşmiş ',' ödeme. 'başarısız', 'dunning' başardı. Redy ',' kredi. Uygulandı ',' anlaşmazlık. 'kapalı' açıldı.
Gereksinimler: webhook'ların imzalanması, backoff ile tekrarlanması, 'delivery _ id'ile veri tekilleştirme.

15) Raporlama ve iş metrikleri

• MRR/ARR (plan/coğrafi segmentasyon), ARPU, LTV/CAC, Churn (logo/gelir), Net Gelir Tutma (NRR).
• Kullanım - Gelir: Darboğaz dönüşüm kartları (kotalara girdikleri yerlerde).
• Cost-to-Serve: Altyapı/talep maliyeti - planlarda marj.

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 servis portalı

Kayıt, planlar, anahtarlar, kullanım grafikleri, faturalar (PDF/JSON), web kitapları.
Yükseltme/düşürme, fatura önizleme (proforma), ödeme yöntemi yönetimi.
Bildirimler: "kota <%10", "fazla ödeme dahil", "düzenlenen/ödenen fatura".

17) Test ve çevre

Sandbox faturalandırma: sahte PSP'ler, test vergi oranları.
Kullanım olaylarının sözleşme testleri (şema/gerekli alanlar).
Bekarlıkta prod örneklerini tekrar oynatın, fiyat kayın regresyon testleri.
Dolgu güvenlidir: sadece idempotency ile toplu alım yoluyla.

18) FinOps ve tarifelerin ekonomisi

Uç noktalardaki/planlardaki marjı göz önünde bulundurun: gelir − hizmet maliyeti.
"Pahalı" işlemleri kredilere tahsis edin ve düşük seviyelerde sınırlayın.
Gözlemlenebilirlik'teki sorgu maliyetini izleyin ve faturalandırmaya bağlantı verin.

19) Kontrol listesini başlat

• 'usage _ event'/' adjustment'/' invoice _ line' şemaları işlenir ve sürümlenir.
• Fiyat kitap test (düz/katmanlı/hacim), doğru prorate/override.
• Yutma ve webhooks idempotency, denetim-günlük ekleme-sadece.
• Vergi/KDV/FX doğru, müşteri profilleri dolduruldu.
• Portal: kullanım, faturalar, krediler, web kitapları; PSP entegrasyonu ve dunning.
• DWH raporlama (MRR/ARPU/LTV/Churn/NRR), uzlaşma günlük.
• SLA kredi ve anlaşmazlık politikaları belgelenmiştir.

20) Sık hatalar ve anti-desenler

Hiçbir idempotency - yinelenen kullanım/çift yazma-off.
Ağır uç noktalar için kredi olmadan "talep hakkında" fiyat - negatif marj.
Vergiler "şirketin yerinde", müşteri değil - uyumluluk hataları.
Ayrıntılı olmayan faturalar - müşteri anlaşmazlıkları.
usage↔PSP↔invoysy arasında uzlaşma yok - raporlama tutarsızlıkları.

Toplam

API'ler için güçlü faturalandırma, olay odaklı ölçüm mimarisi, net fiyat defteri, sıkı idempotence, doğru vergi/FX faturalandırması ve şeffaf raporlamadır. Kullanımı gelire bağlayın, müşteriye net ayrıntılar verin ve olaydan faturaya ve MRR kontrol paneline kadar tüm yolculuğu otomatikleştirin. Bu, öngörülebilir gelirler, daha az anlaşmazlık ve yönetilebilir bir ürün ekonomisi sağlayacaktır.