账单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行车记录。这将提供可预测的收入，减少分配并推动产品经济。