API биллингі және есептілік

1) Неліктен API үшін жеке биллинг

Мөлдір монетизация: байланыс usage → түсім.
Скалдаушылық және бақылау: квоталар, overage, кредиттер, жоспарлар бойынша прайс-бук.
Қаржылық дәлдігі: салықтар/ҚҚС, мультивалюталық, актілер және жабатын құжаттар.
Клиенттердің сенімі: егжей-тегжейлі usage-есептер, вебхактар, өзіне-өзі қызмет көрсету порталы.

2) Биллинг архитектурасы (жоғары деңгейлі)

Producers (API-шлюз, қызметтер) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Клиент порталы/Webhooks.

• Метеринг - usage жинау және қалыпқа келтіру (сұрау салулар, кредиттер, көлемдер).
• Рейтинг (rating) - прайс-бук/жоспар бойынша оқиғаның құнын бағалау.
• Инвойсинг - кезең үшін агрегация, прорейт, салықтар, жеңілдіктер, кредиттер.
• Төлемдер - есептен шығару/рефанд, дейтинг (dunning).
• Есептілік - MRR/ARPU/LTV, когорт churn, cost-to-serve.
• Аудит - теңсіздік, өзгермейтін журналдар.

3) Мәні және сәйкестендіргіштері

Account (tenant), Plan, Entitlements (рұқсаттар/квоталар), Usage Event, Invoice, Credit Note, Tax Profile.
Өмірлік маңызы бар: оқиғаның usage/invoice/payment, source (gateway/batch), version схемаларына idempotency_key.

4) Тұтыну оқиғасы (usage): эталондық схема

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
}

Ережелер: оқиғалар тек қосылады; түзетулер - 'event _ id' сілтемесі бар түзетуші adjustment events арқылы.

5) Сақтау орны және агрегация қабаты

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 (талдау)

Факты: `f_usage`, `f_billing`, `f_payments`; 'd _ tenant', 'd _ plan', 'd _ endpoint', 'd _ region', 'd _ date' өлшемдері.

5. 3 SQL-агрегаттау мысалы 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) Прайс-бук және rating (бағалау)

Қолдау модельдері: flat, tiered, volume, bundled credits, pay-as-you-go, сондай-ақ 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) Инвойсинг: шоттарды қалыптастыру

1. Кезеңнің cutoff (жергілікті аккаунт бойынша).

2. Жоспардың ап/даун-грейд кезіндегі прорейт (күн бойынша).

3. Рейтинг usage + белгілеу invoice lines.

4. Клиенттің орналасқан жері және қызмет көрсету орны бойынша салықтар (VAT/GST).

5. Кредиттер/жеңілдіктер/купондар.

6. Қол қою және жариялау, ақы төлеуге жіберу (PSP), вебхактар.

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) Салықтар және мультивалюталық

ҚҚС/VAT/GST: Tax Profile сақтаңыз (ел, VAT-ID, B2B/B2C валидті).
Күні (нұсқасы) бойынша салық ставкалары, ЕО-да B2B үшін reverse charge.
FX-конверсия: инвойс күніндегі бағам (ЕСВ/провайдер), бағам көзін сақтаңыз.
Құжаттар: инвойс, credit note, дебет-ноталар - нөмірлері мен сериялары бар.

9) Төлемдер, дейтинг және диспуттар

PSP (Stripe/Braintree/Adyen): tokenized төлемдер, бас тарту ретраиялары, dunning (1-3-7 күн).
Disputes/chargebacks: статусын бекіту, инвойспен байланыстыру, таймлайн әрекеттесу.
Refunds: ішінара/толық, 'payment _ id' және 'invoice _ id' байланыстырылған.
Фрод-сигналдар: гео/ASN-аномалиялар, usage жарылыстары, әртүрлі карталар - биллингтегі жалаулар.

10) Кредиттер, жеңілдіктер, SLA-кредиттер

Promo-кредиттер (әмиян), service credits SLA бұзғаны үшін (келесі кезеңдегі автосанақ).
Купондар: фикс/пайыз, ең аз мерзім, жоспар/эндпоинт бойынша шектеулер.
Ашықтық: порталда кредиттер балансын және есептен шығару тарихын көрсетіңіз.

11) Теңсіздік және түзетулер

Idempotency-Key арқылы барлық write операциялары.
Түзетулер - тек adjustments оқиғалары арқылы (оң/теріс), түпнұсқаны түзетусіз.
Reconciliation: күн сайынғы салыстыру usage, rated_lines, invoices, PSP.

12) Қауіпсіздік және комплаенс

HMAC/JWT шлюзден usage-оқиғаларының қолтаңбасы.
mTLS ingest, ортаға арналған жеке кілттер (prod/stage).
PII-минимизация (PAN/поштаны қажетсіз сақтауға болмайды), DSAR/Legal Hold.
Қаржылық операциялар үшін өзгермейтін аудит-лог (append-only).

13) Биллинг порталының API (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"

Негізгі API жауаптарындағы тақырыптар: 'X-Quota-Remaining', 'X-RateLimit-Remaining', 'X-Usage-Period'.

14) Веб-хактар және биллинг оқиғалары

Оқиғалар: 'invoice. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
Талаптар: вебхуктардың қолтаңбасы, backoff қайталауы, 'delivery _ id' бойынша дедупликация.

15) Есептілік және бизнес өлшемдері

• MRR/ARR (жоспарлар бойынша сегменттеу/гео), ARPU, LTV/CAC, Churn (логотип/кіріс), Net Revenue Retention (NRR).
• Usage → Revenue: «тар жерлерді» конверсиялау карталары (квоталарға сүйенетін).
• Cost-to-Serve: инфрақұрылым/сұраныс құны → жоспарлар бойынша маржа.

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: өзіне-өзі қызмет көрсету порталы

Тіркеу, жоспарлар, кілттер, usage-графиктер, инвойстар (PDF/JSON), вебхактар.
Апгрейд/даунгрейд, шотты алдын ала қарау (pro-forma), төлем әдістерін басқару.
Ескертулер: «квота <10%», «оверидж қосылған», «инвойс қойылды/төленді».

17) Тестілеу және қоршаған орта

Sandbox биллинг: жалған PSP, салықтың тесттік ставкалары.
Contract-тесттер usage-оқиғалар (схема/міндетті өрістер).
Стагтағы прод-сэмплдарды replay, прайс-буканың регрессиялық тестілері.
Backfill қауіпсіз: тек batch-ingest арқылы.

18) ФинОПС және тарифтер экономикасы

Маржаны эндпоинттер/жоспарлар бойынша санаңыз: revenue − cost-to-serve.
«Қымбат» операцияларды несиелерге бөліңіз және low-tiers-те шектеңіз.
Observability бағдарламасында query-cost бағдарламасын бақылап, биллингпен байланыстырыңыз.

19) Ұшырудың чек-парағы

• 'usage _ event '/' adjustment '/' invoice _ line' схемалары тіркелген және нұсқаланады.
• Прайс-бук сыналған (flat/tiered/volume), prorate/overage дұрыс.
• Ingestion және вебхуктардың ұқсастығы, append-only аудит-журналы.
• Салықтар/ҚҚС/FX дұрыс, клиенттердің профильдері толтырылған.
• Портал: usage, инвойстар, кредиттер, вебхактар; PSP интеграциясы және dunning.
• DWH-есептілік (MRR/ARPU/LTV/Churn/NRR), күнделікті reconciliation.
• SLA-кредиттер мен пікірталастардың саясаты құжатталған.

20) Жиі қателер және қарсы үлгілер

Сәйкессіздік жоқ → dubly usage/екі рет есептен шығару.
Ауыр эндпоинттер үшін кредитсіз «сұрау туралы» прайс → теріс маржа.
Клиент емес, «компанияның орны бойынша» салықтар → комплаенс қателері.
Нақтылаусыз инвойстар → клиенттермен даулар.
Жоқ reconciliation арасында usage, PSP, инвойстар → есептіліктегі алшақтықтар.

Жиынтығы

API үшін күшті биллинг - бұл метерингтің оқиғалық архитектурасы, айқын прайс-бук, қатаң демпотенттік, салықтармен дұрыс инвойсинг/FX және мөлдір есептілік. Usage-ді түсіммен байланыстырып, клиентке түсінікті бөлшектер беріп, оқиғадан инвойс пен MRR-дашбордқа дейін бүкіл жолды автоматтандырыңыз. Бұл болжамды кірістерді, аз пікірталастарды және өнімнің басқарылатын экономикасын қамтамасыз етеді.