获取批量交易

以单一扁平、基于键集分页的列表返回你所连接用户的交易，按最新优先。每一行都携带其所属用户的 externalReferenceId 和 accountId。没有每用户上限——使用 nextCursor 在该时间窗口内跨所有目标用户遍历每一笔交易。当未提供日期过滤时，默认取最近 90 天。

破坏性变更。 该查询此前返回 results，每个目标用户一个条目，每个条目最多包含 20 笔交易。现在改为返回扁平的 transactions 列表并使用游标分页。参见从按目标返回迁移。

要求

Authorization: Basic <API_KEY>（你的应用程序 API key）
你的应用程序已启用批量 API 能力
每个目标用户授权中具备 LIST_PAYMENT 和 LIST_PURCHASES scope

失败会按目标单独报告，且不会导致整个请求失败。有关目标模型与错误代码，参见批量 API 概览。

查询

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

变量

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

响应

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

参数

参数	类型	说明
`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 天。 交易按月分区存储，窗口内的每个分区都会按目标扫描，因此更宽的窗口会提高每页成本——不是免费的。需要更长历史请使用导出。

目标选择

targetSpec.mode 可为 SELECTED（在 targets 中点名用户，使用你连接时的 externalReferenceId）或 ALL_CONNECTED（你应用上拥有有效授权的所有用户）。重复的 targets 会被去重。此查询最多接受1,000 个目标用户。超过此数量请使用异步导出。

响应字段

字段	类型	说明
`transactions`	`[BulkTransaction!]!`	本页跨所有目标用户的交易，按最新优先，每条均归属到其用户。
`errors`	`[BulkTargetFailure!]!`	被跳过或失败的目标。仅出现在第一页（后续页为空），并限制为最多 100 条样本，以避免大范围扫描返回巨量负载。请使用 `failedTargetCount` 获取真实总数。
`totalCount`	`Int`	跨所有页面匹配请求的交易总数。通过 `includeTotalCount` 选择加入，且只在第一页计算；否则为 `null`。会额外扫描一次窗口，仅在需要展示总数时请求。
`targetCount`	`Int!`	本次请求涉及的目标用户数量。
`succeededTargetCount`	`Int!`	本次请求被授权可读取的目标用户数量——已解析且具备所需 scopes。与本页内容无关：窗口内无交易的已授权用户仍计数。
`failedTargetCount`	`Int!`	无法读取的目标用户数量。每一页均返回（不同于 `errors`），且即使 `errors` 被截断为 100 条样本也提供真实总数。
`nextCursor`	`String`	下一页的不透明游标；最后一页为 `null`。基于键集，能在并发写入下保持稳定。
`hasMore`	`Boolean!`	是否在本页之后还有更多交易。

`BulkTransaction`

字段	类型	说明
`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`

字段	类型	说明
`externalReferenceId`	`String`	目标的你方引用 id（若可用）。
`accountId`	`UUID`	当目标已解析时的账户 id。
`code`	`String!`	机器可读的失败原因（见下）。
`message`	`String!`	人类可读的失败详情。

`code`	含义
`TARGET_NOT_CONNECTED`	该 id 不是当前与你的应用相连接的用户。
`INVALID_TARGET_IDENTIFIER`	该 id 不是有效标识符。
`INSUFFICIENT_SCOPE`	用户授权缺少 `LIST_PAYMENT` 和/或 `LIST_PURCHASES`。
`ACCOUNT_NOT_PERMITTED`	该授权不允许对所请求的消费账户执行此操作。

失败的目标不会导致请求失败。

请求级错误

仅在以下情况下拒绝整个请求：

条件	消息
`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.`

……以及常见的认证与能力相关失败。

分页

先读取第一页，然后跟随 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
  }
}

由于分页基于键集而非偏移，分页过程中写入的新交易不会跨页边界移动已读行，也不会产生重复。

从按目标返回迁移

之前	现在
`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 所含的更丰富交易字段时。通过 submitBulkOperation 提交 GET_TRANSACTIONS_EXPORT，轮询 getBulkOperationJob，并从短期有效的 resultUrl 下载 NDJSON。参见批量操作。

​要求

​查询

​变量

​响应

​参数

​目标选择

​响应字段

​BulkTransaction

​BulkTargetFailure

​请求级错误

​分页

​从按目标返回迁移

​何时改用导出

要求

查询

变量

响应

参数

目标选择

响应字段

`BulkTransaction`

`BulkTargetFailure`

请求级错误

分页

从按目标返回迁移

何时改用导出