請求データのクエリ
このガイドでは、フィルターと集計ディメンションの設定からコールバック応答の処理まで、請求使用状況クエリの作成について説明します。
API、サポートされているチャネル、およびデータのファイナライズ動作の概要は、「請求使用状況API」を参照してください。
始める前に
最初のリクエストを送信する前に、次のものがあることを確認してください。
- APIキー:
billing:usage:viewスコープが必要です。401 Unauthorizedエラーは、このスコープが欠落していることを意味します。「 API 認証 を参照してください。 - コールバック URL: NTT CPaaS POST が実行されるサーバー上のパブリックに到達可能なエンドポイント (localhost は機能しません)。結果が届かない場合は、ファイアウォール ルールを確認し、初期応答の
requestIdをチェックして、要求が受け入れられたことを確認します。 - 日付範囲: データは、当月と過去 2 つの暦月の場合にのみ使用できます。
リクエストを作成する
フィルター、集計ディメンション、コールバック URL を使用して、 請求使用状況データのクエリ を使用して POST リクエストを送信します。
すべてのリクエストには、callbackUrl、filterBy.dateInterval、および aggregateBy の少なくとも 1 つのエントリの 3 つのフィールドが必要です。他のすべてのフィルターはオプションです。
dateInterval または aggregateBy が欠落しているリクエストは、検証エラーを返します。日付範囲は 3 か月を超えてはなりません。例 [#example]
これは、日ごとに分類された2026年4月の返品コストです。ACCOUNT_NAME と CATEGORY_CODE は、勘定またはカテゴリのディメンションが指定されていないため、デフォルトとして自動的に追加されます。
フィルタ [#filters]
フィルターは、処理前に含めるデータを絞り込みます。dateInterval は必須です。その他はすべてオプションです。
| フィルター | 説明 | ノート |
|---|---|---|
| '日付間隔' | UTC での請求データの期間 | 必須。sentSince と sentUntil を yyyy-MM-dd 形式で使用します。最大範囲: 当月と 2 か月前。 |
| 'カテゴリ' | フィルター処理するチャネルまたはサービス | カテゴリを参照してください。 |
| 'トラフィックタイプ' | チャネル内のトラフィックタイプ | 値はチャネルによって異なります。 |
| 「プラットフォーム」 | CPaaS X アプリケーションとエンティティの組み合わせ | テナントまたはユースケースごとのコストを分離するために使用します。 |
campaignReferenceIds | キャンペーン参照ID | API でのみ使用でき、財務レポートでは使用できません。 |
| 「国コード」 | 送信先の国 | ISO 3166-1 alpha-2 形式 (例: ["US", "DE"])。 |
accountKeys, senders, senderTypes, directions, subCategories, campaignIds, templateIds | 追加のオプションフィルター | 有効な値については、課金データリファレンスを参照してください。 |
SMS_OPERATOR_FEEまたはMMS_OPERATOR_FEEカテゴリが生成されます。全額を取得するには、フィルターに両方を含めます: categories: ["SMS", "SMS_OPERATOR_FEE"])。オプション [#options]
includeUnfinalizedData(ブール値、デフォルトはtrue):falseに設定すると、確定した請求期間のみが返され、当月の暫定データが除外されます。
集計ディメンション [#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_KEYも指定されていない場合、ACCOUNT_NAMEは自動追加されます。CATEGORY_CODEは、CATEGORY_CODEもCATEGORY_NAMEも指定されていない場合、自動追加されます。
一方のバリアントを指定すると、もう一方のバリアントが抑制されます。両方を明示的に含めない限り、両方が同時に追加されることはありません。
追加のディメンションには、時間 (DAY、MONTH)、地域 (COUNTRY_NAME、NETWORK_NAME)、送信者、キャンペーン、マルチテナント コンテキスト (APPLICATION_ID、ENTITY_ID) が含まれます。キャンペーンとテンプレートのディメンションは、ID のみを返します。名前は請求データに含まれません。
aggregateBy 列挙値とその定義の完全なリストについては、課金データ リファレンスの Dimensions を参照してください。
応答データ
結果はJSONとしてコールバックURLに配信されます。完全なコールバック ペイロード スキーマについては、「 請求使用結果の受信」を参照してください。
応答には次のものが含まれます。
requestId: クエリを送信したときに返された ID と一致します。status:SUCCESSまたはFAILED。response: ステータスがSUCCESSのときに表示されます。requestedPeriod、totalRows、columns、およびrowsが含まれます。failureMessage: ステータスがFAILEDの場合に存在します。metadata: 成功時に提示します。clientRequestedPeriodとbillingPeriodsが含まれます。
response.rows配列には、集計の組み合わせごとに1つのエントリが含まれます。各行は、インデックスによって値を columns 配列にマップします。特定のチャネルでメトリックが使用できない場合、対応する値は "N/A" です。
metadata.billingPeriods配列は、クエリの対象となる各暦月のファイナライズステータスを示します。volumeFinalized: true は、その月の請求データが完全に処理され、それ以上のボリュームの変更は予想されないことを意味します。請求書と照らし合わせて最終金額を必ず確認してください。
requestedPeriodは、要求された日付範囲と異なる場合があります。範囲は集計の粒度に合わせて調整でき、該当する場合は、最終期間のみにトリミングできます。原価フィールドの定義と通貨形式については、原価フィールドを参照してください。
課金データ参照
有効なカテゴリ、トラフィックタイプ、集計ディメンションコードをすべて検索します。
決算報告
スケジューリングとエクスポートのオプションを備えたWebインターフェイスを介して、同じ請求データを表示します。
Billing Usage API リファレンス
完全なエンドポイントと Webhook の仕様、要求スキーマ、応答ペイロード。