Բիլինգ API և հաշվետվություններ

1) Ինչո՞ ւ է API-ի համար սեփական բիլինգը

Թափանցիկ մետաղադրամներ 'usage-ի կապը ֆինանսական եկամուտները։

Ներբեռնումը և վերահսկումը 'քվոտաներ, overage, վարկեր, ռուսական բուք պլանների վրա։

Ֆինանսական ճշգրտությունը 'հարկեր/ԱԱՀ, ակտիվություն, գործողություններ և փակող փաստաթղթեր։

Հաճախորդների վստահությունը 'մանրամասն usage հաշվետվությունները, webhuks, ինքնաարտադրության պորտալը։

2) Բիլինգի ճարտարապետությունը (բարձր մակարդակի)

Meders (API-կողպեքներ, ծառայություններ) wwww.Usage Event Bus (Kafka/Queue) no Metering & Rating no Billing DB Notoicing/Taxes to Payments (PBS RRRRLoWowER T owER CORT TINCCCO CCCO ORCCORT CCCO CO ORT CORT CtORT bhooks.

Բաղադրիչները

Metering-ը usage-ի հավաքումն ու նորմալացումն է (հարցումներ, վարկեր, ծավալներ)։

Վարկանիշը (rating) իրադարձության արժեքի գնահատումն է ռուսական բուկի/պլանի վրա։

Invoising-ը միավորում է ժամանակահատվածի, թռիչքի, հարկերի, զեղչերի, վարկերի համար։

Վճարումները/refands, dainting (dunning)։

Հաշվետվությունները 'MRR/ARPU/LTV, կոորդինատոր churn, cost-to-serve։

Աուդիտը գաղափարախոսություն է, անփոփոխ ամսագրեր։

3) Էության և ցուցանիշների մասին

Account (tenae), Plan, Entitlements (թույլտվություններ/քվոտաներ), Usage Event, Deloice, Credit Note, Tax Profile։

Կենսական կարևոր է 'idempotency _ key usage/www.oice/pay.ru, 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
}

Կանոնները 'իրադարձությունները միայն ավելացվում են։ ուղղություններ 'ուղղիչ adjustronevents միջոցով, հղում «event _ id»։

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 CPH (վերլուծություն)

Факты: `f_usage`, `f_billing`, `f_payments`; չափումներ ՝ d _ tenault ', «d _ plan», «d _ endpoint», «d _ region», «d _ date»։

5. 3 SQL միավորման օրինակ usage www.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) Medis buk և rating (գնահատական)

Աջակցեք մոդելներին 'flat, tiered, volume, bundled credits, as-all-go, ինչպես նաև overage։

Օրինակ ռուսական s-buka (YAML)

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) Invoising 'հաշիվների ձևավորում

Փուլերը

1. Cutoff ժամանակահատվածը (լոկալ հաշիվով)։

2. Պրորետը պլանի p/down-graide-ում (օր)։

3. Usage + աղյուսակը dioice lines։

4. Հարկերը (VAT/GST) հաճախորդի տեղավորման և ծառայությունների տրամադրման վայրի վրա։

5. Վարկեր/զեղչեր/կտրոններ։

6. Ստորագրումը և հրապարակումը, վճարման ուղարկումը (PSA), webhuks։

Invois-line (օրինակ)

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-ի համար ԵՄ-ում։

FX-կոնվերսիա 'ինվոիսի ամսաթվի դասընթացը (ESV/պրովայդեր), պահեք դասընթացի աղբյուրը։

Փաստաթղթերը ՝ invois, credit note, դեբետային նոտա 'համարներով և շարքերով։

9) Վճարումներ, դեյթինգ և բանավեճեր

PMS (Strone/Braintree/Adyen): tokenized վճարումներ, retray, երբ մերժում է, dunning (1-3-7 օր)։

Proputes/chargebacks: Ստատուսների ամրագրում, ինվոիսի միակցիչ, փոխազդեցության թայմլայնը։

Refunds: մասնակի/ամբողջական, կապված են «payment _ id» և «www.oice _ id» հետ։

Ֆրոդի ազդանշաններ 'geo/ASN-anomali, usage, տարբեր քարտեզներ' դրոշներ բիլինգում։

10) Վարկեր, զեղչեր, SLA վարկեր

Պրոմո վարկերը (դրամապանակներ), որոնք պարունակում են credits SLA-ի խախտման համար (մեքենան հետևում է ժամանակահատվածին)։

Կուպոնները ՝ ֆիքս/տոկոս, նվազագույն ժամանակահատվածը, սահմանափակումները պլանի/էնդպոինտամների վրա։

Թափանցիկություն 'պորտալում ցույց տվեք վարկերի հավասարակշռությունը և հանման պատմությունը։

11) Idempotenty և Windows

Բոլոր write վիրահատությունները Idempotency-Key-ի միջոցով։

Մոսկվան միայն adjustments (դրական/բացասական) իրադարձությունների միջոցով է, առանց բնօրինակի աջ։

Reconciliation: Usage dementrated _ lines-ի ամենօրյա իջեցումը PSA-ն է։

12) Անվտանգություն և ընկերակցություն

HMAC/JWT ստորագրությունը usage իրադարձությունների ստորագրությունը նավից։

MTSA-ի համար, առանձին բանալիներ չորեքշաբթի (07/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-Delta-Remaining», «X-Rance Limit-Remaining», «X-Usage-Period»։

14) Webhuki-ը և բիլինգի իրադարձությունները

Իրադարձությունները '<www.oice։ created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.

Պահանջները 'webhuks ստորագրություն, backoff, dedivery _ id։

15) Բիզնեսի հաշվետվությունները և չափումները

Ֆիննական KPI

MRR/ARR (պլանների/գեոյի հատվածներ), ARPU, LTV/CAC, Churn (ձախ/եկամուտ), Net Revenue Retention (NRR)։

Usage Windows Revenue: «նեղ տեղերի» փոխակերպման քարտեզները (որտեղ հենվում են քվոտաների մեջ)։

Cost-to-Serve: ենթակառուցվածքի/հարցման արժեքը պլանների վրա։

Հարցումների օրինակներ (MSH)

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 գրաֆիկներ, invoiss (PDF/JSON), webhuks։

Apgreid/dungraid, հաշիվների կանխատեսող (71-71 ա), վճարման մեթոդների կառավարում։

Ծանուցումներ ՝ «քվոտա <10 տոկոսը», «overidge», «invois-ը տեղադրված է/վճարված»։

17) Փորձարկում և շրջապատում

Sandbox Biling: ֆիքսված PBS, հարկերի թեստային տոկոսադրույքներ։

Usage-իրադարձությունների թեստերը (սխեմա/պարտադիր դաշտեր)։

Replay prod-semple-ը ստագում, ռեգրեսիայի թեստերը www.s-buka։

Backfill ապահով է, միայն batch-ingest-ի միջոցով 'idempotenty-ով։

18) Ֆինոպսը և սակագների տնտեսությունը

Համարեք մարժա էնդպոինթամ/պլաններ 'revenue no cost-to-serve։

Հատկացրեք վարկերի «թանկ» վիրահատությունները և սահմանափակեք low-tiers-ում։

Դիտարկեք query-cost Observability-ում և կապեք բիլինգի հետ։

19) Չեկի թուղթ

• «Usage _ event »/« adjustrone »/« deporoice _ 2019» սխեմաները գրված և տարբերակվում են։
• Masts-Book-ը փորձարկվել է (flat/tiered/volume), prorate/overage ճիշտ։
• Ingestion և webhuks, append-only աուդիտ-լոգ։
• Հարկեր/ԱԱՀ/FX ճիշտ են, հաճախորդների պրոֆիլները լցված են։
• Պորտալ ՝ usage, invoiss, վարկեր, webhuks; PMS ինտեգրումը և dunning։

• SLA վարկերի և բանավեճերի քաղաքականությունը մեկնաբանվում է։

[MSH զեկույցները (MRR/ARPU/LTV/Churn/NRR), ամեն օր reconciliation։

20) Հաճախակի սխալներ և հակատիպեր

Ոչ մի կուռք չկա, ոչ էլ usage/կրկնակի ապամոնտաժում։
«Հարցման» հետ առանց վարկերի ծանր էնդպոինտների համար բացատրվում է բացասական մարժա։
Հարկերը «ընկերության տեղում», և ոչ թե հաճախորդը բացատրում են կոմպլանսի սխալները։
Invoiss-ը առանց մանրամասն քննարկումների հաճախորդների հետ։
Գոյություն չունի reconciliation usage www.PBS-ի միջև invoiss-ի տարբերությունը հաշվետվություններում։

Արդյունքը

API-ի համար ուժեղ բիլինգը մետերինգի իրադարձական ճարտարապետությունն է, պարզ ալգորիթմ, խիստ գաղափարախոսություն, հարկերի հետ ճիշտ ինվազինգ/FX և թափանցիկ հաշվետվություններ։ Միացրեք usage-ը եկամուտների հետ, թույլ տվեք հաճախորդին հասկանալ մանրամասները և ավտոմատացնել ամբողջ ճանապարհը 'իրադարձությունից մինչև ինվոիս և MRR-dashbord։ Սրանք կանխատեսելի եկամուտներ են, ավելի քիչ բանավեճեր և կառավարվող ապրանքի տնտեսությունը։