获取批量交易

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

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

要求

Authorization: Basic <API_KEY>（你的应用程序 API key）
你的应用具备批量 API 能力
每个目标用户授权上具备LIST_PAYMENT与LIST_PURCHASES范围

失败按目标报告，且不会导致整个请求失败。关于目标模型与错误码，参见批量 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
    }
  }
}

参数

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

目标选择

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

响应字段

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`	交易类型的展示式标签，例如`"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`	目标的你的引用 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`	该授权不允许对请求的消费账户执行此操作。

目标失败不会导致请求失败。 同时选择两个标识符。 对任何你在连接时未提供externalReferenceId的授权，此字段将为null，单独使用时可能无法指明是哪位用户失败。只要目标已解析，accountId就会被填写——这在INSUFFICIENT_SCOPE与ACCOUNT_NOT_PERMITTED情形均成立；仅在TARGET_NOT_CONNECTED与INVALID_TARGET_IDENTIFIER（未解析）时为null。查询errors { externalReferenceId accountId code message }意味着每条记录至少能通过两者之一被识别。

请求级错误

上述均为按目标的错误。以下情况会拒绝整个请求，返回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
你的应用未启用批量 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失败。将其视为“从第一页重新开始”，而非可重试错误。

分页

读取第一页，然后跟随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之外更丰富的逐笔字段时。通过submitBulkOperation提交GET_TRANSACTIONS_EXPORT，轮询getBulkOperationJob，并从短期有效的resultUrl下载 NDJSON。参见批量操作。

​要求

​查询

​变量

​响应

​参数

​目标选择

​响应字段

​BulkTransaction

​BulkTargetFailure

​请求级错误

​分页

​从按目标的响应迁移

​何时改用导出

要求

查询

变量

响应

参数

目标选择

响应字段

`BulkTransaction`

`BulkTargetFailure`

请求级错误

分页

从按目标的响应迁移

何时改用导出