請求情報の取得¶
GET /api/v1/billing/detail/list
概要¶
日付を指定して、現在のワークスペースの請求センター請求明細を読み取ります。
呼び出し前と使用手順¶
対象ワークスペースの API Key を使用します。Key が属するワークスペースに対応する請求センターサイトのデータのみを読み取れ、追加の workspaceUUID/brandKey/サイトパラメータで切り替えることはできません。このインターフェースは課金、チャージ、決済、プラン変更を行いません。請求センターデータには生成または決済の遅延が生じる場合があり、空の結果は消費が発生していないことを意味しません。実際の請求期間と請求センターの情報を照合してください。金額、通貨、精度、統計基準は当該ワークスペースの請求センターに従い、Studio は換算や通貨フィールドの補完を行わず、例示した数値を価格として扱うべきではありません。
billing.billingRead または billing.workspaceUpgrade のいずれかの権限が必要です。startDate/endDate はそれぞれ省略時に Studio サーバーの当日(ローカルの date.today)となり、ワークスペースのタイムゾーンやブラウザのタイムゾーンではありません。常に同じ形式の開始日と終了日を明示的に同時送信することを推奨します。ページングパラメータはありません。pageSize/date/billingKey などのパラメータを独自に追加することはできません。
公開側の検証では文字列であることのみを要求し、実在する日付、8 桁フォーマット、前後順序は検証しません。最終的な受け入れ/拒否と境界基準は請求センターが担い、Studio が日付を自動交換、正規化、補完することを保証するものではありません。明示的な空文字列は省略とは異なります。SDK は両方の値が非空の場合にのみ開始日と終了日を上流へ送信し、いずれかが空の場合、日付範囲は送信されません。空値で過去の請求期間をリクエストしないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| endDate | string | 任意の文字列。省略時はサーバーの当日となり、空値の場合 SDK は日付範囲全体を転送しません。Studio は前後順序を検証しません。 null 許可: False 例: 20260731取得または入力方法: 対象の終了日を選択します。startDate より早くしないことを推奨します。範囲の境界は請求センターに従います。 |
|
| startDate | string | 任意の文字列。省略時はサーバーの当日となります。空文字列ではデフォルト日付は適用されません。公開宣言に形式の正規表現はありません。 null 許可: False 例: 20260730取得または入力方法: 対象の請求期間に応じて YYYYMMDD 形式の日付を選択します。endDate と合わせて明示的に入力することを推奨します。 |
パラメータ補足説明¶
請求センターの明細リストを返します。フィールド表と例は上流の実際の構造に基づいて解釈します。製品識別子、フィールド型、空値は Studio によってブランド表示名に置き換えられたり、デフォルト値が補完されたりしません。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/billing/detail/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode startDate=20260730 \
--data-urlencode endDate=20260731
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | array または object | 請求センターの請求リストをそのまま返します。例では各項目がオブジェクトです。空配列の場合があります。上流に content がない場合、SDK は空オブジェクト {} にフォールバックし、Studio のページングラッパーはありません。 |
| content[] | object | 1 件の請求明細。フィールドは請求センター由来であり、すべてのフィールドが各項目に存在することを保証しません。 |
| content[].consumeTimeOfDay | JSON | 消費日。例は YYYY-MM-DD で、呼び出し時刻ではありません。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].orgName | JSON | 請求センターの組織名であり、ワークスペース UUID ではありません。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].productName | JSON | 上流の製品識別子/名称。固定のブランド表示名を仮定できず、実際の返却値は書き換えません。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].productDetail | JSON | 課金項目の表示名。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].billingKey | JSON | 課金カテゴリ識別子。過去のレスポンスによっては tag6 のみの場合があります。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].billingCycle | JSON | 請求サイクル区分(Day/Month/Year/Single など)。実際の返却値に応じて処理してください。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].billingResult | JSON | 支払対象金額。請求センターの基準です。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].deductionAmount | JSON | 控除金額。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].oweAmount | JSON | 未払い金額。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].originAmount | JSON | 定価金額。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].serviceBillingAmount | JSON | サービス料金。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].couponAmount | JSON | クーポン控除金額。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].storedCardAmount | JSON | チャージカード控除金額。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].cashAmount | JSON | 現金控除金額。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].cashCouldAmount | JSON | クラウドマーケット控除金額。過去のフィールド表記を保持します。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].commodityCategory | JSON | 製品タイプ/課金モデル。上流によって定義されます。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].consumePlatform | JSON | 決済チャネル区分。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].customerIdentifier | JSON | クラウドマーケット顧客識別子。他の API で使用できる認証情報ではありません。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].consumption | JSON | 上流の消費追加情報。Studio は加工しません。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].workspaceUuid | JSON | 消費に紐づくワークスペース識別子。フィールドの小文字 uid 表記が workspaceUUID と異なる点に注意してください。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].workspaceName | JSON | 消費に紐づくワークスペース名。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].consumeTime | JSON | 消費時刻。型と単位は上流が決定し、固定の秒単位タイムスタンプとして扱わないでください。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].billingResultDetails | JSON | 請求センターの追加課金明細。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].count | JSON | 使用量。単位は課金項目ごとに異なり、課金項目をまたいで直接合計できません。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].tag6 | JSON | 過去の課金項目識別子(例: session_replay)。過去の空値は null、空文字列、またはリテラル文字列 None の可能性があり、実際の型に応じて処理してください。 |
| content[].declaration | object | オブジェクトリストを直接返す場合、空でない行に付加されるワークスペース宣言。 |
{
"code": 200,
"content": [
{
"consumeTimeOfDay": "2023-07-31",
"orgName": "None",
"productName": "None",
"productDetail": "Session Replay",
"billingCycle": "None",
"billingResult": 0,
"deductionAmount": "None",
"oweAmount": "None",
"originAmount": 0,
"serviceBillingAmount": "None",
"couponAmount": "None",
"storedCardAmount": "None",
"cashAmount": "None",
"cashCouldAmount": "None",
"commodityCategory": "None",
"consumePlatform": "None",
"customerIdentifier": "None",
"consumption": "None",
"workspaceUuid": "None",
"workspaceName": "None",
"consumeTime": "None",
"tag6": "session_replay",
"billingResultDetails": "None",
"count": 0,
"declaration": {}
}
],
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
請求センター SDK はまず ft.CloudCareApiError にマッピングし、上流の HTTP/ビジネスコードで上書きします。この SDK にはパススルーフラグが設定されていないため、最終的な code が 500 以上の場合、グローバルに HTTP500、ft.InternalServerError、および汎用テキストでラップされます。外部に対して 503 や元の 5xx メッセージが保持されることを前提にできません。最終的な code が 500 未満の場合は CloudCareApiError と実際の message が保持されます。接続例外のデフォルトは 400 です。ここでは確認済みの Studio マッピングのみを記載し、請求センターの各ビジネスエラーやプロキシエラーを網羅するものではありません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 未宣言の Query パラメータを使用した、またはパラメータがルールに違反している | パラメータ解析失敗 | Query パラメータ表と例を確認してください。 |
| 404 | ft.ObjectNotExists | 現在の Key に対応するワークスペースレコードが見つからない | 指定オブジェクトが存在しない | 対象ワークスペースと Key の有効状態を確認してください。 |
| 406 | ft.InvalidBossNode | ワークスペースにバインドされた請求センターブランド/ノードが未設定または利用不可 | 無効な Boss ノード | 管理者に連絡し、ワークスペースの請求センターバインドとサイト設定を確認してください。日付の変更で回避しないでください。 |
| 400 | ft.CloudCareApiError | 請求センターへのリクエスト接続失敗(デフォルト 400)、またはマッピング後の code が 500 未満の上流 HTTP/ビジネスエラー | 内部インターフェース呼び出し失敗 | HTTP、message、traceId を保持し、請求センターの可用性と具体的なエラーを確認してください。最終的な 4xx は変動する可能性があり、code が 500 以上の場合、グローバルに ft.InternalServerError でラップされます。 |
| 500 | ft.InternalServerError | 請求センターが想定外の型/欠落フィールド、無効な JSON、その他の保存・フォーマットエラーを返した | 内部エラー | traceId を保持して管理者に連絡し、上流の応答を確認したうえで、後で読み取りを再試行してください。 |