請求データのクエリ

このガイドでは、フィルターと集計ディメンションの設定からコールバック応答の処理まで、請求使用状況クエリの作成について説明します。

API、サポートされているチャネル、およびデータのファイナライズ動作の概要は、「請求使用状況API」を参照してください。

始める前に

最初のリクエストを送信する前に、次のものがあることを確認してください。

• APIキー: billing:usage:viewスコープが必要です。401 Unauthorizedエラーは、このスコープが欠落していることを意味します。「 API 認証 を参照してください。
• コールバック URL: NTT CPaaS POST が実行されるサーバー上のパブリックに到達可能なエンドポイント (localhost は機能しません)。結果が届かない場合は、ファイアウォール ルールを確認し、初期応答の requestId をチェックして、要求が受け入れられたことを確認します。
• 日付範囲: データは、当月と過去 2 つの暦月の場合にのみ使用できます。

リクエストを作成する

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

例

POST /billing/1/usage/query
 
{
  "callbackUrl": "https://your-server.com/billing-callback",
  "request": {
    "filterBy": {
      "dateInterval": {
        "sentSince": "2026-04-01",
        "sentUntil": "2026-04-30"
      }
    },
    "aggregateBy": ["DAY"]
  }
}

これは、日ごとに分類された2026年4月の返品コストです。ACCOUNT_NAME と CATEGORY_CODE は、勘定またはカテゴリのディメンションが指定されていないため、デフォルトとして自動的に追加されます。

フィルタ

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

オプション

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

"options": {
  "includeUnfinalizedData": false
}

集計ディメンション

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

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

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

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

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

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

応答データ

結果は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 は、その月の請求データが完全に処理され、それ以上のボリュームの変更は予想されないことを意味します。請求書と照らし合わせて最終金額を必ず確認してください。

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