Logo
CTRLK
Logo
CTRLK
無料で試す
すべての製品を見る
概要
ダッシュボード
メール配信到達性センター
レポート
レポートの管理
メッセージログ
Webhook のレポート
メトリック API
課金使用状況 API
メトリックリファレンス
列参照

Billing Usage API ガイド

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

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

  • コストレポートパイプラインの自動化
  • 請求データを独自のダッシュボードまたは財務システムに統合する
  • オンデマンドでアカウント階層全体にわたるクエリ
  • 日または月レベルでコストを集計し、前期比分析を行う
機能課金使用状況 APIメトリック API財務報告
データタイプ財務 (コスト)パフォーマンス(配信、エンゲージメント)財務 (コスト)
アクセス非同期 API非同期 APIWebインターフェイス
時間の粒状化日、月時間から年間へ月次合計、オプションの日の内訳
保持当月 + 2 か月前クエリごとに最大 366 日当月 + 2 か月前
キャンペーン参照でフィルタ可可いいえ (寸法としてのみ使用可能)
マルチテナントアプリケーション、エンティティアプリケーション、エンティティアプリケーション、エンティティ

アクセスと可用性

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

  • APIキー: billing:usage:viewスコープが必要です。「 API 認証 を参照してください。
  • コールバックURL: クエリの完了時にNTT CPaaS POSTが実行されるサーバー上のパブリックに到達可能なエンドポイント。localhost は機能しません。
  • 日付範囲: データは、当月と過去 2 つの暦月の場合にのみ使用できます。

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

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

カバレッジ

Billing Usage API は、次のチャネルとプラットフォーム サービスをサポートしています。


Apple Messages for BusinessSMSMMSEmailWhatsAppRCSViberNumber LookupMobile PushEmail ValidationAgentOSVoice and Video

請求カテゴリ コードの完全なリストについては、請求データ リファレンスの カテゴリ を参照してください。


仕組み

Billing Usage API は、非同期の要求/応答パターンを使用します。

1

要求を送信する
フィルター、集計ディメンション、サーバーを指す callbackUrl を使用して Billing Usage API エンドポイントに POST します。

2

要求 ID を受け取る
API はすぐに requestId (HTTP 201) を返します。処理は非同期に実行されます。

3

コールバックURLで結果を受け取る
処理が完了すると、NTT CPaaSは結果をJSONとしてcallbackUrlにPOSTします。処理時間は、クエリの複雑さと日付範囲によって異なります。


データのファイナライズ

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

重要最終的なデータを財務システムまたは請求システムにのみ統合します。

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

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

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

備考固定のWhatsApp月間アクティブユーザー(MAU)サブスクリプションプランをご利用の場合、データには超過料金のみが表示されます。含まれるユーザー数は返されません。これは、財務レポート、請求使用状況 API、AgentOS レポートに適用されます。

Metrics API とより広範な比較を行うには、Metrics API を使用します。2 つの API は異なるものを測定し、直接比較することはできません。


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

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

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

オプション [#options]

  • includeUnfinalizedData (ブール値、デフォルトは true): false に設定すると、確定した請求期間のみが返され、当月の暫定データが除外されます。
json
1"options": {
2 "includeUnfinalizedData": false
3}

リクエストを作成する

すべてのリクエストには、callbackUrl、request.filterBy.dateInterval、および request.aggregateBy の少なくとも 1 つのエントリの 3 つのフィールドが必要です。他のすべてのフィルターはオプションです。

備考dateInterval または aggregateBy が欠落しているリクエストは、検証エラーを返します。日付範囲は 3 か月を超えてはなりません。

例 [#example]

http
POST /billing/1/usage/query
json
1{
2 "callbackUrl": "https://example.com/billing-callback",
3 "request": {
4 "filterBy": {
5 "dateInterval": {
6 "sentSince": "2026-04-01",
7 "sentUntil": "2026-05-01"
8 }
9 },
10 "aggregateBy": ["DAY"]
11 }
12}

これは、日ごとに分類された2026年4月の返品コストです。sentUntilは排他的であるため、翌月の 1 日を使用して暦月全体をカバーします。ACCOUNT_NAME と CATEGORY_CODE は、勘定またはカテゴリのディメンションが指定されていないため、デフォルトとして自動的に追加されます。


フィルター [#filters]

フィルターは、処理前に含めるデータを絞り込みます。dateInterval は必須です。その他はすべてオプションです。

フィルター説明ノート
'日付間隔'UTC での請求データの期間必須です。sentSince と sentUntil を yyyy-MM-dd 形式で使用します。sentSinceは包括的で、sentUntilは排他的です。最大範囲: 当月と 2 か月前。
'カテゴリ'フィルター処理するチャネルまたはサービスカテゴリを参照してください。
'トラフィックタイプ'チャネル内のトラフィックタイプ値はチャネルによって異なります。
「プラットフォーム」CPaaS Xアプリケーションとエンティティ の組み合わせテナントまたはユースケースごとのコストを分離するために使用します。
campaignReferenceIdsキャンペーン参照IDAPI でのみ使用でき、財務レポートでは使用できません。
「国コード」送信先の国ISO 3166-1 alpha-2 形式 (例: ["US", "DE"])。
'サブカテゴリ'カテゴリ内のサービスバリアントViber および Voice and Video カテゴリに適用されます。サブカテゴリを参照してください。
accountKeys, senders, senderTypes, directions, campaignIds, templateIds追加のオプションフィルター有効な値については、課金データリファレンスを参照してください。
備考米国では、SMS と MMS のトラフィックによって、通信事業者の追加料金として別のSMS_OPERATOR_FEEまたはMMS_OPERATOR_FEEカテゴリが生成されます。全額を取得するには、フィルターに両方を含めます: categories: ["SMS", "SMS_OPERATOR_FEE"])。

集計ディメンション [#aggregation-dimensions]

集計ディメンションは、応答で結果をグループ化する方法を定義します。フィルターは、含まれる**データを絞り込みます。ディメンションは、グループ化の方法を定義します。たとえば、'categories: ["SMS（Short Message Service"]' でフィルタリングすると、結果は SMS に制限されます。aggregateBy に "COUNTRY_NAME" を追加すると、国ごとに分類されます。

aggregateBy には少なくとも 1 つのディメンションが必要です。2 つのペアには、ペアからいずれかのバリアントを指定しない場合、デフォルトが自動追加されます。

送信すると...結果には以下が含まれます...
'["日"]'ACCOUNT_NAME, CATEGORY_CODE, DAY
'["ACCOUNT_KEY", "日"]'CATEGORY_CODE、ACCOUNT_KEY、「日」
'["ACCOUNT_NAME", "CATEGORY_NAME", "日"]'ACCOUNT_NAME、CATEGORY_NAME、「日」
'["ACCOUNT_KEY", "CATEGORY_NAME", "日"]'ACCOUNT_KEY, CATEGORY_NAME, DAY

デフォルトの自動追加ディメンション:

  • ACCOUNT_NAME: ACCOUNT_NAME も ACCOUNT_KEY も指定されていない場合は自動追加されます。
  • CATEGORY_CODE: CATEGORY_CODE も CATEGORY_NAME も指定されていない場合は自動追加されます。

一方のバリアントを指定すると、もう一方のバリアントが抑制されます。両方を明示的に含めない限り、両方が同時に追加されることはありません。

追加のディメンションには、時間 (DAY、MONTH)、地域 (COUNTRY_NAME、NETWORK_NAME)、送信者、キャンペーン、マルチテナント コンテキスト (APPLICATION_ID、ENTITY_ID) が含まれます。キャンペーンとテンプレートのディメンションは、ID のみを返します。名前は請求データに含まれません。

もっと詳しく知る

aggregateBy 列挙値とその定義の完全なリストについては、請求データ リファレンスの Dimensions を参照してください。


応答データ

結果はJSONとしてコールバックURLに配信されます。応答には次のものが含まれます。

フィールド説明
requestIdクエリを送信したときに返された ID と一致します
'ステータス'SUCCESSまたはFAILED
response.requestedPeriodクエリで使用される時間範囲。粒度の調整またはファイナライズのトリミングにより、要求された範囲と異なる場合があります。
response.totalRows返されるデータ行の合計数
'応答.列'各列を記述する配列: columnName (ディメンションまたはコスト フィールド コード) と columnDataType (STRING, INTEGER, NUMBER, BOOLEAN, DATE_TIME)
response.rowsデータ行の配列。各行には、columns 配列と同じ順序の値が含まれています。N/A は、フィールドがその行の組み合わせに適用されないことを示します。
'失敗メッセージ'ステータスがFAILEDの場合に存在します。
metadata.clientRequestedPeriodsentSince と sentUntil は、送信したとおりの値です。response.requestedPeriodと比較して、範囲が調整されたかどうかを確認します。
metadata.billingPeriodsクエリ内の各請求期間の確定ステータスは、month (yyyy-MM 形式) と volumeFinalized として指定されます。volumeFinalized が true の場合、その月のユニット数は完了し、それ以上のボリュームの変更は予想されません。請求書が発行されるまで価格は変更される可能性があるため、請求書と照合して最終金額を必ず確認してください。

原価フィールドの定義と通貨形式については、原価フィールドを参照してください。


アカウント階層と可視性

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

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


トラブルシューティング

問題点ソリューション
コールバックURLが結果を受信していないコールバック URL がパブリックにアクセス可能であることを確認します (localhost は機能しません)。受信要求をブロックする可能性のあるファイアウォール規則を確認します。最初の応答で返された requestId をチェックして、要求が受け入れられたことを確認します。
401 不正エラーAPIキーにbilling:usage:viewスコープがあることを確認します。「 API 認証 を参照してください。
検証エラーdateInterval と少なくとも 1 つの aggregateBy ディメンションが含まれていることを確認します。日付範囲が 3 か月を超えないことを確認します。
Billing Usage APIにアクセスできないAPIキーにbilling:usage:viewスコープがあることを確認します。スコープが正しい場合、アカウントはレガシー設定を使用できますが、これは要求に応じて有効にできない構造上の制限です。アカウントマネージャーに問い合わせて確認してください。


関連ページ

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

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

メトリクスAPI
集計されたパフォーマンス指標をクエリして、すべてのチャネルにわたる配信とエンゲージメントの分析を行います。



← メトリック APIメッセージング・メトリック・リファレンス →

Logo

ご不明点は

サポートまでお問い合わせ

ください

© NTT DOCOMO BUSINESS X,Inc.