ბილინგი API და მოხსენებები

1) რატომ არის საკუთარი ბილინგი API- სთვის

გამჭვირვალე მონეტიზაცია: საკომუნიკაციო კავშირი და შემოსავალი.
სკალირება და კონტროლი: კვოტები, გადაფარვა, სესხები, ფასების წრე გეგმებზე.
ფინანსური სიზუსტე: გადასახადები/დღგ, მულტივალუტა, აქტები და დახურვის დოკუმენტები.
მომხმარებელთა ნდობა: დეტალური შეტყობინებები, ვებჰუკები, თვითმომსახურების პორტალი.

2) ბილინგის არქიტექტურა (მაღალი დონის)

Producters (API კარიბჭე, მომსახურება), Usage Event Bus (Kafka/Queue), Metering & Rating, Billing DB, Invoicing/Taxes Payments (Payments) - ის (PeTaGuroDuRage) და RuREed DaGage DaGaGeSeSeSage (PuRed (Page) - ის Danbhooks.

• მეტერინგი - მოხმარების შეგროვება და ნორმალიზაცია (მოთხოვნები, სესხები, მოცულობა).
• რეიტინგი (ნიშანი) - ღონისძიების ღირებულების შეფასება ფასების წიფლის/გეგმის მიხედვით.
• ინვოისი - დანაყოფი პერიოდის განმავლობაში, გადაკვეთა, გადასახადები, ფასდაკლებები, სესხები.
• გადახდები - ჩამოწერები/რეფანდები, dunning.
• მოხსენებები - MRR/ARPU/LTV, კოჰორტული churn, cost-to-serve.
• აუდიტი არის idempotence, უცვლელი ჟურნალები.

3) ობიექტები და იდენტიფიკატორები

Account (tenant), Plan, Entitlements (ნებართვები/კვოტები), Usage Event, Invoice, Credit Note, Tax Profile.
სასიცოცხლოდ მნიშვნელოვანია: idempotence _ key usage/invoice/payment, source (gateway/batch), ღონისძიების სქემის ვერსია.

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
}

წესები: მოვლენები მხოლოდ ემატება; რედაქტორები - მაკორექტირებელი adjustment events მითითებით '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 DWH (ანალიტიკა)

Факты: `f_usage`, `f_billing`, `f_payments`; გაზომვები: 'd _ tenant', '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) ფასების წრე და რბოლა (შეფასება)

მხარი დაუჭირეთ მოდელებს: flat, tiered, volume, bundled credits, გადახდა-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. მარშრუტი ap/down grade გეგმის (დღის განმავლობაში).

3. Usage რეიტინგი + ინვოისის ხაზების დაფიქსირება.

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).
საგადასახადო განაკვეთები თარიღისთვის (ვერსიები), reverse charge ევროკავშირში B2B- სთვის.
FX კონვერტაცია: კურსი ინვოისის თარიღამდე (ESV/პროვაიდერი), შეინახეთ კურსის წყარო.
დოკუმენტები: ინვოისი, კრედიტი ნოტი, სადებიუტო ნოტა - ნომრებით და სერიებით.

9) გადახდა, დეიტინგი და დებატები

PSP (Stripe/Braintree/Adyen): tokenized გადახდები, retrai უარის თქმის დროს, dunning (1-3-7 დღე).
Disputes/chargebacks: სტატუსის დაფიქსირება, ინვოისთან დაკავშირება, ურთიერთქმედების დრო.
Refunds: ნაწილობრივი/სრული, უკავშირდება 'payment _ id' და 'invoice _ id'.
ფროიდის სიგნალები: გეო/ASN ანომალიები, აურზაური, სხვადასხვა ბარათები - დროშები ბილინგში.

10) სესხები, ფასდაკლება, SLA სესხები

პრომო სესხები (საფულე), სერვისის კრედიტები SLA- ს დარღვევისთვის (ბენზინგასამართი სადგური შემდეგ პერიოდში).
კუპონები: ფიქსი/პროცენტი, მინიმალური ვადა, შეზღუდვები გეგმის/ენდოინტამის მიხედვით.
გამჭვირვალობა: პორტალში აჩვენეთ სესხების ბალანსი და ჩამოწერის ისტორია.

11) Idempotence და კორექტირება

ყველა write ოპერაცია Idempotency-Key- ის საშუალებით.
კორექტირება - მხოლოდ adjustments- ის მოვლენების საშუალებით (პოზიტიური/უარყოფითი), ორიგინალის რედაქტირების გარეშე.
რეკონსტრუქცია: ყოველდღიური შერწყმა მომაბეზრებელი - ხაზები - ინვოისები - PSP.

12) უსაფრთხოება და შესაბამისობა

HMAC/JWT ხელს აწერს სურათის მოვლენებს კარიბჭისგან.
mTLS ingest- ისთვის, ინდივიდუალური კლავიშები ოთხშაბათისთვის (mTLS/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-Éta-Remaining', 'X-RateLimit-Remaining', 'X-Usage-Period'.

14) ვებჰუკი და ბილინგის მოვლენები

მოვლენები: 'ინვოისი. created`, `invoice. finalized`, `payment. succeeded|failed`, `dunning. retry`, `credit. applied`, `dispute. opened|closed`.
მოთხოვნები: ვებჰუკების ხელმოწერა, გამეორება backoff- დან, „მიწოდების _ 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: თვითმომსახურების პორტალი

რეგისტრაცია, გეგმები, გასაღებები, სურათის გრაფიკა, ინვოისი (PDF/JSON), ვებჰუკი.
Apgrade/downgrade, ანგარიშის წინასწარი შემოწმება (pro-forma), გადახდის მეთოდების მართვა.
შეტყობინებები: „კვოტა <10%“, „ჩართულია“, „ინვოისი გამოიცემა/გადახდილი“.

17) ტესტირება და გარემო

Sandbox ბილინგი: ფიქტიური PSP, ტესტის გადასახადები.
კონტაქტური მოვლენების ტესტები (სქემა/სავალდებულო ველები).
Replay prod semples stag- ში, ფასების წიფლის რეგრესიული ტესტები.
Backfill უსაფრთხოა: მხოლოდ batch-ingest- ის მეშვეობით იდემპოტენტურობით.

18) FinOps და ტარიფების ეკონომიკა

განიხილეთ ზღვარი ენდოინტამის/გეგმების მიხედვით: revenue - cost-to-serve.
გამოყავით „ძვირადღირებული“ ოპერაციები სესხებზე და შეზღუდეთ დაბალი დონის ოპერაციები.
დააკვირდით query-cost Observability და დაუკავშირდით ბილინგს.

19) გაშვების სია

• სქემები 'usage _ event '/' adjustment '/' invoice _ line' დაფიქსირდა და განახლებულია.
• ფასების ბუკის ტესტირება (flat/tiered/volume), prorate/overage სწორია.
• Idempotention ungestion და webhuks, append-only აუდიტის ჟურნალი.
• გადასახადები/დღგ/FX სწორია, მომხმარებელთა პროფილები ივსება.
• პორტალი: დახმარება, ინვოისი, სესხები, ვებჰუკი; PSP ინტეგრაცია და დუნინგი.
• DWH ანგარიში (MRR/ARPU/LTV/Churn/NRR), ყოველდღიური რეკონსტრუქცია.
• SLA სესხებისა და დავების პოლიტიკოსები დოკუმენტირებულია.

20) ხშირი შეცდომები და საწინააღმდეგო ნიმუშები

არ არსებობს idempotention - dubles sage/ორმაგი ჩამოწერა.
ფასი „მოთხოვნის შესახებ“ სესხების გარეშე, მძიმე ენდოინტებისთვის, უარყოფითი ზღვარია.
გადასახადები „კომპანიის ადგილზე“ და არა კლიენტი - შესაბამისობის შეცდომები.
ინვოისი დეტალების გარეშე არის დავა მომხმარებლებთან.
არ არსებობს ჩანაწერების გამოქვეყნება PSP - ინვოისები ანგარიშგებაში.

შედეგი

API- სთვის ძლიერი ბილინგი არის მეტერიზაციის ღონისძიების არქიტექტურა, მკაფიო ფასების წრე, მკაცრი idempotence, სწორი ინვოისი გადასახადებით/FX და გამჭვირვალე ანგარიშგებები. დაუკავშირდით შემოსავალს, მიეცი კლიენტს გასაგები დეტალები და ავტომატიზაცია გაუწიეთ ყველა გზას - მოვლენიდან ინვოისამდე და MRR დაშბორდამდე. ეს უზრუნველყოფს პროგნოზირებადი შემოსავალი, ნაკლები დავა და პროდუქტის კონტროლირებადი ეკონომიკა.