課金利用状況APIガイド

課金利用状況APIは、毎月の請求書の根拠となる課金データにプログラム経由でアクセスできるようにします。必要に応じてコストを照会し、その結果をお客様のシステムに統合し、自動化されたレポート作成パイプラインを構築することができます。

課金利用状況APIの利用は、次のようなことをする必要が生じた時に役立ちます：

• コストレポートパイプラインの自動化
• 独自のダッシュボードまたは財務システムへの課金データの統合
• アカウント階層全体を対象にしたオンデマンドのクエリ
• 期間ごとの比較分析用の日次または月次コストの集計

アクセスと可用性

課金利用状況APIを使用するには、以下が必要です：

• APIキー： billing:usage:viewスコープが必要です。詳細については、 API認可 について詳述しているドキュメントをご参照ください。
• コールバックURL： クエリが完了した際に、NTT CPaaSが結果をPOSTする、サーバー上の一般にアクセス可能なエンドポイントです。localhostは使用できません。
• 日付範囲： データは、当月および過去2か月の暦月分のみ利用可能です。

デフォルトでは、検索結果には、お持ちのアカウント、関連するサブアカウント、およびお客様の会社の管理下にあるすべてのアカウントのデータが含まれます。このアカウント横断的な表示は、請求書の構造を反映したものです。サブアカウントとしてログインした場合は、お客様専用のデータのみが表示されます。詳細[アについては、アカウントの階層と可視性 について詳述しているドキュメントをご参照ください。

対応範囲

課金利用状況APIは、以下のチャネルとプラットフォームサービスをサポートしています：

Apple Messages for BusinessSMSMMSEmailWhatsAppRCSViberNumber LookupMobile PushEmail ValidationAgentOSVoice and Video

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

仕組み

課金利用状況APIは、非同期のリクエスト／レスポンスパターンを使用します：

データの確定

当月の課金データは、月次決算が完了するまでは暫定的なものです。合計額は、請求書が発行される翌月5日に確定するまでは変わる可能性があります。

当月のデータは、以下の状況が生じた場合に変更になることがあります：

• トラフィックのレコードが届くのが遅くなった場合
• 数量ベースの割引が遡及的に適用された場合
• 価格調整が発生した場合

APIのレスポンスには、クエリに記述した各課金期間の確定ステータスを示すmetadata.billingPeriods配列が含まれています。財務計画または請求の目的で課金データを使用する際は、必ずその前に請求書と照合して、確定したデータであることを確認するようにしてください。

メトリクスAPIとより広範な比較を行いたい時は、メトリクスAPI をご利用ください。但し、これら2つのAPIは測定対象が異なるため、直接比較することはできません。

データの対象範囲 [#data-scope]

以下に示す制約は、すべての課金データ表示画面（財務レポート、課金利用状況API）に適用されます：

• 保持期間： 当月および過去2か月まで
• タイムゾーン： UTC。カスタムタイムゾーンはサポートされていません。
• マルチデータセンター： データはデータセンターごとに生成され、アクセスされます。データセンター間の集計はサポートされていません。お客様のアカウントがどのデータセンターでホストされているかを確認したい場合、アカウントマネージャーまたはサポートまでお問い合わせください。
• 請求書の整合性： 課金データは、NTT CPaaSの請求書と同じ月次サイクル、通貨形式および課金体系に従います。

オプション [#options]

• includeUnfinalizedData（ブール値、デフォルトは true）： falseに設定すると、確定した課金期間のみが返され、当月の暫定データが除外されます。

リクエストの作成

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

例 [#example]

これは、2026年4月のコストが日別内訳として返された例です。sentUntilは「終了日を含まない」という意味になるため、暦月全体を網羅したい場合は、翌月の1日を指定してください。この例では、アカウントやカテゴリーのディメンションが指定されていないため、ACCOUNT_NAMEとCATEGORY_CODEはデフォルト値として自動的に追加されます。

フィルター [#filters]

フィルターは、対象として含めたいデータを処理前に絞り込みたい時に使用します。dateIntervalは必須です。その他のフィルターはすべて任意です。

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

集計ディメンションは、レスポンス内で結果がどのようにグループ化されるかを定義します。フィルターは、どのデータを含めるかを絞り込み、ディメンションは、どのようにグループ化されるかを定義します。例えば、フィルターで対象をcategories: ["SMS"]に絞り込むと、結果はSMSに限定されます。さらに、aggregateByに "COUNTRY_NAME"を追加すると、その結果が国ごとに分類されます。その結果が国ごとに分類されます。

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

デフォルトで自動的に追加されるディメンション：

• ACCOUNT_NAME： ACCOUNT_NAMEもACCOUNT_KEYも指定されていない場合に自動的に追加されます。`
• CATEGORY_CODE： CATEGORY_CODEもCATEGORY_NAMEも指定されていない場合に自動的に追加されます。`

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

指定可能な追加のディメンションには、時間（DAY、MONTH）、地域（COUNTRY_NAME、NETWORK_NAME）、送信者、キャンペーン、マルチテナントのコンテキスト（APPLICATION_ID、ENTITY_ID）が含まれます。キャンペーンおよびテンプレートのディメンションからは、IDのみが返されます。課金データには名前は含まれません。

詳細情報

For the full list of aggregateBy enum values and their definitions, see Dimensions in the Billing data reference.

レスポンスデータ

結果は、JSON形式でコールバックURLに送信されます。レスポンスには以下の内容が含まれます：

コストフィールドの定義および通貨の表示形式については、コストフィールド について詳述しているドキュメントをご参照ください。

アカウントの階層と可視性

デフォルトでは、課金利用状況APIは、アカウント階層全体（お持ちのアカウント、関連するサブアカウント、およびお客様の会社の管理下にあるすべてのアカウント）のデータを返します。このアカウント横断的な表示は、請求書の構造を反映したものです。

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

トラブルシューティング