Ҳисобот ва ҳисоботдиҳии API

1) Чаро биллинги худ барои API

Монетизатсияи шаффоф: пайванди истифодаи → даромад.
Миқёс ва назорат: квотаҳо, барзиёд пардохт кардан, қарзҳо, китоби нархҳо тибқи нақшаҳо.
Дақиқии молиявӣ: андозҳо/андоз аз арзиши иловашуда, бисёрҷониба, санадҳо ва ҳуҷҷатҳои пӯшида.
Боварӣ ба муштариён: ҳисоботҳои муфассал оид ба истифодабарӣ, веб-китобҳо, портали худхоҳона.

2) Меъмории биллинг (сатҳи баланд)

Истеҳсолкунандагон (дарвозаи API, хидматҳо) → Истифодабарии Event Bus (Kafka/Queue) → Баҳодиҳӣ ва рейтинг → Биллинг DB → Ҳисобкунӣ/Андозҳо → Пардохтҳо (PSP) → Ҳисоботдиҳии DWH → Портали мизоҷон/Вебхукҳо.

• Ченкунӣ - ҷамъоварӣ ва ба эътидол овардани истифодаи (дархостҳо, қарзҳо, ҳаҷмҳо).
• Рейтинг - баҳодиҳии арзиши чорабинӣ аз рӯи нарх/нақша.
• Ҳисобнома-фактура - ҷамъбасти давра, фоида, андоз, тахфиф, қарз.
• Пардохтҳо - аз ҳисоб баровардан/ислоҳ кардан, шиносоӣ (дуннинг).
• Ҳисобот - MRR/ARPU/LTV, churn cohort, хароҷот барои хидмат.
• Аудит - idempotence, гузоришҳои бетағйир.

3) Субъектҳо ва идентификаторҳо

Ҳисоб (иҷорагир), Нақша, Ҳуқуқҳо, Чорабинии истифода, Ҳисобнома-фактура, Эзоҳи қарзӣ, Профили андоз.
Vital: idempotency_key истифода/ҳисобнома/пардохт, манбаъ (дарвоза/партия), версияи схемаи ҳодиса.

4) Ҳодисаи истифода: нақшаи истинод

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'.

5) Қабати нигаҳдорӣ ва агрегатсия

5. 1 OLTP (Биллинги DB)

Таблицы: 'иҷорагирон', 'нақшаҳо', 'нақша _ нархҳо', 'ҳуқуқҳо', 'истифодаи _ чорабиниҳо', 'rated _ lines', 'ҳисобнома-фактураҳо', 'ҳисобнома-фактураҳо', 'андозҳо', 'қарзҳо', 'пардохтҳо', 'баҳсҳо'.

5. 2 DWH (таҳлил)

Факты: 'f _ usage', 'f _ billing', 'f _ payments'; андозаҳо: 'd _ иҷорагир', 'd _ plan', 'd _ endpoint', 'd _ region', 'd _ date'.

5. 3 Намунаи истифодаи агрегатсияи SQL → хатҳои ҳисобшуда

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) Китоби нарх ва рейтинг (рейтинг)

Моделҳои дастгирӣ: ҳамвор, сатҳӣ, ҳаҷм, қарзҳои бастабандишуда, пардохти музди меҳнат ва бекор кардани он.

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. Давраи буриш (аз рӯи маҳал).

2. Нархгузорӣ дар нақшаи синфи боло/поён (рӯзона).

3. Рейтинги истифода + хатҳои ҳисобнома-фактура.

4. Андозҳо (ААИ/ГСТ) аз рӯи ҷойгиршавӣ ва нуқтаи хидматрасонии муштариён.

5. Қарзҳо/тахфифҳо/купонҳо.

6. Имзо ва нашр, фиристодани пардохт (PSP), webhooks.

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) Андозҳо ва бисёрҷониба

ААИ/ААИ/ГСТ: Профили андозро нигоҳ доред (кишвар, ААИ-ID, B2B/B2C).
Меъёрҳои андоз аз рӯи сана (версия), пардохти баръакс барои ИА B2B.
Табдили FX: меъёри санаи ҳисобнома-фактура (ERU/провайдер), манбаи меъёрро нигоҳ доред.
Ҳуҷҷатҳо: ҳисобнома-фактура, қайди кредитӣ, қайди дебетӣ - бо рақамҳо ва силсилаҳо.

9) Пардохтҳо, шиносоӣ ва баҳсҳо

PSP (Stripe/Braintree/Adyen): пардохтҳои токенизатсияшуда, бозпас гирифтани радкунӣ, партофтан (1-3-7 рӯз).
Баҳсҳо/пардохтҳо: ислоҳи статусҳо, пайвастшавӣ ба ҳисобнома-фактура, ҷадвали ҳамкорӣ.
Баргардонидан: қисман/пурра, бо 'пардохт _ id' ва 'ҳисобнома-фактура _ ид' алоқаманд аст.
Сигналҳои қаллобӣ: аномалияҳои гео/ASN, буридани истифода, кортҳои гуногун - парчамҳо дар биллинг.

10) Қарзҳо, тахфифҳо, қарзҳои SLA

Қарзҳои Promo (ҳамён), қарзҳои хидматрасонӣ барои вайрон кардани SLA (оғози худкор дар давраи оянда).
Купонҳо: собит/фоизҳо, мӯҳлати ҳадди ақал, маҳдудиятҳо дар нақша/нуқтаҳои ниҳоӣ.
Шаффофият: дар портал бақияи қарзҳо ва таърихи аз ҳисоб бароварданро нишон медиҳад.

11) Номутобиқатӣ ва тасҳеҳот

Ҳама амалиётро тавассути Idempotency-Key менависанд.
Тасҳеҳот - танҳо бо роҳи тасҳеҳи воқеаҳо (мусбат/манфӣ), бе таҳрири аслӣ.
Муқоиса: тафтиши ҳаррӯзаи истифода ↔ rated_lines ↔ ҳисобнома-фактураҳо ↔ PSP.

12) Бехатарӣ ва риояи

Рӯйдодҳои истифодаи имзои HMAC/JWT аз дарвоза.
MTLS барои ворид кардан, калидҳои инфиродӣ дар як муҳит (prod/stage).
Ҳадди ақалл кам кардани PII (PAN/почтаро нолозим нигоҳ надоред), DSAR/Hold Legal.
Аудит-журнал барои амалиёти молиявӣ бетағйир (танҳо замима карда мешавад).

13) Портали биллингии API (порчаҳои Open

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-Remain', 'X-Rate

14) Чорабиниҳои веб ва биллинг

Ҳодисаҳо: 'ҳисобнома-фактура. офаридааст ',' ҳисобнома. ба итмом расонида шуд ',' пардохт. муваффақ шуд ​ ​ 'failed', 'dunning. retry ',' қарз. татбиқ ',' баҳс. кушода 'кушода'.
Талабот: имзои webhooks, такрор бо бозгашт, такрорӣ аз ҷониби 'delivery _ id'.

15) Нишондиҳандаҳои ҳисоботдиҳӣ ва тиҷорат

• MRR/ARR (нақша/сегментатсияи гео), ARPU, LTV/CAC, Churn (лого/даромад), Нигоҳдории даромади холис (NRR).
• Истифодаи → Даромад: кортҳои табдили мушкилот (дар куҷо онҳо ба квота дохил мешаванд).
• Арзиши хидматрасонӣ: арзиши инфрасохтор/дархост → маржа аз рӯи нақшаҳо.

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) Dev 'Ex: Портали худидоракунии хидматрасонӣ

Бақайдгирӣ, нақшаҳо, калидҳо, графикҳои истифода, ҳисобномаҳо (PDF/JSON), веб-китобҳо.
Навсозӣ/коҳиш, пешнамоиши ҳисобнома-фактура (pro-forma), идоракунии усули пардохт.
Огоҳиҳо: "квота <10%", "overidge дохил карда шудааст", "ҳисобнома-фактура дода/пардохта шудааст".

17) Озмоиш ва муҳити зист

Биллинги Sandbox: PSP-ҳои dummy, меъёрҳои андоз.
Санҷишҳои шартномавии рӯйдодҳои истифода (схема/майдонҳои зарурӣ).
Такрори намунаҳои prod дар stag, санҷишҳои регрессияи нархҳо.
Backfill бехатар аст: танҳо тавассути бастабандӣ бо idempotency.

18) Финопсияҳо ва иқтисодиёти тарифҳо

Маржаро дар нуқтаҳои ниҳоӣ/нақшаҳо баррасӣ кунед: даромад − хароҷот барои хидмат.
Амалиёти "гарон" -ро ба қарзҳо ҷудо кунед ва дар сатҳи паст маҳдуд кунед.
Арзиши дархостро дар мушоҳидаҳо назорат кунед ва ба биллинг пайваст кунед.

19) Рӯйхати назоратӣ оғоз кунед

• 'Wusage _ event '/' тасҳеҳ '/' ҳисобнома-фактура _ line' schemes содир ва санҷида мешавад.
• Китоби нархҳо санҷида шуд (ҳамвор/сатҳӣ/ҳаҷм), пешакӣ/тағир додан дуруст.
• Номутобиқатии воридшавӣ ва веб-китобҳо, танҳо аудит-журнал.
• Андоз/ААИ/FX дуруст, профилҳои муштариён пур карда шудаанд.
• Портал: истифода, ҳисобнома-фактураҳо, қарзҳо, вебхукҳо; Интегратсияи PSP ва dunning.
• Ҳисоботи DWH (MRR/ARPU/LTV/Churn/NRR), оштӣ ҳар рӯз.
• Сиёсати қарзӣ ва баҳсҳои SLA ҳуҷҷатгузорӣ карда мешаванд.

20) Хатогиҳои зуд-зуд ва зидди намунаҳо

Не idempotency → истифодаи такрорӣ/аз ҳисоб баровардани дукарата.
Нархи "дар бораи дархост" бидуни қарз барои нуқтаҳои ниҳоӣ → маржаи манфӣ.
Андозҳо "дар ҷои ширкат", на хатогиҳои муштарӣ → мувофиқат мекунанд.
Ҳисобнома-фактураҳо бидуни тафсилот → баҳсҳои муштариён.
Ягон мусолиҳа байни ихтилофҳои гузоришдиҳандаи usage↔PSP↔invoysy → вуҷуд надорад.

Ҷамъ

Ҳисоббаробаркунии қавӣ барои API ин меъмории андозагирии рӯйдодҳо, китоби возеҳи нархҳо, idempotence қатъӣ, ҳисобкунии дурусти андоз/FX ва ҳисоботи шаффоф мебошад. Истифодаи пайванд ба даромад, ба муштарӣ тафсилоти возеҳ диҳед ва тамоми сафарро автоматӣ кунед - аз ҳодиса то ҳисобнома-фактура то панели MRR. Ин даромадҳои пешгӯишаванда, баҳсҳои камтар ва иқтисоди идорашавандаи маҳсулотро таъмин хоҳад кард.