課金使用状況 API

Billing Usage API を使用すると、毎月の請求書の背後にある同じ請求データにプログラムでアクセスできます。オンデマンドでコストを照会し、結果を独自のシステムに統合し、自動レポートパイプラインを構築します。

Billing Usage API は、次の必要がある場合に使用します。

コストレポートパイプラインの自動化
請求データを独自のダッシュボードまたは財務システムに統合する
オンデマンドでアカウント階層全体にわたるクエリ
前期比分析のための月レベルでのコストの集計

請求データへのアクセス方法を選択する

NTT CPaaS は、Web インターフェイスの 財務レポート と、プログラムによるアクセス用の Billing Usage API の 2 つのサーフェスを通じて、同じ請求グレードのデータを公開します。ワークフローに合ったオプションを選択します。

機能	財務報告	課金使用状況 API
アクセス	Webインターフェイス(1回限りまたは繰り返し)	オンデマンド、非同期
時間粒化	月次合計、オプションの日の内訳	日または月
キャンペーン参照でフィルタ	いいえ (寸法としてのみ使用可能)	はい
名前解決	キャンペーン名とテンプレート名を表示します	ID のみ
エクスポート形式	XLSX、CSV	JSON (コールバック)
スケジュール設定	定期 (月次)	オンデマンドのみ

Webインタフェースオプションについては、財務諸表を参照してください。

仕組み

Billing Usage API は、非同期の要求/応答パターンを使用します。クエリを送信すると、処理が完了すると、NTT CPaaS がサーバー上のコールバック URL に結果を配信します。

リクエストを送信する
フィルター、集計ディメンション、サーバーを指す callbackUrl を使用して、請求使用状況データのクエリを使用してリクエストを送信します。

要求 ID を受け取る
API はすぐに requestId を返します。処理は非同期に実行されるため、サーバーを待つ必要はありません。

コールバックURLで結果を受け取る
処理が完了すると、NTT CPaaSは結果をJSONとしてcallbackUrlにPOSTします。コールバックペイロード構造については、「請求使用結果の受信」を参照してください。処理時間は、クエリの複雑さと日付範囲によって異なります。

アクセスと可用性

Billing Usage APIを使用するには、次のものが必要です。

billing:usage:view スコープを持つ APIキー。「 API 認証を参照してください。
コールバック URL: クエリの完了時に NTT CPaaS POST が生成されるサーバー上のパブリックに到達可能なエンドポイント。

デフォルトでは、結果には、アカウント、関連するサブアカウント、および会社の下のすべてのアカウントのデータが含まれます。このクロスアカウントビューは、請求構造を反映しています。サブアカウントユーザーには、自分のデータのみが表示されます。アカウント階層と可視性を参照してください。

大事なBilling Usage API は、従来のアカウント設定では使用できません。これは構造上の制限です。要求に応じて有効にすることはできません。アカウントで従来の設定が使用されているかどうか不明な場合は、アカウントマネージャーにお問い合わせください。

カバレッジ

請求カテゴリコードの完全なリストについては、請求データリファレンスの「カテゴリ](/billing-usage-api/billing-data-reference#categories)」を参照してください。

データのファイナライズ

大事な当月のデータは暫定的なものであり、翌月5日に確定するまで変更される可能性があります。最終的なデータを財務システムまたは請求システムにのみ統合します。

当月の請求データは、月が終わるまで暫定的です。合計は、請求書が発行される 翌月 5 日 に確定するまで変更される場合があります。

当月のデータは、次の理由で変更される可能性があります。

遅れた交通記録
遡及的な数量ベースの割引
価格調整

API レスポンスには、クエリ内の各請求期間のファイナライズステータスを示すmetadata.billingPeriods配列が含まれています。財務計画または請求の目的で請求データを使用する前に、必ず請求書と照合してください。

手記固定のWhatsApp MAUサブスクリプションプランをご利用の場合、データには超過料金のみが表示されます。含まれるユーザー数は返されません。

データスコープ [#data-scope]

これらの制約は、すべての請求データサーフェス(財務レポート、請求使用状況 API)に適用されます。

保持期間: 当月および最大 2 か月前
タイムゾーン: UTC。カスタムタイムゾーンはサポートされていません。
マルチデータセンター: データはデータセンターごとに生成され、アクセスされます。データセンター間の集約はサポートされていません。アカウントがホストされている場所を確認するには、アカウントマネージャーまたはサポートにお問い合わせください。
請求書発行の調整: 請求データは、NTT CPaaS 請求書と同じ月次サイクル、通貨形式、請求構造に従います。

アカウント階層と可視性

デフォルトでは、Billing Usage API は、アカウント階層全体 (自分のアカウント、関連するサブアカウント、会社の下のすべてのアカウント) のデータを返します。これは請求構造を反映しています。

サブアカウントユーザーには、自分のアカウントデータのみが表示されます。結果を特定のアカウントに絞り込むには、accountKeysフィルタパラメータを使用します。

課金使用量 API およびメトリック API

Billing Usage API と Metrics API は異なるものを測定し、直接比較することはできません。Billing Usage API は課金されたメッセージのみをカウントし、すべてのチャネルがメッセージごとに課金されるわけではありません (たとえば、RCS は、個々のメッセージごとではなく、会話セッションごとに課金されます)。メトリック API は、請求ステータスに関係なく、すべてのメッセージをカウントします。タイムゾーンの構成により、2 つのクエリ間に異なる期間の境界が生成される場合もあります。

コスト調整には Billing Usage API を使用し、デリバリーとエンゲージメントの分析には Metrics API を使用します。

関連ページ

請求データのクエリ
最初の要求を作成し、フィルターと集計ディメンションを理解し、応答を処理します。

課金データ参照
コストフィールド、請求カテゴリ、チャネル別のトラフィックタイプ、および使用可能なすべての集計ディメンションを検索します。

決算報告
スケジューリングとエクスポートのオプションを備えたWebインターフェイスを介して、同じ請求データを表示します。

Billing Usage API リファレンス
完全なエンドポイントと Webhook の仕様、要求スキーマ、応答ペイロード。