Billing API və hesabat

1) Niyə API üçün öz billing

Şəffaf monetizasiya: rabitə usage → gəlir.
Skalasiya və nəzarət: kvotalar, overage, kreditlər, planlara görə qiymət beki.
Maliyyə dəqiqliyi: vergilər/ƏDV, multivalyuta, aktlar və bağlayıcı sənədlər.
Müştərilərin etimadı: ətraflı usage hesabatları, vebhuklar, özünə xidmət portalı.

2) Billinq arxitekturası (yüksək səviyyəli)

Producers (API-şlyuz, xidmətlər) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Portal Client/Webhooks.

• Ölçmə - usage-in toplanması və normallaşdırılması (sorğular, kreditlər, həcmlər).
• Reytinq (rating) - qiymət/plan üzrə hadisənin dəyərinin qiymətləndirilməsi.
• İnvoysinq - dövr üçün aqreqasiya, proyeyt, vergilər, endirimlər, kreditlər.
• Ödənişlər - debet/refand, deytinq (dunning).
• Hesabat - MRR/ARPU/LTV, kohort churn, cost-to-serve.
• Audit - idempotentlik, dəyişməz jurnallar.

3) Mahiyyətlər və identifikatorlar

Account (tenant), Plan, Entitlements (icazə/kvota), Usage Event, Invoice, Credit Note, Tax Profile.
Həyati əhəmiyyət kəsb edir: idempotency_key usage/invoice/payment, source (gateway/batch), version hadisə sxemləri.

4) İstehlak hadisəsi (usage): istinad sxemi

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
}

Qaydalar: hadisələr yalnız əlavə olunur; düzəlişlər - 'event _ id' linki ilə düzəliş adjustment events vasitəsilə.

5) Saxlama və aqreqasiya təbəqəsi

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

Факты: `f_usage`, `f_billing`, `f_payments`; 'd _ tenant', 'd _ plan', 'd _ endpoint', 'd _ region', 'd _ date' ölçmələri.

5. 3 Nümunə SQL-yığma 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) Qiymət və rating (qiymətləndirmə)

Modelləri dəstəkləyin: flat, tiered, volume, bundled credits, pay-as-you-go və 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) İnvoysinq: hesabların formalaşdırılması

1. Cutoff dövrü (yerli hesab).

2. Up/down-grade planında keçid (günlərlə).

3. Reytinq usage + qeyd invoice lines.

4. Müştərinin yeri və xidmət yeri üzrə vergilər (VAT/GST).

5. Kreditlər/endirimlər/kuponlar.

6. Abunə və nəşr, ödəniş göndərilməsi (PSP), webhucks.

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) Vergilər və multivalyuta

ƏDV/VAT/GST: Vergi Profili (ölkə, etibarlı VAT-ID, B2B/B2C) saxlayın.
Tarix üzrə vergi dərəcələri (versiya), AB-də B2B üçün reverse charge.
FX-konvertasiya: invoys tarixi kursu (ECB/provayder), məzənnə mənbəyini saxlayın.
Sənədlər: invoys, kredit note, debet nota - nömrələri və seriyaları ilə.

9) Ödənişlər, deytinq və mübahisələr

PSP (Stripe/Braintree/Adyen): tokenized ödənişlər, retras, dunning (1-3-7 gün).
Disputes/chargebacks: status sabitləşdirilməsi, invoys ilə əlaqə, time line qarşılıqlı.
Refunds: qismən/tam, bağlı 'payment _ id' və 'invoice _ id'.
Frod siqnalları: geo/ASN-anomaliyalar, usage sıçrayışları, müxtəlif kartlar - billinqdə bayraqlar.

10) Kreditlər, endirimlər, SLA-kreditlər

Promosyon kreditləri (cüzdan), SLA-nın pozulmasına görə service credits (sonrakı dövrdə avtomatik hesablama).
Kuponlar: fix/faiz, minimum müddət, plan/end-point məhdudiyyətləri.
Şəffaflıq: Portalda kreditlərin balansını və silinmə tarixçəsini göstərin.

11) İdempotentlik və düzəlişlər

Idempotency-Key vasitəsilə bütün write əməliyyatları.
Düzəlişlər - yalnız orijinal düzəlişlər olmadan, adjustments hadisələri (müsbət/mənfi) vasitəsilə.
Reconciliation: gündəlik yoxlama usage, rated_lines, invoices, PSP.

12) Təhlükəsizlik və uyğunluq

HMAC/JWT imza usage-hadisə şlüzdən.
mTLS ingest, mühit üçün fərdi açarlar (prod/stage).
PII-minimallaşdırma (lazım olmadan PAN/poçt saxlamaq deyil), DSAR/Legal Hold.
Maliyyə əməliyyatları üçün audit-log dəyişməz (append-only).

13) Billing portalının API-si (OpenAPI fraqmentləri)

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"

Əsas API-nin cavablarındakı başlıqlar: 'X-Quota-Remaining', 'X-RateLimit-Remaining', 'X-Usage-Period'.

14) Vebhuk və billinq hadisələri

Hadisələr: 'invoice. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Tələblər: webhook imzası, backoff ilə təkrar, 'delivery _ id' deduplikasiyası.

15) Hesabat və biznes metrikası

• MRR/ARR (planlara görə seqmentasiya/geo), ARPU, LTV/CAC, Churn (logo/gəlirli), Net Revenue Retention (NRR).
• Usage → Revenue: «dar yerlərin» konversiya kartları (burada kvotalara əsaslanır).
• Cost-to-Serve: infrastruktur/sorğu dəyəri → marja planları.

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: özünə xidmət portalı

Qeydiyyat, planlar, açarlar, usage-qrafiklər, invoyslar (PDF/JSON), vebhuklar.
Yeniləmə/endirim, hesabın əvvəlcədən yoxlanılması (pro-forma), ödəniş üsullarının idarə edilməsi.
Bildirişlər: «kvota <10%», «overage daxil», «invoys qoyuldu/ödənildi».

17) Test və mühit

Sandbox billing: uydurma PSP, test vergi dərəcələri.
Contract-testlər usage-hadisələr (sxem/məcburi sahələr).
Replay prod-samples yığın, regressiya test qiymət fıstığı.
Backfill təhlükəsiz: yalnız idempotentlik ilə batch-ingest vasitəsilə.

18) FinOps və tarif iqtisadiyyatı

revenue − cost-to-serve.
Kreditlərə «bahalı» əməliyyatları ayırın və low-tiers-də məhdudlaşdırın.
Observability query-cost monitorinq və billing ilə əlaqə saxlayın.

19) Başlanğıc çek siyahısı

• 'usage _ event '/' adjustment '/' invoice _ line' sxemləri qeydə alınmış və versiyalaşdırılmışdır.
• Prorate/overage düzgün (düz/tiered/volume) test prorate/overage.
• İdempotentlik ingestion və vebhuk, audit log append-only.
• Vergilər/ƏDV/FX düzgün, müştərilərin profilləri doldurulur.
• Portal: usage, invoys, kreditlər, vebhuks; PSP inteqrasiya və dunning.
• DWH-hesabat (MRR/ARPU/LTV/Churn/NRR), gündəlik reconciliation.
• SLA kredit və mübahisə siyasətləri sənədləşdirilmişdir.

20) Tez-tez səhvlər və anti-nümunələr

No idempotentity → double usage/cüt silinmə.
Ağır end nöqtələri üçün kreditsiz «sorğu haqqında» qiymət → mənfi marja.
Vergilər «şirkətin yerində» deyil, müştəri → uyğunluq səhvləri.
Ətraflı olmayan invoys → müştərilərlə mübahisələr.
No reconciliation arasında usage, PSP, invoys → hesabat uyğunsuzluqları.

Yekun

API üçün güclü billing - hadisə meterinq arxitekturası, aydın qiymət qaynağı, ciddi idempotentlik, düzgün vergi invoysinqi/FX və şəffaf hesabatdır. Usage-i gəlirlə əlaqələndirin, müştəriyə başa düşülən detallar verin və hadisədən invoysa və MRR dashborduna qədər bütün yolu avtomatlaşdırın. Bu, proqnozlaşdırıla bilən gəlirləri, daha az mübahisələri və idarə olunan məhsul iqtisadiyyatını təmin edəcəkdir.