賬單API和報告

1）為什麼API有自己的賬單

透明的貨幣化：使用關系→收入。
可攀登性和控制性：配額，覆蓋，貸款，按計劃計算的價位。
財務準確性：稅收/增值稅、多元貨幣性、契約和結賬文件。
客戶信任：詳細的用戶報告，webhooks，自助服務門戶。

2）計費架構（高級）

生產商（API網關，服務）→使用事件巴士（Kafka/Queue）→計量和評級→ Billing DB → Invoicing/Taxes → Payments（PSP）→報告DWH → 客戶端門戶/Webhooks。

• 計量-收集和正常化使用（查詢、信用、數量）。
• 評級（評級）-按價格山毛櫸/計劃估計事件成本。
• 發票-期間匯總，跨度，稅收，折扣，貸款。
• 付款-註銷/重組，代理（dunning）。
• 報告-MRR/ARPU/LTV，隊列churn，成本服務。
• 審計-相等性，不變日誌。

3）實體和標識符

Account （tenant）、Plan、Entitlements（許可/配額）、Usage Event、Invoice、Credit Note、Tax Profile。
至關重要的是：idempotency_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
}

規則：僅添加事件；編輯-通過參考「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 usage → billed lines 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、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.Proreit在up/down grade計劃中（每天）。

3.Usage評級+invoice lines固定。

4.按客戶位置和服務交付地點征稅（VAT/GST）。

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）稅收和多重貨幣性

VAT/VAT/GST：儲存稅務資料（國家，VAT-ID有效性，B2B/B2C）。
按日期（版本）計算的稅率，歐盟B2B的反向收費。
FX轉換：發票日期（ERU/提供商）的課程,存儲課程來源。
文件：發票、信用註釋、借記筆記--有數字和系列。

9）付款，代言和付款

PSP （Stripe/Braintree/Adyen）： tokenized付款,免責聲明,dunning （1-3-7天）.

Disputes/chargebacks：狀態固定、發票捆綁、交互時間線。
Refunds：部分/完整，與「payment_id」和「invoice_id」相關聯。
Frod信號：地理/ASN異常，使用爆發，不同的地圖是計費中的標誌。

10）貸款,折扣,SLA貸款

促銷學分（錢包），服務學分違反SLA（在跟蹤期間自動運行）。

優惠券： 虛假/百分比,最低期限,計劃限制/結束.

透明度：在門戶網站上顯示貸款余額和註銷歷史。

11）相容性和調整

通過Idempotency-Key進行所有寫作操作。
調整-僅通過adjustments事件（正/負），而無需編輯原始事件。
Reconciliation： usage的每日對賬↔ rated_lines ↔ invoices ↔ PSP。

12）安全和合規性

HMAC/JWT從網關簽名使用事件。
mTLS for ingest,單個鍵到環境（prod/stage）。
PII最小化（無需存儲PAN/郵件），DSAR/法律保留。
財務交易的審計日誌不可變（僅附錄）。

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-Cota-Remaining」，「X-RateLimit-Remaining」，「X-Usage-Period」。

14）Webhooks和計費活動

事件： 'invoice。created`, `invoice.finalized`, `payment.succeeded|failed`, `dunning.retry`, `credit.applied`, `dispute.opened|closed`.

要求：webhook簽名，backoff重播，「delivery_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），webhooks。
Upgrade/downgrade，帳戶預付款（pro- forma），管理付款方法。
通知：「配額<10%」，「覆蓋」，「發票/付款」。

17）測試和環境

Sandbox計費：虛構PSP，測試稅率。
使用事件合同測試（模式/必填字段）。
在舞臺上重播原生試劑盒，回歸價格山毛櫸測試。
Backfill是安全的：只有通過擊球和偶數。

18） FinOps和關稅經濟

根據殘局/計劃計算利潤：revenue −成本服務。
將「昂貴」的交易分配到貸款中,並限制在低分期付款中。
在Observability中監控查詢成本並鏈接到計費。

19）發射支票清單

• 「usage_event」/「adjustment」/「invoice_line」方案被固定並轉換。
• 價格山毛櫸經過測試（flat/tiered/volume）, prorate/overage是正確的。
• 強度和網絡手冊的難易程度，僅審計日誌附錄。
• 稅收/VAT/FX是正確的，客戶配置文件已完成。
• 門戶網站：使用、發票、貸款、網絡手冊；PSP集成和停機。
• DWH報告（MRR/ARPU/LTV/Churn/NRR），每日重新報告。
• SLA信用和分配政策已記錄在案。

20）頻繁的錯誤和反模式

沒有相等性→使用雙打/雙重註銷。
Price「關於請求」，沒有嚴重尾礦的貸款，→負利潤率。
「在公司所在地」而不是客戶的稅收→合規錯誤。
沒有細節的發票→客戶爭議。
usage↔PSP↔invoysy →報告不一致之間沒有重新調整。

底線

API的強計費是事件計費體系結構，清晰的價位，嚴格的冪等，正確的稅收/外匯計費和透明的報告。將使用與收入聯系起來,為客戶提供清晰的細節,並始終實現自動化-從事件到發票和MRR行車記錄。這將提供可預測的收入，減少分配並推動產品經濟。