Биллинг API жана отчеттуулук

1) Эмне үчүн өз биллинг үчүн API

Ачык акча табуу: байланыш usage → киреше.
Scaling & Control: квота, 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.
Маанилүү: idempotency_key usage/invoice/payment, source (gateway/batch), version окуя схемасы.

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

КНС/VAT/GST: Салык профилин (өлкө, VAT-ID, B2B/B2C) сактаңыз.
датасы боюнча салыктык чендер (версия), ЕБде B2B үчүн reverse charge.
FX-Conversion: Invoys датасы боюнча курс (ECB/провайдер), курстун булагын сактаңыз.
Документтер: инвойс, credit note, дебет-нота - номерлери жана сериялары менен.

9) Төлөмдөр, дейтинг жана талаш-тартыштар

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

10) Кредиттер, арзандатуулар, SLA-кредиттер

Промо-кредиттер (капчык), SLA бузгандыгы үчүн service credits (кийинки мезгилде AutoNet).
Купондор: фикс/пайыз, минималдуу мөөнөт, план/эндпоинттер боюнча чектөөлөр.
Ачык-айкындуулук: порталда кредиттердин балансын жана эсептен чыгаруу тарыхын көрсөтүңүз.

11) Демпотенттүүлүк жана оңдоолор

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

12) Коопсуздук жана комплаенс

HMAC/JWT кулпусу кулпусу-окуялар.
mTLS үчүн ingest, айлана-чөйрөгө өзүнчө ачкычтар (prod/этап).
PII-минималдаштыруу (зарылчылыгы жок PAN/почта сактоо эмес), DSAR/Юридикалык 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 (logo/кирешелүү), 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), вебхактар.
Upgrade/downgrade, алдын ала эсеп (pro-форма), төлөм ыкмаларын башкаруу.
Билдирүүлөр: "квота <10%", "оверидж киргизилген", "инвойс коюлган/төлөнгөн".

17) Сыноо жана айлана-чөйрө

Sandbox биллинг: жасалма PSP, тесттик салык чендер.
Contract-тесттер usage-окуялар (схема/милдеттүү талаалар).
реплика прод-үлгүлөрү, регрессия тесттер баа букту.
Backfill коопсуз: бир гана демпотенттик менен batch-ingest аркылуу.

18) FinOps жана экономика

revenue − cost-to-serve.
Кредиттерге "кымбат" операцияларды бөлүп, low-tiers менен чектеңиз.
Observability query-cost мониторинг жана биллинг менен байланышкан.

19) Чек тизмеси ишке киргизүү

• Схемалар 'usage _ event '/' adjustment '/' invoice _ line' жазылган жана версияланган.
• Прайс-бук сыналган (flat/tiered/volume), prorate/overage туура.
• Idempotentity ingestion жана Webhook, аудит-log append-only.
• Салыктар/КНС/FX туура, кардарлардын профилдери толтурулган.
• Портал: usage, инвойстор, кредиттер, вебхактар; PSP бириктирүү жана dunning.
• DWH отчеттуулук (MRR/ARPU/LTV/Churn/NRR), reconciliation күн сайын.
• SLA кредиттердин жана талаш-тартыштардын саясаты документтештирилген.

20) Тез-тез каталар жана анти-үлгүлөрү

Эч кандай демпотенттик → double usage/кош эсептен чыгаруу.
Баасы "суроо-талап жөнүндө" оор enpoints үчүн кредиттер жок → терс маржа.
Салыктар "компаниянын орду боюнча" эмес, кардар → комплаенс каталары.
майда-чүйдөсүнө чейин жок Invoys → кардарлар менен талаш.
Жок reconciliation ортосунда usage, PSP, Invoys → отчетто айырмачылыктар.

Жыйынтык

API үчүн күчтүү биллинг - бул иш-чаранын метеринг архитектурасы, так баа букту, катуу демпотенттик, салыктар менен туура инвойсинг/FX жана ачык-айкын отчеттуулук. Колдонууну киреше менен байланыштырыңыз, кардарга түшүнүктүү деталдарды бериңиз жана бардык жолду автоматташтырыңыз - окуядан инвойска жана MRR-дашбордго чейин. Бул алдын ала кирешелерди, азыраак талаш-тартыштарды жана продуктунун башкарылуучу экономикасын камсыз кылат.