批次取得交易

以單一扁平、鍵集合分頁的清單（最新在前）回傳你所連接使用者的交易。每一列都帶有所屬使用者的 externalReferenceId 與 accountId。沒有每位使用者的上限 — 使用 nextCursor 分頁即可遍歷視窗內所有目標使用者的每筆交易。若未提供日期篩選，預設為最近 90 天。

重大變更。 此查詢先前會回傳 results，每個目標使用者一筆條目，且各自最多含 20 筆交易。現在改為回傳扁平的 transactions 清單並以游標分頁。請參見從每目標回應遷移。

Requirements

Authorization: Basic <API_KEY>（你的應用程式 API 金鑰）
你的應用程式啟用批次 API 能力
每個目標使用者的授權需具備 LIST_PAYMENT 與 LIST_PURCHASES 範圍

失敗以每個目標為單位回報，不會使整體請求失敗。請參見 Bulk API Overview 以了解目標模型與錯誤代碼。

Query

query GetBulkTransactions(
  $targetSpec: BulkTargetSpecInput!
  $createdGte: DateTime
  $createdLte: DateTime
  $includeMetadata: Boolean
  $limit: Int
  $after: String
  $includeTotalCount: Boolean
) {
  getBulkTransactions(
    targetSpec: $targetSpec
    createdGte: $createdGte
    createdLte: $createdLte
    includeMetadata: $includeMetadata
    limit: $limit
    after: $after
    includeTotalCount: $includeTotalCount
  ) {
    transactions {
      externalReferenceId
      accountId
      recordId
      transactionType
      amount
      status
      createdAt
      memo
      transactionCategory
    }
    errors {
      externalReferenceId
      accountId
      code
      message
    }
    totalCount
    targetCount
    succeededTargetCount
    failedTargetCount
    nextCursor
    hasMore
  }
}

Variables

{
  "targetSpec": { "mode": "SELECTED", "targets": ["your-user-001", "your-user-002"] },
  "createdGte": null,
  "createdLte": null,
  "includeMetadata": false,
  "limit": 100,
  "after": null,
  "includeTotalCount": true
}

Response

{
  "data": {
    "getBulkTransactions": {
      "transactions": [
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "recordId": "rec-1",
          "transactionType": "GIFT_CARD_PURCHASE",
          "amount": 25.0,
          "status": "SETTLED",
          "createdAt": "2026-07-01T00:00:00.000Z",
          "memo": null,
          "transactionCategory": null
        },
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "recordId": "rec-2",
          "transactionType": "DEPOSIT",
          "amount": 100.0,
          "status": "SETTLED",
          "createdAt": "2026-06-30T18:12:04.000Z",
          "memo": null,
          "transactionCategory": null
        }
      ],
      "errors": [
        {
          "externalReferenceId": "your-user-002",
          "accountId": null,
          "code": "TARGET_NOT_CONNECTED",
          "message": "The id does not correspond to a user currently connected to your application."
        }
      ],
      "totalCount": 1284,
      "targetCount": 2,
      "succeededTargetCount": 1,
      "failedTargetCount": 1,
      "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2…",
      "hasMore": true
    }
  }
}

Arguments

Argument	Type	Description
`targetSpec`	`BulkTargetSpecInput!`	目標選擇。請見目標設定。
`createdGte`	`DateTime`	僅包含在此時間或之後建立的交易。預設為 `createdLte` 往前 90 天。不得晚於 `createdLte`。
`createdLte`	`DateTime`	僅包含在此時間或之前建立的交易。預設為現在。
`includeMetadata`	`Boolean`	也回傳 `memo` 與 `transactionCategory`。較慢；預設為 `false`。
`limit`	`Int`	此頁的交易數上限。預設與最大值皆為 `100`。較大的值會被壓制為上限，而非被拒絕。
`after`	`String`	先前回應中的不透明游標 `nextCursor`。第一頁請省略。
`includeTotalCount`	`Boolean`	也回傳 `totalCount`。需要對視窗進行第二次掃描，因此預設為 `false`。建議以 `hasMore`/`nextCursor` 驅動分頁。

日期視窗界定資料範圍；limit 則界定單一頁面。視窗最長可跨 365 天。 交易以月份分區儲存，而視窗內的每個分區都會針對每個目標進行掃描，因此視窗越寬，每頁成本越高——並非免費。若需更長期的歷史，請使用匯出功能。

Targeting

targetSpec.mode 可為 SELECTED（在 targets 中列出使用者，使用你連接時的 externalReferenceId）或 ALL_CONNECTED（你的應用程式上所有具有效授權的使用者）。重複的 targets 會被移除。此查詢最多接受1,000 位目標使用者。若超過，請使用非同步匯出。

Response fields

Field	Type	Description
`transactions`	`[BulkTransaction!]!`	這一頁涵蓋所有目標使用者的交易，最新在前，每筆皆歸屬於其使用者。
`errors`	`[BulkTargetFailure!]!`	被略過或失敗的目標。僅在第一頁（後續頁面為空），且上限為取樣 100 筆，避免大型掃描回傳過大的酬載。請使用 `failedTargetCount` 取得真實總數。
`totalCount`	`Int`	符合請求的總交易數，跨越所有頁面——包含每個目標、整個視窗。需透過 `includeTotalCount` 選擇性啟用，且只在第一頁計算；否則為 `null`。因需第二次掃描視窗，僅在需要顯示總數時才要求。
`targetCount`	`Int!`	此請求涵蓋的目標使用者數量。
`succeededTargetCount`	`Int!`	此請求獲授權可讀取的目標使用者數量——已解析，且具有所需的 scopes。與本頁內容無關：在視窗內沒有交易的已授權使用者仍會被計入。
`failedTargetCount`	`Int!`	無法讀取的目標使用者數量。每一頁皆回傳（不同於 `errors`），且即使 `errors` 因 100 筆取樣而截斷，此欄位仍為真實總數。
`nextCursor`	`String`	下一頁的不透明游標；當為最後一頁時為 `null`。為鍵集合（keyset）基礎，能在併發寫入時保持穩定。
`hasMore`	`Boolean!`	是否在此頁之外還有更多交易。

`BulkTransaction`

Field	Type	Description
`externalReferenceId`	`String`	此交易所屬使用者的你的參考識別碼。
`accountId`	`UUID!`	此交易所屬使用者的 Fluz 帳戶 ID。
`recordId`	`UUID`	交易記錄的唯一識別碼。
`transactionType`	`String`	交易種類的顯示型標籤，例如 `"Account Transfer - In"`。非列舉——請見下方說明。
`amount`	`Float!`	交易金額。
`status`	`TransactionStatus`	`PENDING` 或 `SETTLED`。
`createdAt`	`DateTime`	交易建立時間。
`memo`	`String`	僅在 `includeMetadata: true` 時填入。
`transactionCategory`	`String`	僅在 `includeMetadata: true` 時填入。

需注意的四個行為：

transactionType 是人類可讀的標籤，並非穩定的列舉——其值看起來像 "Account Transfer - In"，而非 TRANSFER。請勿在程式碼中以此欄位進行分支；請以 recordId 與金額/正負號處理邏輯，並將此欄位視為顯示用文字。
僅回傳 PENDING 與 SETTLED 的交易——被拒與其他非基準記錄會被排除，與單一使用者交易介面一致。
排序為全串流的最新在前（createdAt 遞減，若同時則以 recordId，再以使用者打破平手）。
共享帳戶上的同一筆交易，對每個可見授權各出現一次——會有兩筆擁有相同 recordId 但不同 externalReferenceId 的歸屬列。

BulkTransaction 是目的明確且精簡的型別。它不是單一使用者交易查詢所回傳的完整 Transaction 型別——以上欄位即為完整集合。若需更豐富的逐筆交易資料，請使用非同步匯出。

`BulkTargetFailure`

Field	Type	Description
`externalReferenceId`	`String`	目標的你的參考識別碼（若可用）。
`accountId`	`UUID`	當目標已解析時的目標帳戶 ID。
`code`	`String!`	機器可讀的失敗原因（見下）。
`message`	`String!`	人類可讀的失敗細節。

`code`	Meaning
`TARGET_NOT_CONNECTED`	該 id 並非目前已連接至你應用程式的使用者。
`INVALID_TARGET_IDENTIFIER`	該 id 不是有效的識別碼。
`INSUFFICIENT_SCOPE`	使用者的授權缺少 `LIST_PAYMENT` 與/或 `LIST_PURCHASES`。
`ACCOUNT_NOT_PERMITTED`	該授權不允許在請求的消費帳戶上執行此操作。

失敗的目標不會使請求失敗。 同時選擇兩種識別碼。 對於你在連接授權時未提供 externalReferenceId 的授權，其值將為 null，因此單獨使用它可能無法識別出哪位使用者失敗。當目標已解析時，accountId 會被填入——這適用於 INSUFFICIENT_SCOPE 與 ACCOUNT_NOT_PERMITTED——而僅在 TARGET_NOT_CONNECTED 與 INVALID_TARGET_IDENTIFIER（無法解析）時為 null。查詢 errors { externalReferenceId accountId code message } 可確保每筆條目至少能由兩者之一識別。

Request-level errors

以上皆為每目標錯誤。以下則會拒絕整體請求，回傳 data.getBulkTransactions: null 並伴隨 GraphQL 錯誤。請以 extensions.code 分支，不要依賴錯誤訊息文字——措辭可能變更，代碼不會。

Condition	`extensions.code`	`extensions.errorName`	`statusCode`
視窗超過 365 天	`APPLICATIONS-0009`	`InvalidDateWindow`	422
`createdGte` 晚於 `createdLte`	`APPLICATIONS-0009`	`InvalidDateWindow`	422
`after` 游標格式錯誤或被竄改	`APPLICATIONS-0010`	`InvalidPaginationCursor`	422
超過 1,000 位目標使用者	`APPLICATIONS-0008`	`TargetLimitExceeded`	422
你的應用程式未啟用 Bulk API	`APPLICATIONS-0003`	`BulkApiAccessDenied`	403
缺少憑證，或非 Basic 認證方案	`AUTH-0002`	`InvalidCredentials`	401

上述兩個日期錯誤共用代碼——兩者皆表示「你要求的區間不可用」——而 message 會加以區分：

{
  "errors": [
    {
      "message": "The requested window exceeds the 365-day maximum. Narrow the range, or use the asynchronous transactions export for a wider pull.",
      "path": ["getBulkTransactions"],
      "extensions": {
        "errorName": "InvalidDateWindow",
        "code": "APPLICATIONS-0009",
        "statusCode": 422,
        "userFriendly": true
      }
    }
  ],
  "data": { "getBulkTransactions": null }
}

任何被更動過的游標——截斷、重新編碼、手動編輯——在到達資料庫之前就會以 APPLICATIONS-0010 失敗。請將其視為「從第一頁重新開始」，而非可重試的錯誤。

Paging

讀取第一頁，接著沿用 nextCursor，直到 hasMore 為 false。除游標外，跨頁請保持其他引數完全相同——游標編碼了該特定查詢排序中的位置。

# Page 1: omit `after`. Read errors here — they are first-page only. Ask for totalCount only
# if you actually need it; it costs an extra scan.
{
  getBulkTransactions(targetSpec: { mode: ALL_CONNECTED }, limit: 100, includeTotalCount: true) {
    transactions { recordId externalReferenceId amount createdAt }
    errors { externalReferenceId code message }
    totalCount
    failedTargetCount
    nextCursor
    hasMore
  }
}

# Page 2+: pass the previous nextCursor.
{
  getBulkTransactions(
    targetSpec: { mode: ALL_CONNECTED }
    limit: 100
    after: "eyJjcmVhdGVkQXQiOiIyMDI2LTA2…"
  ) {
    transactions { recordId externalReferenceId amount createdAt }
    nextCursor
    hasMore
  }
}

由於分頁為鍵集合而非位移（offset）基礎，分頁過程中寫入的交易不會讓列跨越頁界或產生重複。

Migrating from the per-target response

Before	Now
`results[]`，每個目標使用者一筆條目	`transactions[]`，每筆交易一筆條目。可於用戶端依 `externalReferenceId` 分組以重建舊結構。
`results[].transactions`（完整 `Transaction`）	頂層 `transactions` 為較精簡的 `BulkTransaction` 型別。
`results[].error`	`errors[]`——扁平的失敗目標清單，僅第一頁，且取樣上限 100 筆。
`results[].totalCount`（每目標）	`totalCount`（整體請求，透過 `includeTotalCount` 選擇，僅第一頁）。不再回傳每目標的總數。
`results[].hasNextPage`（每目標）	`hasMore` + `nextCursor`（整體請求的鍵集合分頁）。
`successCount` / `failureCount`	`succeededTargetCount` / `failedTargetCount`。
每目標 20 筆交易，硬性上限	無每使用者上限。以 `limit`（預設與最大 100）界定頁面大小。
90 天視窗為硬性上限	90 天改為預設；硬性上限為 365 天。
100 位目標使用者，硬性上限	1,000 位目標使用者。

When to use the export instead

getBulkTransactions 可以透過分頁走訪完整歷史，因此匯出適用於你不想逐頁讀取的情境——超過 1,000 位使用者、超過一年以上的視窗、排程批次作業，或當你需要超出 BulkTransaction 所載欄位的更豐富逐筆資料。提交 GET_TRANSACTIONS_EXPORT 至 submitBulkOperation，輪詢 getBulkOperationJob，並從短效的 resultUrl 下載 NDJSON。請參見 Bulk Operations。

​Requirements

​Query

​Variables

​Response

​Arguments

​Targeting

​Response fields

​BulkTransaction

​BulkTargetFailure

​Request-level errors

​Paging

​Migrating from the per-target response

​When to use the export instead

Requirements

Query

Variables

Response

Arguments

Targeting

Response fields

`BulkTransaction`

`BulkTargetFailure`

Request-level errors

Paging

Migrating from the per-target response

When to use the export instead