एपीआई बिलिंग और रिपोर्टिंग

1) एपीआई के लिए खुद की बिलिंग क्यों

पारदर्शी मुद्रीकरण: उपयोग लिंक → राजस्व।

स्केलेबिलिटी और नियंत्रण: योजनाओं के अनुसार कोटा, ओवरराइड, ऋण, मूल्य पुस्तक।

वित्तीय सटीकता: कर/वैट, बहुसांस्कृतिक, कार्य और समापन दस्तावेज।

ग्राहक ट्रस्ट: विस्तृत उपयोग रिपोर्ट, वेबहूक, स्व-सेवा पोर्टल।

2) बिलिंग वास्तुकला (उच्च-स्तरीय)

निर्माता (एपीआई गेटवे, सेवाएं) → उपयोग इवेंट बस (काफ्का/कतार) → मीटरिंग और रेटिंग → बिलिंग डीबी → चालान/कर → भुगतान (पीएसपी) → रिपोर्टिंग डीडब्ल्यूएच → क्लाइंट पोर्टल/वेबहूक।

• मीटरिंग - उपयोग का संग्रह और सामान्यीकरण (अनुरोध, ऋण, मात्रा)।
• मूल्य बही/योजना के अनुसार घटना की लागत का मूल्यांकन।
• चालान - अवधि, लाभ, करों, छूट, क्रेडिट के लिए एकत्रीकरण।
• भुगतान - राइट-ऑफ/रिफंड, डेटिंग (डायनिंग)।
• रिपोर्टिंग - एमआरआर/एआरपीयू/एलटीवी, कोहॉर्ट मंथन, लागत से सेवा।
• लेखा परीक्षा - पहचान, अपरिवर्तित लॉग।

3) इकाइयाँ और पहचानकर्ता

खाता (किरायेदार), योजना, अधिकार, उपयोग कार्यक्रम, चालान, क्रेडिट नोट, कर प्रोफ़ाइल।

महत्वपूर्ण: 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
}

नियम: घटनाओं को केवल जोड़ा जाता है; संपादन - 'घटना _ आईडी' के संदर्भ में सुधारात्मक समायोजन घटनाओं के माध्यम से।

5) भंडारण और एकत्रीकरण परत

5. 1 OLTP (बिलिंग DB)

Таблицы: : 'किरायेदार', 'योजना', 'प्लान _ कीमतें', 'हकदारी', 'उपयोग _ इवेंट्स', 'रेटेड _ लाइन्स', 'चालान _ लाइन्स', 'टैक्स _ रेट्स', 'क्रेडिट', 'भुगतान', 'रिफंड्स'।

5. 2 DWH (एनालिटिक्स)

Факты: 'f _ usage', 'f _ billing', 'f _ paments'; आयाम: 'डी _ किरायेदार', 'डी _ प्लान', 'डी _ एंडपॉइंट', 'डी _ रीजन', 'डी _ डेट'।

5. SQL एकत्रीकरण उपयोग का 3 उदाहरण - बिल लाइनें

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. हस्ताक्षर और प्रकाशन, भुगतान (पीएसपी), वेबहूक के लिए भेजना।

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) कर और मल्टीक्यूरेंसी

वैट/वैट/जीएसटी: टैक्स प्रोफाइल (देश, वैध वैट-आईडी, बी 2 बी/बी 2 सी) रखें।

तिथि (संस्करण) द्वारा कर दरें, यूरोपीय संघ बी 2 बी के लिए रिवर्स चार्ज।

एफएक्स रूपांतरण: चालान तिथि (ईआरयू/प्रदाता) पर दर, दर का स्रोत रखें।

दस्तावेज़: चालान, क्रेडिट नोट, डेबिट नोट - संख्या और श्रृंखला के साथ।

9) भुगतान, डेटिंग और विवाद

PSP (स्ट्राइप/ब्रेंट्री/Adyen): टोकन भुगतान, मना करने पर पीछे हटना, डायनिंग (1-3-7 दिन)।

विवाद/चार्जबैक: क़ानूनों को ठीक करना, एक चालान से जुड़ ना, बातचीत की समयरेखा।

Refunds: आंशिक/पूर्ण, 'भुगतान _ id' और 'invoice _ id' से जुड़ा।

धोखाधड़ी के संकेत: भू/एएसएन विसंगतियां, उपयोग फटना, बिलिंग में विभिन्न कार्ड - झंडे।

10) क्रेडिट, छूट, एसएलए क्रेडिट

प्रोमो ऋण (बटुआ), एसएलए के उल्लंघन के लिए सेवा क्रेडिट (अगली अवधि में ऑटो शुरू)।

कूपन: निश्चित/ब्याज, न्यूनतम अवधि, योजना/समापन बिंदुओं पर प्रतिबंध।

पारदर्शिता: पोर्टल में ऋण के संतुलन और राइट-ऑफ का इतिहास दिखाया गया है।

11) पहचान और समायोजन

सभी Idempotency-Key के माध्यम से संचालन लिखते हैं

समायोजन - केवल समायोजन घटनाओं (सकारात्मक/नकारात्मक) के माध्यम से, मूल को संपादित किए बिना।

सुलह: उपयोग का दैनिक सत्यापन ↔ rated_lines ↔ चालान ↔ PSP।

12) सुरक्षा और अनुपालन

HMAC/JWT हस्ताक्षर प्रवेश द्वार से घटनाओं का उपयोग करते हैं।

निगलने के लिए mTLS, प्रति वातावरण व्यक्तिगत कुंजी (prod/stage)।

पीआईआई न्यूनतम (पैन/मेल को अनावश्यक रूप से संग्रहीत न करें), डीएसएआर/लीगल होल्ड।

वित्तीय लेनदेन के लिए ऑडिट-लॉग अपरिवर्तनीय (एपेंड-केवल)।

13) बिलिंग पोर्टल एपीआई (ओपन एपीआई टुकड़े)

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"

मुख्य एपीआई प्रतिक्रियाओं में हेडर 'एक्स-कोटा-शेष', 'एक्स-रेटलिमिट-शेष', 'एक्स-उपयोग-अवधि' हैं।

14) वेबहूक और बिलिंग इवेंट्स

घटनाएँ: 'चालान। बनाया ',' चालान। अंतिम रूप दिया ',' भुगतान। सफल 'फेल', 'डायनिंग। रीट्री ',' क्रेडिट। लागू ',' विवाद। खोला गया 'क्लोज्ड'।

आवश्यकताएं: वेबहूक का हस्ताक्षर, बैकऑफ के साथ पुनरावृत्ति, 'डिलीवरी _ आईडी' द्वारा डीडुप्लिकेशन।

15) रिपोर्टिंग और व्यापार मैट्रिक्स

• MRR/ARR (प्लान/जियो सेगमेंटेशन), ARPU, LTV/CAC, चुरन (लोगो/राजस्व), नेट रेवेन्यू रिटेंशन (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) डेवेक्स: सेल्फ-सर्विस पोर्टल

पंजीकरण, योजना, कुंजी, उपयोग रेखांकन, चालान (पीडीएफ/जेएसएन), वेबहूक।

उन्नयन/डाउनग्रेड, चालान पूर्वावलोकन (प्रो-फॉर्मा), भुगतान विधि प्रबंधन।

सूचनाएं: "कोटा <10%", "ओवररिज शामिल", "" चालान जारी/भुगतान "।

17) परीक्षण और पर्यावरण

सैंडबॉक्स बिलिंग: डमी पीएसपी, परीक्षण कर दरें।

उपयोग की घटनाओं के अनुबंध परीक्षण (स्कीमा/आवश्यक क्षेत्र)।

हरिण, मूल्य बीच प्रतिगमन परीक्षणों में रीप्ले प्रोड नमूने।

बैकफिल सुरक्षित है: केवल पहचान के साथ बैच-इनगेस्ट के माध्यम से।

18) फिनोप्स और टैरिफ के अर्थशास्त्र

समापन बिंदुओं/योजनाओं पर मार्जिन पर विचार करें: राजस्व − लागत-से-सेवा।

ऋण और कम स्तरों में सीमित करने के लिए "महंगा" संचालन आवंटित करें।

वेधशाला में क्वेरी-लागत की निगरानी करें और बिलिंग के लिए लिंक करें।

19) चेकलिस्ट लॉन्च करें

• 'usage _ event '/' adjustment '/' invoice _ line' schemes प्रतिबद्ध और versioned हैं।
• मूल्य पुस्तक परीक्षण (फ्लैट/टियर/वॉल्यूम), prorate/override सही।
• अंतर्ग्रहण और वेबहूक की पहचान, ऑडिट-लॉग एपेंड-केवल।
• कर/वैट/एफएक्स सही, ग्राहक प्रोफाइल में भरा।
• पोर्टल: उपयोग, चालान, क्रेडिट, वेबहूक; पीएसपी एकीकरण और डायनिंग।
• DWH रिपोर्टिंग (MRR/ARPU/LTV/Churn/NRR), प्रतिदिन सुलह।
• एसएलए क्रेडिट और विवाद नीतियों का दस्तावेजीकरण किया जाता है।

20) बार-बार त्रुटियां और विरोधी पैटर्न

कोई पहचान नहीं - डुप्लिकेट उपयोग/डबल राइट-ऑफ।

भारी समापन बिंदुओं के लिए ऋण के बिना मूल्य "अनुरोध के बारे में" - नकारात्मक मार्जिन।

कर "कंपनी के स्थान पर", ग्राहक नहीं - अनुपालन त्रुटियां।

विस्तार के बिना चालान - ग्राहक विवाद।

usage↔PSP↔invoysy → रिपोर्टिंग विसंगतियों के बीच कोई सुलह नहीं।

कुल

एपीआई के लिए मजबूत बिलिंग इवेंट-चालित पैमाइश आर्किटेक्चर, स्पष्ट मूल्य पुस्तक, सख्त पहचान, सही कर/एफएक्स चालान और पारदर्शी रिपोर्टिंग है। राजस्व के लिए लिंक उपयोग, ग्राहक को स्पष्ट विवरण दें और पूरी यात्रा को स्वचालित करें - घटना से चालान तक एमआरआर डैशबोर्ड। यह अनुमानित आय, कम विवाद और एक प्रबंधनीय उत्पाद अर्थव्यवस्था प्रदान करेगा।