コンテンツにスキップ

アカウント残高を取得



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 ストアドバリューカード残高

リクエスト例

curl --get 'https://openapi.guance.com/api/v1/billing/balance/get' \
  -H 'DF-API-KEY: <DF-API-KEY>'

レスポンス

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 を保持して管理者に連絡し、上流のレスポンスを確認してください。後で読み取りを再試行してください。

フィードバック

このページは役に立ちましたか?