需求
Authorization: Basic <API_KEY>（你的應用程式 API 金鑰）- 應用程式已啟用 批次 API 功能
- 每個目標使用者的授權需具備
LIST_PAYMENT權限範圍
查詢
query GetBulkBalances($targetSpec: BulkTargetSpecInput!) {
getBulkBalances(targetSpec: $targetSpec) {
targetCount
successCount
failureCount
results {
externalReferenceId
accountId
success
error { code message }
balances {
userCashBalanceId
nickname
status
totalCashBalance
availableCashBalance
lifetimeCashBalance
createdAt
}
}
}
}
變數 — 指定使用者
{
"targetSpec": { "mode": "SELECTED", "targets": ["your-user-001", "your-user-002"] }
}
變數 — 所有已連結使用者
{
"targetSpec": { "mode": "ALL_CONNECTED" }
}
回應
{
"data": {
"getBulkBalances": {
"targetCount": 2,
"successCount": 1,
"failureCount": 1,
"results": [
{
"externalReferenceId": "your-user-001",
"accountId": "8f3c…",
"success": true,
"error": null,
"balances": [
{
"userCashBalanceId": "ucb-1",
"nickname": "Main account",
"status": "ACTIVE",
"totalCashBalance": "125.50",
"availableCashBalance": "100.00",
"lifetimeCashBalance": "500.00",
"createdAt": "2026-01-01T00:00:00.000Z"
}
]
},
{
"externalReferenceId": "your-user-002",
"accountId": "a90d…",
"success": false,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "The user has not granted the scopes this operation requires. Missing scopes: LIST_PAYMENT."
},
"balances": null
}
]
}
}
}
參數
| 參數 | 型別 | 說明 |
|---|---|---|
targetSpec.mode | BulkTargetMode! | ALL_CONNECTED 或 SELECTED。 |
targetSpec.targets | [String!] | 要鎖定的 externalReferenceId。SELECTED 時必填；ALL_CONNECTED 時忽略。重複值會被移除；結果順序依此清單排列。最多 100 筆。 |
回應欄位
| 欄位 | 說明 |
|---|---|
results[].success | 是否成功回傳該目標的餘額。 |
results[].error | 當 success 為 false 時會出現。錯誤代碼見概觀。 |
results[].balances | 該使用者的現金餘額。當授權僅限於特定消費帳戶時，僅回傳被允許的消費帳戶。 |
targetCount / successCount / failureCount | 請求層級的彙總。 |
若目標的授權僅限於特定消費帳戶，則只會回傳那些帳戶的餘額 —— 自動生效，無需額外參數。