API請求と報告

1）なぜAPIの請求を所有するのか

透明な収益化：使用率リンク→収益。
スケーラビリティとコントロール：クォータ、オーバーライド、ローン、プランに応じた価格表。
財務の正確さ：税金/付加価値税、マルチカレンシー、行為およびクロージングドキュメント。
顧客の信頼：詳細な使用状況レポート、webhook、セルフサービスポータル。

2）請求アーキテクチャ（高レベル）

Producers （APIゲートウェイ、サービス）→Usage Event Bus （Kafka/Queue）→Metering&Rating→Billing DB→Invoicing/Tax→Payments （PSP）→Reporting DWH→クライアントポータル/Webhooks。

• メータリング-使用量の収集と正規化（要求、ローン、ボリューム）。
• 評価-料金表/プランに従ってイベントの費用を見積もります。
• 請求書-期間、利益、税金、割引、クレジットの集計。
• 支払い-書き込みオフ/refands、日付（dunning）。
• 報告-MRR/ARPU/LTV、コホートチャーン、費用対効果。
• 監査-idempotence、変更されないログ。

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
}

ルール：イベントは追加されます。編集-'event_id'を参照した修正調整イベントを使用します。

5）貯蔵および集計の層

5.1 OLTP（課金DB）

Таблицы：'テナント'、'プラン'、'plan_prices'、 'entitlements'、 'usage_events'、 'rated_lines'、 'invoices'、 'invoice_lines'、 'tax_rates'、 'credits'、' payments'、'refunds'、'constitutes'。

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）価格表と評価（評価）

サポートモデル：平らな、階層化された、容積、束ねられたクレジット、pay-as-you-goおよび上書き。

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.顧客の所在地とサービスポイントによる税金（VAT/GST）。

5.クレジット/割引/クーポン。

6.署名と出版、支払いのための送信（PSP）、 webhook。

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： keep Tax Profile（国、有効なVAT-ID、 B2B/B2C）。
日付（バージョン）による税率、EU B2Bの逆の料金。
FX変換：請求日のレート（ERU/プロバイダ）、レートのソースを保持します。
書類：請求書、クレジットノート、デビットノート-番号とシリーズ。

9）支払い、デート、紛争

PSP （Stripe/Braintree/Adyen）：トークン化された支払い、拒否時の再送信、ダニング（1-3-7日）。
紛争/チャージバック：ステータスの修正、請求書へのリンク、相互作用のタイムライン。
払い戻し：'payment_id'と'invoice_id'に関連付けられた部分/完全。
詐欺信号：地理/ASN異常、使用バースト、異なるカード-請求のフラグ。

10）クレジット、割引、SLAクレジット

プロモーションローン（ウォレット）、SLA違反のサービスクレジット（次の期間で自動開始）。
クーポン：固定/利息、最低期間、プラン/エンドポイントの制限。
透明性：ポータルでは、ローンの残高とライトオフの履歴が表示されます。

11） Idempotencyおよび調節

Idempotency-Keyを介したすべての書き込み操作。
調整-オリジナルを編集せずに、調整イベント（正/負）のみを使用します。
和解：PSP ↔の請求書の使用rated_lines ↔ ↔毎日の検証。

12）安全性とコンプライアンス

ゲートウェイからのHMAC/JWT署名使用イベント。
mTLSはingestのために、環境ごとの個々のキー（prod/stage）。
PII最小化（PAN/メールを不必要に保存しない）、DSAR/Legal Hold。
金融取引の監査ログの変更不可（追加のみ）。

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-Quota-Remaining'、 'X-RateLimit-Remaining'、 'X-Usage-Period'です。

14） Webhookおよび請求イベント

イベント：'請求書。'、'請求書を作成しました。最終的な'、'支払い。'failed'、 'dunning成功しました。再試行、クレジット。適用された'、'論争。'closed'を開きました。
要件：Webhookの署名、バックオフの繰り返し、'delivery_id'による重複除外。

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） DevEx： セルフサービスポータル

登録、計画、キー、使用状況グラフ、請求書（PDF/JSON）、 webhook。
アップグレード/ダウングレード、請求書プレビュー（pro-forma）、支払い方法管理。
通知：「quota <10％」、 「overidge included」、「請求書発行/支払済」。

17）テストおよび環境

サンドボックス課金：ダミーPSP、テスト税率。
使用イベント（スキーマ/必須フィールド）の契約テスト。
stag、価格のブナの回帰テストのprodのサンプルを再生して下さい。
Backfillは安全です：idempotencyを使用したバッチインジェストのみ。

18） FinOpsと関税の経済学

エンドポイント/プランのマージンを考えてみましょう。収益−費用対効果です。
ローンに「高価な」オペレーションを割り当て、低層で制限します。
Observabilityのクエリコストを監視し、請求にリンクします。

19）チェックリストを起動する

• 'usage_event'/'adjustment'/'invoice_line' schemesがコミットされ、バージョン化されます。
• 価格表のテスト（フラット/階層/ボリューム）、prorate/override正しい。
• Idempotency of ingestion and webhook、 audit-log append-only。
• 税金/付加価値税/FX正しい、顧客プロファイルが入力されています。
• ポータル：使用法、請求書、クレジット、webhooks；PSPの統合とダニング。
• DWH報告（MRR/ARPU/LTV/Churn/NRR）、毎日和解。
• SLAクレジットおよび紛争ポリシーが文書化されています。

20）頻繁なエラーとアンチパターン

idempotency→duplicate usage/double write-offなし。
重いエンドポイントのための貸付け金のない価格「要求について」→否定的な証拠金。
税金「会社の場所で」、ないクライアント→コンプライアンスエラー。
詳細のない請求書→顧客の紛争。
usage↔PSP↔invoysy→レポートの不一致の間の和解はありません。

合計

APIに対する強力な請求は、イベント駆動のメータリングアーキテクチャ、明確な価格表、厳格なidempotence、正しい税金/FX請求、および透明なレポートです。使用状況を収益にリンクし、クライアントに明確な詳細を提供し、イベントから請求書、MRRダッシュボードまでの全体の旅を自動化します。これは、予測可能な収入、少数の紛争、および管理可能な製品経済を提供します。