取得大量交易

以單一扁平、鍵集合分頁的列表（新到舊）傳回所有已連結使用者的交易。每一列都包含該交易所屬使用者的 externalReferenceId 與 accountId。沒有每位使用者的筆數上限——使用 nextCursor 進行分頁，即可在時間窗格內遍歷所有目標使用者的每筆交易。若未提供日期篩選，預設為最近 90 天。

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

Requirements

Authorization: Basic <API_KEY>（您的應用程式 API key）
應用程式具備大量 API 能力
每個目標使用者授權包含 LIST_PAYMENT 與 LIST_PURCHASES 範圍

失敗會以每個目標為單位回報，且不會使整個請求失敗。請參閱大量 API 概觀以了解目標模型與錯誤碼。

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!`	此請求具備讀取授權的目標使用者數——已解析且擁有所需範圍。獨立於本頁內容：在窗格內沒有交易的授權使用者仍會計入。
`failedTargetCount`	`Int!`	無法讀取的目標使用者數。每一頁皆回傳（不同於 `errors`），且即使 `errors` 因 100 筆樣本上限而被截斷，這也是正確總數。
`nextCursor`	`String`	下一頁的不透明游標；最後一頁為 `null`。基於鍵集合，因此在並發寫入下仍穩定。
`hasMore`	`Boolean!`	此頁之後是否仍有更多交易。

`BulkTransaction`

Field	Type	Description
`externalReferenceId`	`String`	此交易所屬使用者的您的參考 ID。
`accountId`	`UUID!`	此交易所屬使用者的 Fluz 帳戶 ID。
`recordId`	`UUID`	交易紀錄的唯一識別碼。
`transactionType`	`String`	例如 `GIFT_CARD_PURCHASE`、`DEPOSIT`、`WITHDRAWAL`、`TRANSFER`。
`amount`	`Float!`	交易金額。
`status`	`TransactionStatus`	`PENDING` 或 `SETTLED`。
`createdAt`	`DateTime`	交易建立時間。
`memo`	`String`	僅在 `includeMetadata: true` 時提供。
`transactionCategory`	`String`	僅在 `includeMetadata: true` 時提供。

需注意的三項行為：

只回傳 PENDING 與 SETTLED 的交易——拒絕與其他非基線紀錄會被排除，與單一使用者交易介面一致。
排序為整體扁平串流的新到舊（createdAt 遞減，遇到相同時以 recordId、再以使用者作為決勝）。
共用帳戶上的同一筆交易，會針對每個可見授權各出現一次——兩筆具有相同 recordId 但不同 externalReferenceId 的列。

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

`BulkTargetFailure`

Field	Type	Description
`externalReferenceId`	`String`	目標的您的參考 ID（若可用）。
`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`	此授權不允許對請求的消費帳戶執行此操作。

單一目標的失敗不會造成整個請求失敗。

Request-level errors

僅在以下情況下整個請求會被拒絕：

Condition	Message
`createdGte` 晚於 `createdLte`	`createdGte must not be after createdLte.`
畸形或被竄改的 `after`	`Invalid pagination cursor.`
超過 1,000 位目標使用者	Target cap exceeded.
時間窗格超過 365 天	`The requested window exceeds the 365-day maximum.`

……以及一般的驗證與能力相關失敗。

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
  }
}

因為分頁是基於鍵集合而非位移，於分頁過程中寫入的新交易，不會使列在頁面邊界間移動或產生重複。

從每目標回應遷移

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 位目標使用者。

何時改用匯出

getBulkTransactions 可藉由分頁走完整歷史，因此匯出適用於不想透過分頁提取的情境——超過 1,000 位使用者、超過一年的時間窗格、排程的批次作業，或當您需要超出 BulkTransaction 所含欄位的更豐富交易資料時。提交 GET_TRANSACTIONS_EXPORT 透過 submitBulkOperation，以 getBulkOperationJob 輪詢，並從短效的 resultUrl 下載 NDJSON。請參閱大量作業。

​Requirements

​Query

​Variables

​Response

​Arguments

​Targeting

​Response fields

​BulkTransaction

​BulkTargetFailure

​Request-level errors

​Paging

​從每目標回應遷移

​何時改用匯出

Requirements

Query

Variables

Response

Arguments

Targeting

Response fields

`BulkTransaction`

`BulkTargetFailure`

Request-level errors

Paging

從每目標回應遷移

何時改用匯出