> ## 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 天**。

## Requirements

* `Authorization: Basic <API_KEY>`（您的應用程式 API 金鑰）
* 您的應用程式已啟用 **批次 API 能力**
* 每個目標使用者的授權需含有 `LIST_PAYMENT` 與 `LIST_PURCHASES` 範圍

錯誤會以每個目標為單位回報，不會使整個請求失敗。請參閱 [Bulk API Overview](/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
            }
          ]
        }
      ]
    }
  }
}
```

## Arguments

| Argument          | Type                   | Description                                           |
| ----------------- | ---------------------- | ----------------------------------------------------- |
| `targetSpec`      | `BulkTargetSpecInput!` | 目標選取。最多 100 個目標。請見[Overview](/bulk-api)。              |
| `createdGte`      | `DateTime`             | 只包含在此時間「當時或之後」建立的交易。預設為 `createdLte` 之前 90 天。         |
| `createdLte`      | `DateTime`             | 只包含在此時間「當時或之前」建立的交易。預設為現在。                            |
| `includeMetadata` | `Boolean`              | 另外回傳 `memo` 與 `transactionCategory`。速度較慢；預設為 `false`。 |

## Response fields

| Field                                           | Description                                     |
| ----------------------------------------------- | ----------------------------------------------- |
| `results[].transactions`                        | 視窗內最多 20 筆最新交易，依新到舊排序。當授權是針對特定消費帳戶時，僅限於允許的消費帳戶。 |
| `results[].totalCount`                          | 此目標在視窗內符合條件的交易總數。                               |
| `results[].hasNextPage`                         | 當此目標有超過已回傳的 20 筆時為 `true`。                      |
| `targetCount` / `successCount` / `failureCount` | 請求層級彙總。                                         |

## 限制與取得完整歷史

* 每個目標 **20 筆交易**，且每次請求的視窗最多 **90 天**。超過 90 天的視窗會被拒絕——請縮小範圍或使用匯出功能。
* 當 `hasNextPage` 為 `true` 或 `totalCount` 大於已回傳數量時，表示尚有更多資料。此受限查詢不會無聲截斷；若需完整歷史，請使用 **非同步交易匯出**（即將推出）。
* 將 `includeMetadata: true` 會為每筆交易加入 `memo` 與 `transactionCategory`，但會增加延遲。批次路徑不含附件連結——若需完整中繼資料請使用匯出功能。