アカウント残高を取得¶
GET /api/v1/billing/balance/get
概要¶
現在のワークスペースに対応する請求センターアカウントの3種類の残高を読み取ります。
呼び出し前の準備と使用手順¶
対象ワークスペースの API Key を使用します。Key が所属するワークスペースに対応する請求センターサイトのデータのみを読み取ることができ、追加の workspaceUUID/brandKey/サイトパラメータで切り替えることはできません。このインターフェースは課金、チャージ、精算、またはプランの変更を行いません。請求センターデータには生成または精算の遅延が発生する場合があり、空の結果は消費が発生していないことを意味しません。実際の請求期間と請求センターを照合してください。金額、通貨、精度、統計基準はそのワークスペースの請求センターに従い、Studio は換算や通貨フィールドの補完を行いません。例示された数値を価格と見なさないでください。
billing.billingRead、billing.billingWrite、または billing.workspaceUpgrade のいずれかの権限が必要です。ビジネス動作を制御できる Query パラメータはなく、workspaceUUID/accountUUID または請求期間でクエリを切り替えることはできません。追加の Query は無視され、ワークスペースや請求期間は変わりません。残高は請求センターアカウントに帰属し、これに基づいて他のワークスペースの消費額を推測しないでください。Studio は請求センターの残高結果から cashBalance/couponBalance/storedCardBalance の3つのキーのみを抽出し、その他の上流フィールドは自動的に公開されません。請求センターでいずれかのキーが欠落している場合は500になり、0で補完されることはありません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
パラメータ補足説明¶
返却パラメータの説明:
主要フィールド
| パラメータ名 | パラメータ説明 |
|---|---|
| cashBalance | 現金アカウント残高 |
| couponBalance | クーポン残高 |
| storedCardBalance | ストアドバリューカード残高 |
リクエスト例¶
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 現在の請求センターアカウントの残高ビューであり、チャージ額や請求書発行可能額ではありません。 |
| content.cashBalance | JSON | 現金アカウント残高。例では number。上流の値をそのまま透過し、固定の精度/通貨や自動換算を保証しません。 |
| content.couponBalance | JSON | クーポン残高。上流の値をそのまま返し、現金として引き出し可能な残高を意味しません。 |
| content.storedCardBalance | JSON | ストアドバリューカード残高。上流の値をそのまま返し、現金残高を意味しません。 |
| content.declaration | object | ワークスペース宣言。残高とは無関係です。 |
{
"code": 200,
"content": {
"cashBalance": 1000.25,
"couponBalance": 20.0,
"storedCardBalance": 0.0,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
請求センター SDK はまず ft.CloudCareApiError にマッピングし、上流の HTTP/ビジネス code で上書きします。この SDK にはパススルー用のマークが設定されていないため、最終的な code が 500 以上の場合、グローバルに HTTP500、ft.InternalServerError、および汎用テキストにラップされます。外部に対して 503 や元の 5xx メッセージが保持されると仮定しないでください。最終的な code が 500 未満の場合は、CloudCareApiError と実際の message が保持されます。接続異常はデフォルトで 400 です。ここでは確認済みの Studio マッピングのみを記載し、請求センターの各ビジネスエラーやプロキシエラーを網羅するものではありません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 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 を保持して管理者に連絡し、上流のレスポンスを確認してください。後で読み取りを再試行してください。 |