Billing API va hisobot

1) Nima uchun API uchun o’z billingi

Shaffof monetizatsiya: aloqa usage → tushum.
Skalatsiya va nazorat: kvotalar, overage, kreditlar, rejalar bo’yicha prays-buklar.
Moliyaviy aniqlik: soliqlar/QQS, multivalyutalik, dalolatnomalar va yopiq hujjatlar.
Mijozlarning ishonchi: batafsil usage-hisobotlar, vebxuklar, o’z-o’ziga xizmat ko’rsatish portali.

2) Billing arxitekturasi (yuqori darajali)

Producers (API-shlyuz, servislar) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Mijoz portali/Webhooks.

• Metring - usage yig’ish va normallashtirish (so’rovlar, kreditlar, hajmlar).
• Reyting (rating) - voqea qiymatini prays-bukka/reja bo’yicha baholash.
• Invoysing - davr uchun agregatsiya, proreyt, soliqlar, chegirmalar, kreditlar.
• To’lovlar - hisobdan chiqarish/refand, deyting (dunning).
• Hisobot - MRR/ARPU/LTV, kogort churn, cost-to-serve.
• Audit - idempotentlik, o’zgarmas jurnallar.

3) Mohiyat va identifikatorlar

Account (tenant), Plan, Entitlements (ruxsatnomalar/kvotalar), Usage Event, Invoice, Credit Note, Tax Profile.
Hayotiy ahamiyatga ega: idempotency_key usage/invoice/payment, source (gateway/batch), version sxemalari.

4) Iste’mol hodisasi (usage): etalon sxemasi

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
}

Qoidalar: voqealar faqat qo’shiladi; tahrirlash -’event _ id’ga havola qilingan tuzatish adjustment events orqali amalga oshiriladi.

5) Ombor va agregatsiyalar qatlami

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

Факты: `f_usage`, `f_billing`, `f_payments`; o’lchovlar:’d _ tenant’,’d _ plan’,’d _ endpoint’,’d _ region’,’d _ date’.

5. 3 SQL agregatsiyasi namunasi 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) Prays-buk va rating (baholash)

flat, tiered, volume, bundled credits, pay-as-you-go va overage modellarini qo’llab-quvvatlang.

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) Invoysing: hisobvaraqlarni shakllantirish

1. Cutoff davri (hisobning lokali boʻyicha).

2. Reja ap/daun-greydida proreyt (kunlar bo’yicha).

3. Reyting usage + fiksatsiya invoice lines.

4. Mijozning joylashuvi va xizmat ko’rsatish joyi bo’yicha soliqlar (VAT/GST).

5. Kreditlar/chegirmalar/kuponlar.

6. Imzolash va e’lon qilish, to’lov uchun yuborish (PSP), vebxuklar.

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) Soliqlar va multivalyutlilik

QQS/VAT/GST: Tax Profile (mamlakat, VAT-ID, B2B/B2C) saqlang.
Sana (versiya) bo’yicha soliq stavkalari, Yevropa Ittifoqida B2B uchun reverse charge.
FX-konvertatsiya: invoys sanasidagi kurs (ESV/provayder), kurs manbaini saqlang.
Hujjatlar: invoys, credit note, debet-nota - tartib raqami va seriyasi bilan.

9) To’lovlar, deyting va munozaralar

PSP (Stripe/Braintree/Adyen): tokenized to’lovlar, retralar rad etilganda, dunning (1-3-7 kun).
Disputes/chargebacks: statuslarni tuzatish, invoys bilan bog’lash, vaqt oralig’ida o’zaro hamkorlik qilish.
Refunds: qisman/toʻliq,’payment _ id’va’invoice _ id’bilan bogʻliq.
Frod-signallar: geo/ASN-anomaliyalar, usage portlashlari, turli xaritalar - billingdagi bayroqlar.

10) Kreditlar, chegirmalar, SLA-kreditlar

Promo-kreditlar (hamyon), service credits SLAni buzganlik uchun (keyingi davrda avtomatik hisob).
Kuponlar: fix/foiz, eng kam muddat, reja/endpindlar bo’yicha cheklovlar.
Shaffoflik: portalda kreditlar balansi va hisobdan chiqarish tarixini ko’rsating.

11) Idempotentlik va tuzatishlar

Idempotency-Key orqali barcha write operatsiyalari.
Tuzatishlar faqat adjustments (ijobiy/salbiy) hodisalari orqali, asl nusxasini tuzatmasdan amalga oshiriladi.
Reconciliation: kundalik taqqoslash usage, rated_lines, invoices, PSP.

12) Xavfsizlik va komplayens

HMAC/JWT imzosi.
mTLS ingest uchun, chorshanba uchun alohida kalitlar (prod/stage).
PII-minimallashtirish (PAN/pochtani zaruratsiz saqlamang), DSAR/Legal Hold.
Moliyaviy operatsiyalar uchun o’zgarmas (append-only) audit-log.

13) Billing portalining API (OpenAPI parchalari)

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"

Asosiy API javoblaridagi sarlavhalar:’X-Quota-Remaining’,’X-RateLimit-Remaining’,’X-Usage-Period’.

14) Vebxuklar va billing voqealari

Hodisalar:’invoice. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Talablar: vebxuklarning imzosi, backoff bilan takrorlash,’delivery _ id’deduplikatsiyasi.

15) Biznes hisoboti va metrikasi

• MRR/ARR (reja/geo bo’yicha segmentatsiya), ARPU, LTV/CAC, Churn (logo/daromad), Net Revenue Retention (NRR).
• Usage → Revenue: «tor joylar» konversiya kartalari (kvotalarga asoslanadi).
• Cost-to-Serve: infratuzilma/so’rov qiymati → reja bo’yicha marja.

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: o’z-o’ziga xizmat ko’rsatish portali

Ro’yxatdan o’tish, rejalar, kalitlar, usage-grafiklar, invoyslar (PDF/JSON), vebxuklar.
Yangilash/tushirish, hisobni oldindan ko’rish (pro-forma), to’lov usullarini boshqarish.
Bildirishnomalar: «kvota <10%», «overij kiritilgan», «invoys qo’yilgan/to’langan».

17) Test va atrof-muhit

Sandbox billing: soxta PSP, soliqlarning test stavkalari.
Usage-hodisalarning contract-testlari (sxema/majburiy maydonlar).
Replay prod-samplov stagda, regression prays-buka testlari.
Backfill xavfsiz: faqat idempotentlik bilan batch-ingest orqali.

18) FinOps va tariflar iqtisodiyoti

Marjani endpoint/rejalar bo’yicha hisoblang: revenue − cost-to-serve.
Kreditlarga «qimmat» operatsiyalarni ajrating va low-tiers bilan cheklang.
Observability’da query-cost’ni kuzatib boring va billing bilan bogʻlang.

19) Ishga tushirish chek-varaqasi

• ’usage _ event ’/’ adjustment ’/’ invoice _ line’sxemalari qayd etilgan va versiya qilinadi.
• Prays-buk sinovdan o’tgan (flat/tiered/volume), prorate/overage to’g’ri.
• Ingestion va vebxuklarning idempotentligi, append-only audit-log.
• Soliqlar/QQS/FX to’g "ri, mijozlar profillari to’ldirilgan.
• Portal: usage, invoyslar, kreditlar, vebxuklar; PSP integratsiyasi va dunning.
• DWH-hisobot (MRR/ARPU/LTV/Churn/NRR), kundalik reconciliation.
• SLA-kreditlar va munozaralar siyosati hujjatlashtirilgan.

20) Tez-tez xatolar va anti-patternlar

Idempotentlik yoʻq → dubli usage/ikki marta hisobdan chiqarish.
Og’ir endpointlar uchun kreditsiz «so’rov» narxi → salbiy marja.
Mijoz emas, balki «kompaniya o’rni bo’yicha» soliqlar → komplayens xatolari.
Tafsilotsiz invoyslar → mijozlar bilan nizolar.
Hech qanday reconciliation mavjud emas usage, PSP, invoys → hisobot tafovutlari.

Jami

API uchun kuchli billing - bu metering arxitekturasi, aniq prays-buk, qat’iy idempotentlik, soliqlar bilan to’g’ri invoysing/FX va shaffof hisobot. Foydalanuvchini tushum bilan bog’lang, mijozga tushunarli tafsilotlar bering va voqeadan invoys va MRR-dashbordgacha bo’lgan yo’lni avtomatlashtiring. Bu prognoz qilinadigan daromadlar, kam tortishuvlar va boshqariladigan mahsulot iqtisodiyotini taʼminlaydi.