> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取批量交易

> 在一次调用中返回最多 100 个已连接用户的近期交易，按时间从新到旧排序，默认返回过去 90 天的数据。

在一次调用中返回最多 **100 个已连接用户** 的近期交易——每个目标最多 **20 条**，按时间从新到旧排序，默认窗口为 **过去 90 天**。

## 要求

* `Authorization: Basic <API_KEY>`（你的应用程序 API 密钥）
* 你的应用启用 **批量 API 能力**
* 每个目标用户的授权包含 `LIST_PAYMENT` 和 `LIST_PURCHASES` scope

失败按目标分别报告，永不导致整个请求失败。参见 [批量 API 概览](/bulk-api) 了解目标模型与错误代码。

## Query

```graphql theme={null}
query GetBulkTransactions(
  $targetSpec: BulkTargetSpecInput!
  $createdGte: DateTime
  $createdLte: DateTime
  $includeMetadata: Boolean
) {
  getBulkTransactions(
    targetSpec: $targetSpec
    createdGte: $createdGte
    createdLte: $createdLte
    includeMetadata: $includeMetadata
  ) {
    targetCount
    successCount
    failureCount
    results {
      externalReferenceId
      accountId
      success
      error { code message }
      totalCount
      hasNextPage
      transactions {
        recordId
        transactionType
        amount
        status
        createdAt
        memo
        transactionCategory
      }
    }
  }
}
```

### Variables

```json theme={null}
{
  "targetSpec": { "mode": "SELECTED", "targets": ["your-user-001"] },
  "createdGte": null,
  "createdLte": null,
  "includeMetadata": false
}
```

## Response

```json theme={null}
{
  "data": {
    "getBulkTransactions": {
      "targetCount": 1,
      "successCount": 1,
      "failureCount": 0,
      "results": [
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "success": true,
          "error": null,
          "totalCount": 42,
          "hasNextPage": true,
          "transactions": [
            {
              "recordId": "rec-1",
              "transactionType": "GIFT_CARD_PURCHASE",
              "amount": 25.0,
              "status": "SETTLED",
              "createdAt": "2026-07-01T00:00:00.000Z",
              "memo": null,
              "transactionCategory": null
            }
          ]
        }
      ]
    }
  }
}
```

## 参数

| 参数                | 类型                     | 说明                                                 |
| ----------------- | ---------------------- | -------------------------------------------------- |
| `targetSpec`      | `BulkTargetSpecInput!` | 目标选择。最多 100 个目标。参见[概览](/bulk-api)。                 |
| `createdGte`      | `DateTime`             | 仅包含在此时间或之后创建的交易。默认为 `createdLte` 之前 90 天。          |
| `createdLte`      | `DateTime`             | 仅包含在此时间或之前创建的交易。默认为现在。                             |
| `includeMetadata` | `Boolean`              | 还返回 `memo` 和 `transactionCategory`。更慢；默认为 `false`。 |

## 响应字段

| 字段                                              | 说明                                                     |
| ----------------------------------------------- | ------------------------------------------------------ |
| `results[].transactions`                        | 窗口内最多 20 条最新交易，按时间从新到旧排序。当授权按消费账户范围限定时，仅返回被允许的消费账户的数据。 |
| `results[].totalCount`                          | 此目标在该窗口内匹配的交易总数。                                       |
| `results[].hasNextPage`                         | 当此目标的交易多于已返回的 20 条时为 `true`。                           |
| `targetCount` / `successCount` / `failureCount` | 请求级别汇总。                                                |

## 限制与获取完整历史

* 每个目标 **20 条交易**，每次请求的时间窗口 **最长为 90 天**。超过 90 天的窗口会被拒绝——请缩小范围或使用导出。
* 当 `hasNextPage` 为 `true` 或 `totalCount` 超过已返回数量时，表示还有更多数据。此受限查询从不静默截断；要获取完整历史，请使用 **异步交易导出**（即将推出）。
* `includeMetadata: true` 会为每笔交易添加 `memo` 和 `transactionCategory`，但会带来一定的延迟成本。批量路径不包含附件链接——若需完整元数据，请使用导出。