Billing API we hasabat

1) Näme üçin API üçin öz billing

Aç-açan monetizasiýa: usage → girdeji baglanyşygy.
Skalasiýa we gözegçilik: meýilnamalar boýunça kwotalar, overage, karzlar, bahalar.
Maliýe takyklygy: salgytlar/goşulan baha üçin salgytlar, köp walýutalylyk, hereketler we ýapyjy resminamalar.
Müşderileriň ynamy: jikme-jik usage-hasabatlar, webhuklar, öz-özüne hyzmat portaly.

2) Billing arhitekturasy (ýokary derejeli)

Producers (API-şlýuz, hyzmatlar) → Usage Event Bus (Kafka/Queue) → Metring & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Portal Client/Webhooks.

• Ölçeg - usage ýygnamak we kadalaşdyrmak (haýyşlar, karzlar, göwrümler).
• Reýting (rating) - praws-buku/meýilnama boýunça wakanyň bahasyna baha bermek.
• Invoýsing - döwür üçin agregasiýa, proýeýt, salgytlar, arzanladyşlar, karzlar.
• Tölegler - hasapdan çykarmalar/refandlar, deyting (dunning).
• Hasabat - MRR/ARPU/LTV, kogortny churn, cost-to-serve.
• Audit - idempotentlik, üýtgemeýän žurnallar.

3) Düýp manylary we kesgitleýjiler

Account (tenant), Plan, Entitlements (rugsatlar/kwotalar), Usage Event, Invoice, Credit Note, Tax Profile.
Örän möhümdir: idempotency_key/invoice/payment, source (gateway/batch), wakanyň wersiýa shemasy.

4) Sarp ediş hadysasy (usage): salgylanma shemasy

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
}

Düzgünler: wakalar diňe goşulýar; düzedişler - 'event _ id' salgysy bilen düzediji adjustment events arkaly.

5) Ammar we agregasiýa gatlagy

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çegleri.

5. 3 SQL-agregasiýa mysaly 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) Baha kesmek we baha bermek

Modelleri goldaň: flat, tiered, volume, bundled credits, pay-as-you-go, şeýle hem 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) Invoýsing: hasaplaryň emele gelmegi

1. Cutoff (hasabyň lokalizasiýasy boýunça).

2. Meýilnamanyň ap/down-grade döwründe proýeýt (günler boýunça).

3. Reýting usage + bellik invoice lines.

4. Müşderiniň ýerleşýän ýeri we hyzmat edilýän ýeri boýunça salgytlar (VAT/GST).

5. Karzlar/arzanladyş/kuponlar.

6. Gol çekmek we çap etmek, tölemek üçin ibermek (PSP), webhuklar.

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) Salgytlar we köp walýutalylyk

Goşulan baha üçin salgydy/VAT/GST: Salgyt profilini saklaň (ýurt, hakyky VAT-ID, B2B/B2C).
TheB-de B2B üçin senesi (wersiýasy) boýunça salgyt stawkalary.
FX-öwrülişik: invoýs senesindäki kurs (ECB/üpjün ediji), nyrhyň çeşmesini saklaň.
Resminamalar: invoýs, credit note, debet-nota - sany we seriýasy bilen.

9) Tölegler, deýting we jedeller

PSP (Stripe/Braintree/Adyen): tokenized tölegler, ret edilende retra, dunning (1-3-7 gün).
Disputes/chargebacks: statuslary düzetmek, invoýs bilen baglanyşyk, wagtlaýyn özara gatnaşyk.
Refunds: bölekleýin/doly, 'payment _ id' we 'invoice _ id' bilen baglanyşykly.
Frod-signallar: geo/ASN-anomaliýalar, usage partlamalary, dürli kartalar - billingdäki baýdaklar.

10) Karzlar, arzanladyşlar, SLA-karzlar

Promo-kreditler (gapjyk), SLA-ny bozandygy üçin service credits (indiki döwürde awtoseçet).
Kuponlar: fiks/göterim, iň az möhlet, meýilnama/endpointler boýunça çäklendirmeler.
Aç-açanlyk: portalda karzlaryň balansyny we hasapdan çykarmagyň taryhyny görkeziň.

11) Idempotentlik we düzedişler

Idempotency-Key arkaly ähli write amallary.
Düzedişler - diňe asyl nusgasyny düzetmezden, adjustments (oňyn/negatiw) hadysalary arkaly.
Reconciliation: Gündelik deňeşdirme usage, rated_lines invoices, PSP.

12) Howpsuzlyk we gabat gelmek

HMAC/JWT şlýuzdan ulanylan wakalaryň goly.
mTLS ingest üçin, daşky gurşaw üçin aýratyn açarlar (prod/stage).
PII-minimalizasiýa (PAN/poçtany zerur bolmasa saklamaň), DSAR/Legal Hold.
Maliýe amallary üçin üýtgemeýän (append-only) audit-log.

13) Billing portalynyň API (OpenAPI bölekleri)

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"

Esasy API-iň jogaplaryndaky sözbaşylar: 'X-Quota-Remaining', 'X-RateLimit-Remaining', 'X-Usage-Period'.

14) Webhuklar we billing wakalary

Wakalar: 'invoice. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Talaplar: webhuklaryň goly, backoff-dan gaýtalamak, 'delivery _ id' -den de-duplikasiýa.

15) Işiň hasabatlylygy we metrikleri

• MRR/ARR (meýilnama/geo segmentasiýasy), ARPU, LTV/CAC, Çurn (logo/girdeji), Net Revenue Retention (NRR).
• Usage → Revenue: "dar ýerleriň" öwrülişik kartalary (kwotalara esaslanýar).
• Cost-to-Serve: infrastrukturanyň/islegiň bahasy → meýilnama boýunça 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: öz-özüne hyzmat portaly

Hasaba alyş, meýilnamalar, açarlar, usage-grafikler, invoýslar (PDF/JSON), webhuklar.
Täzelenmek/düşmek, hasaby öňünden görmek (pro-forma), töleg usullaryny dolandyrmak.
Habarnamalar: "kwota <10%", "overage goşuldy", "invoýs goýuldy/tölendi".

17) Synag we gurşaw

Sandbox billing: toslama PSP, salgyt synag nyrhlary.
Usage-wakalaryň contract-synaglary (shema/hökmany meýdançalar).
Replay proto-samplow stagda, price-bukyň regression synaglary.
Backfill howpsuz: diňe batch-ingest arkaly.

18) FinOps we nyrhlaryň ykdysadyýeti

Endpointler/meýilnamalar boýunça marjany hasaplaň: revenue − cost-to-serve.
"Gymmat" amallary karzlara bölüň we low-tiers bilen çäklendiriň.
Observability-de query-cost-a gözegçilik ediň we billing bilen baglanyşdyryň.

19) Işe girizmegiň çek-sanawy

• 'usage _ event '/' adjustment '/' invoice _ line' shemalary ýazylýar we wersiýa edilýär.
• Bahasy barlandy (flat/tiered/volume), prorate/overage dogry.
• Ingestion we webhook idempotentligi, append-only audit-log.
• Salgytlar/goşulan baha üçin salgytlar/FX dogry, müşderileriň profilleri doldurylýar.
• Portal: usage, invoýslar, karzlar, webhuklar; PSP integrasiýasy we dunning.
• DWH-hasabat (MRR/ARPU/LTV/Çurn/NRR), gündelik reconciliation.
• SLA-karzlaryň we jedelleriň syýasaty resminamalaşdyrylýar.

20) Ýygy-ýygydan ýalňyşlyklar we anti-patternler

Idempotentlik ýok → goşa ulanyş/goşa ýazmak.
Agyr endpointler üçin karzsyz "pro" bahasy → negatiw marja.
Müşderiniň däl-de, "kompaniýanyň ýeri boýunça" salgytlar → komplayens ýalňyşlyklary.
Jikme-jikliksiz invoýslar → müşderiler bilen jedeller.
Hiç hili reconciliation arasynda usage, PSP, invoys → hasabatda gapma-garşylyklar.

Jemi

API üçin güýçli billing - meteringiň wakalaryň arhitekturasy, aýdyň baha-buky, berk idempotentlik, salgytlar bilen dogry maýa goýum/FX we aç-açan hasabat. Ulanyşy girdeji bilen baglanyşdyryň, müşderä düşnükli jikme-jiklikleri beriň we wakadan invoýsa we MRR-daşborda çenli ähli ýoly awtomatlaşdyryň. Bu bolsa öňünden aýdyp boljak girdejileri, az jedelleri we önümiň dolandyrylýan ykdysadyýetini üpjün eder.