取得所有交易

概觀

Transactions API 讓你擷取與你的帳戶相關的完整金融交易歷史。這包含購買、存款、提領、轉帳、帳單支付，以及所有其他金融活動。 端點類型: GraphQL Query
驗證: 必需（JWT Bearer Token）
必要範圍: LIST_PAYMENT 與 LIST_PURCHASES
速率限制: 套用標準 GraphQL 速率限制

快速開始

基本查詢

query GetTransactions {
  getTransactions {
    transactions {
      recordId
      transactionType
      amount
      status
      channel
      connectedAppId
      connectedAppName
      createdAt
    }
    totalCount
    hasNextPage
  }
}

查詢結構

getTransactions(
  filter: TransactionFilterInput
  paginate: OffsetInput
): TransactionConnection!

參數

參數	類型	必填	說明
`filter`	`TransactionFilterInput`	否	交易的篩選條件
`paginate`	`OffsetInput`	否	分頁參數（預設：limit=20, offset=0）

回應結構

TransactionConnection

type TransactionConnection {
  transactions: [Transaction]
  totalCount: Int!
  hasNextPage: Boolean!
}

欄位	類型	說明
`transactions`	`[Transaction]`	交易紀錄陣列
`totalCount`	`Int!`	符合篩選之交易總數（用於分頁）
`hasNextPage`	`Boolean!`	是否還有更多結果

篩選選項

TransactionFilterInput

input TransactionFilterInput {
  # Record & Status
  recordId: [UUID]
  status: [TransactionStatus]
  
  # Amount Filters
  amount: Float
  amountGte: Float
  amountLte: Float
  finalAmount: Float
  finalAmountGte: Float
  finalAmountLte: Float
  
  # Cashback Filters
  cashbackAmount: Float
  cashbackAmountGte: Float
  cashbackAmountLte: Float
  cashbackPercentage: Float
  cashbackPercentageGte: Float
  cashbackPercentageLte: Float
  
  # Fee Filters
  feeAmount: Float
  feeAmountGte: Float
  feeAmountLte: Float
  
  # Date Filters
  createdGte: DateTime
  createdLte: DateTime
  updatedGte: DateTime
  updatedLte: DateTime
  
  # Merchant Filters
  merchantId: [UUID]
  merchant: [String]
  
  # Transaction Properties
  transactionType: [String]
  channel: [String!]
  category: [String]
  
  # Virtual Card Filters
  virtualCardProgram: [String]
  virtualCard: [UUID]
  
  # Other
  fundingSource: [String]
  userCashBalanceId: [UUID]
  referenceId: String
  liabilityId: UUID
}

篩選欄位詳細說明

紀錄與狀態篩選

`recordId`

類型: [UUID]
說明: 依特定交易紀錄 ID 篩選。範例:

filter: {
  recordId: ["550e8400-e29b-41d4-a716-446655440000"]
}

`status`

類型: [TransactionStatus]
說明: 依交易狀態篩選。選項:

PENDING - 交易處理中
SETTLED - 交易已成功完成

範例:

filter: {
  status: [SETTLED]
}

金額篩選

`amount`, `amountGte`, `amountLte`

類型: Float
說明: 依確切金額或金額區間（USD）篩選。

amount - 精準金額相符
amountGte - 最低金額（大於等於）
amountLte - 最高金額（小於等於）

範例:

# Transactions between $10 and $500
filter: {
  amountGte: 10.00
  amountLte: 500.00
}

`finalAmount`, `finalAmountGte`, `finalAmountLte`

類型: Float
說明: 依最終金額（金額 + 手續費）篩選。範例:

filter: {
  finalAmountGte: 25.00
}

現金回饋篩選

`cashbackAmount`, `cashbackAmountGte`, `cashbackAmountLte`

類型: Float
說明: 依獲得的現金回饋金額篩選。範例:

# Transactions that earned $5 or more in cashback
filter: {
  cashbackAmountGte: 5.00
}

`cashbackPercentage`, `cashbackPercentageGte`, `cashbackPercentageLte`

類型: Float
說明: 依現金回饋比率百分比篩選。範例:

# Transactions with 5% or higher cashback
filter: {
  cashbackPercentageGte: 5.0
}

手續費篩選

`feeAmount`, `feeAmountGte`, `feeAmountLte`

類型: Float
說明: 依交易手續費金額篩選。範例:

# Transactions with fees
filter: {
  feeAmountGte: 0.01
}

日期篩選

`createdGte`, `createdLte`

類型: DateTime
格式: ISO 8601（例如：2025-01-01T00:00:00Z）
說明: 依交易建立時間區間篩選。範例:

filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}

`updatedGte`, `updatedLte`

類型: DateTime
說明: 依交易最後更新時間區間篩選。

商家篩選

`merchantId`

類型: [UUID]
說明: 依特定商家 ID 篩選。範例:

filter: {
  merchantId: ["550e8400-e29b-41d4-a716-446655440000"]
}

`merchant`

類型: [String]
說明: 依商家名稱篩選（比對 destination 欄位）。範例:

filter: {
  merchant: ["Amazon", "Walmart"]
}

交易屬性

`transactionType`

類型: [String]
說明: 依特定交易類型篩選。 常見值:

Add Money - 存入資金
Gift Card Purchase - 禮品卡購買
Transfer - In - 轉入
Transfer - Out - 轉出
Virtual Card Purchase - 虛擬卡購買
Withdrawal

範例:

filter: {
  transactionType: ["Gift Card Purchase", "Add Money"]
}

`channel`

類型: [String!]
說明: 依平台通道篩選。 常見值:

WEB - 網頁瀏覽器
MOBILE - 行動應用程式
API - API 請求

範例:

filter: {
  channel: ["WEB", "MOBILE"]
}

`category`

類型: [String]
說明: 依交易分類篩選。範例:

filter: {
  category: ["Shopping", "Travel"]
}

虛擬卡篩選

`virtualCardProgram`

類型: [String]
說明: 依虛擬卡計畫／發卡機構篩選。範例:

filter: {
  virtualCardProgram: ["TRANSPECOS", "SUTTON"]
}

`virtualCard`

類型: [UUID]
說明: 依特定虛擬卡 ID 篩選。範例:

filter: {
  virtualCard: ["vc-1", "vc-2"]
}

其他篩選

`fundingSource`

類型: [String]
說明: 搜尋資金來源名稱（對來源或目的地做部分比對）。範例:

filter: {
  fundingSource: ["Visa"]
}

`referenceId`

類型: String
說明: 依外部參考 ID 篩選（例如：購買顯示 ID）。範例:

filter: {
  referenceId: "1000123"
}

`liabilityId`

類型: UUID
說明: 依負債 ID 篩選（用於帳單支付）。

分頁

OffsetInput

input OffsetInput {
  limit: Int = 20
  offset: Int = 0
}

欄位	類型	預設	最大值	說明
`limit`	Int	20	20	每頁要回傳的交易筆數
`offset`	Int	0	-	要略過的交易筆數

範例 - 第 1 頁:

paginate: {
  limit: 20
  offset: 0
}

範例 - 第 2 頁:

paginate: {
  limit: 20
  offset: 20
}

範例 - 檢查是否有更多頁:

query GetTransactions {
  getTransactions(paginate: { limit: 20, offset: 0 }) {
    transactions { record_id }
    hasNextPage  # Use this to determine if there are more results
    totalCount   # Total matching records
  }
}

交易型別

type Transaction {
  record_id: UUID
  user: String!
  account_id: UUID!
  user_id: UUID
  transaction_type: String
  amount: Float!
  destination: String
  source: String
  external_funding_source_activity: Float
  fluz_balance_activity: Float
  fee: Float
  cashback: Float
  
  # Ending balances after transaction
  gift_card_prepayment_balance_available_balance: Float
  gift_card_prepayment_balance_total_balance: Float
  cash_balance_available_balance: Float
  cash_balance_total_balance: Float
  seat_balance_available_balance: Float
  seat_balance_total_balance: Float
  reserve_balance_available_balance: Float
  reserve_balance_total_balance: Float
  other_cash_balance_available_balance: Float
  other_cash_balance_total_balance: Float
  
  status: TransactionStatus
  reference_id: String
  description: String
  note: String
  category: String
  card_last_four: String
  card_display_name: String
  original_currency_amount: Float
  original_currency_code: String
  conversion_rate: Float
  merchant_id: UUID
  descriptor_id: UUID
  virtual_card_program: String
  cashback_rate: Float
  bonus_cashback_rate: Float
  channel: String
  source_type: String
  logo_url: String
  platformInstitutionLogo: String
  challengeLogoUrl: String
  invitedAccountId: UUID
  expectedClearedDate: DateTime
  liability_id: UUID
  is_gift_card_balance_affected: Boolean
  is_cash_balance_affected: Boolean
  is_seat_balance_affected: Boolean
  is_reserve_balance_affected: Boolean
  transfer_id: UUID
  used_user_cash_balance_id: UUID
  connectedAppId: UUID
  connectedAppName: String
  
  memo: String
  transactionCategory: String
  attachmentUrl: String

  created_at: DateTime
  updated_at: DateTime
}

欄位說明

核心交易欄位

欄位	類型	說明
`record_id`	UUID	此交易紀錄的唯一識別碼
`user`	String	與交易相關的使用者顯示名稱
`account_id`	UUID	擁有此交易的帳戶
`user_id`	UUID	發起此交易的使用者
`transaction_type`	String	交易類型（PURCHASE、DEPOSIT 等）
`amount`	Float	主要交易金額（USD）
`source`	String	資金來源（例如：“Bank Card ****1234”）
`destination`	String	資金去向（例如：商家名稱）
`status`	TransactionStatus	目前狀態（PENDING 或 SETTLED）

金融明細

欄位	類型	說明
`external_funding_source_activity`	Float	對外部資金來源（銀行卡／帳戶）的變動
`fluz_balance_activity`	Float	對 Fluz 內部餘額的變動
`fee`	Float	此交易收取的手續費
`cashback`	Float	此交易獲得的現金回饋
`cashback_rate`	Float	現金回饋比率（百分比）
`bonus_cashback_rate`	Float	額外加碼的現金回饋比率

餘額快照

重要: 所有餘額欄位皆顯示此交易「套用後」的餘額。

欄位	說明
`cash_balance_available_balance`	交易後可用現金餘額
`cash_balance_total_balance`	交易後現金總餘額
`seat_balance_available_balance`	交易後可用獎勵餘額
`seat_balance_total_balance`	交易後獎勵總餘額
`gift_card_prepayment_balance_available_balance`	交易後可用預付餘額
`gift_card_prepayment_balance_total_balance`	交易後預付總餘額
`reserve_balance_available_balance`	交易後可用保留餘額
`reserve_balance_total_balance`	交易後保留總餘額
`other_cash_balance_available_balance`	交易後其他現金可用餘額
`other_cash_balance_total_balance`	交易後其他現金總餘額

交易明細

欄位	類型	說明
`reference_id`	String	外部參考（例如：購買顯示 ID）
`description`	String	人類可讀的描述
`note`	String	額外備註
`category`	String	交易分類
`card_last_four`	String	使用卡片的末四碼（若適用）
`card_display_name`	String	付款方式顯示名稱
`memo`	String	附加於此交易的自由文字備忘。可透過 `updateTransactionMetadata` 設定，或於存款、購買與轉帳時設定。
`transactionCategory`	String	附加於此交易的分類標籤。可透過 `updateTransactionMetadata` 設定，或於存款、購買與轉帳時設定。
`attachmentUrl`	String	附加於此交易檔案的簽名 URL。可透過 `updateTransactionMetadata` 設定，或於交易時設定。此 URL 會過期 — 請勿儲存。需要存取檔案時請重新擷取交易。

商家資訊

欄位	類型	說明
`merchant_id`	UUID	商家識別碼
`descriptor_id`	UUID	交易敘述 ID
`logo_url`	String	指向商家／來源 Logo 的 URL

虛擬卡資訊

欄位	類型	說明
`virtual_card_program`	String	虛擬卡計畫（LITHIC、MARQETA 等）

貨幣換算

欄位	類型	說明
`original_currency_amount`	Float	原始幣別金額（用於海外交易）
`original_currency_code`	String	原始幣別代碼（例如：“EUR”）
`conversion_rate`	Float	套用的匯率

中繼資料

欄位	類型	說明
`channel`	String	平台通道（WEB、MOBILE、API）
`source_type`	String	資金來源類型
`liability_id`	UUID	關聯的負債（用於帳單支付）
`transfer_id`	UUID	關聯的轉帳（用於 P2P）
`used_user_cash_balance_id`	UUID	使用的特定現金餘額
`is_gift_card_balance_affected`	Boolean	是否影響禮品卡餘額
`is_cash_balance_affected`	Boolean	是否影響現金餘額
`is_seat_balance_affected`	Boolean	是否影響獎勵餘額
`is_reserve_balance_affected`	Boolean	是否影響保留餘額
`connectedAppId`	UUID	關聯的應用程式 ID
`connectedAppName`	String	關聯的應用程式名稱
`created_at`	DateTime	交易建立時間
`updated_at`	DateTime	交易最後更新時間

範例

範例 1：基本交易清單

查詢:

query GetRecentTransactions {
  getTransactions(
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      status
      cashback
      created_at
    }
    totalCount
    hasNextPage
  }
}

回應:

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "record_id": "550e8400-e29b-41d4-a716-446655440000",
          "transaction_type": "GIFT_CARD_PURCHASE",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "status": "SETTLED",
          "cashback": 2.50,
          "created_at": "2025-01-15T14:30:00Z"
        },
        {
          "record_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "transaction_type": "DEPOSIT",
          "amount": 100.00,
          "description": "Cash Balance Deposit",
          "status": "SETTLED",
          "cashback": 0.00,
          "created_at": "2025-01-14T10:15:00Z"
        }
      ],
      "totalCount": 2,
      "hasNextPage": false
    }
  }
}

範例 2：依日期區間篩選

查詢:

query GetJanuaryTransactions {
  getTransactions(
    filter: {
      createdGte: "2025-01-01T00:00:00Z"
      createdLte: "2025-01-31T23:59:59Z"
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      status
      created_at
    }
    totalCount
    hasNextPage
  }
}

範例 3：僅購買且含餘額

查詢:

query GetPurchaseHistory {
  getTransactions(
    filter: {
      transactionType: ["GIFT_CARD_PURCHASE"]
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      reference_id
      amount
      description
      source
      destination
      cashback
      cashback_rate
      cash_balance_available_balance
      seat_balance_available_balance
      created_at
    }
    totalCount
    hasNextPage
  }
}

回應:

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "record_id": "550e8400-e29b-41d4-a716-446655440000",
          "reference_id": "1000123",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "source": "Visa ****1234",
          "destination": "Amazon",
          "cashback": 2.50,
          "cashback_rate": 5.0,
          "cash_balance_available_balance": 102.50,
          "seat_balance_available_balance": 25.00,
          "created_at": "2025-01-15T14:30:00Z"
        }
      ],
      "totalCount": 1,
      "hasNextPage": false
    }
  }
}

範例 4：高現金回饋交易

查詢:

query GetHighCashbackTransactions {
  getTransactions(
    filter: {
      cashbackPercentageGte: 5.0
      status: [SETTLED]
    }
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      cashback
      cashback_rate
      status
      created_at
    }
    totalCount
  }
}

範例 5：金額區間篩選

查詢:

query GetMediumTransactions {
  getTransactions(
    filter: {
      amountGte: 50.00
      amountLte: 200.00
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      amount
      transaction_type
      description
      created_at
    }
    totalCount
    hasNextPage
  }
}

範例 6：虛擬卡交易

查詢:

query GetVirtualCardTransactions {
  getTransactions(
    filter: {
      virtualCardProgram: ["LITHIC", "MARQETA"]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      amount
      description
      virtual_card_program
      merchant_id
      status
      created_at
    }
    totalCount
  }
}

範例 7：分頁示例

查詢 - 取得第一頁並檢查是否有更多:

query GetFirstPage {
  getTransactions(paginate: { limit: 20, offset: 0 }) {
    transactions {
      record_id
      amount
      transaction_type
    }
    totalCount
    hasNextPage
  }
}

回應顯示 hasNextPage=true:

{
  "data": {
    "getTransactions": {
      "transactions": [...],
      "totalCount": 150,
      "hasNextPage": true
    }
  }
}

查詢 - 取得第二頁:

query GetSecondPage {
  getTransactions(paginate: { limit: 20, offset: 20 }) {
    transactions {
      record_id
      amount
      transaction_type
    }
    totalCount
    hasNextPage
  }
}

錯誤處理

常見錯誤

缺少或無效權杖

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

HTTP 狀態: 401 Unauthorized

權限不足

{
  "errors": [
    {
      "message": "Insufficient permissions: LIST_PAYMENT and LIST_PURCHASES scopes required",
      "extensions": {
        "code": "FORBIDDEN",
        "requiredScopes": ["LIST_PAYMENT", "LIST_PURCHASES"]
      }
    }
  ]
}

HTTP 狀態: 403 Forbidden

無效的篩選參數

{
  "errors": [
    {
      "message": "Invalid date format for createdGte",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

HTTP 狀態: 400 Bad Request

超出速率限制

{
  "errors": [
    {
      "message": "Rate limit exceeded. Please try again later.",
      "extensions": {
        "code": "RATE_LIMITED",
        "retryAfter": 60
      }
    }
  ]
}

HTTP 狀態: 429 Too Many Requests

最佳實務

1. 有效運用分頁

一律檢查 hasNextPage 來判斷是否還有更多結果：

async function fetchAllTransactions() {
  const allTransactions = [];
  let offset = 0;
  const limit = 20;
  
  while (true) {
    const result = await getTransactions({ 
      paginate: { limit, offset } 
    });
    
    allTransactions.push(...result.transactions);
    
    if (!result.hasNextPage) break;
    offset += limit;
  }
  
  return allTransactions;
}

2. 僅請求所需欄位

只指定你需要的欄位以減少回應大小：

# Good - minimal fields
getTransactions {
  transactions {
    record_id
    amount
    transaction_type
    created_at
  }
  totalCount
  hasNextPage
}

# Less efficient - requesting all 40+ fields
getTransactions {
  transactions {
    record_id
    transaction_type
    amount
    ... (all fields)
  }
}

3. 查詢歷史資料時使用日期篩選

在查詢較早期的交易時，一律使用日期篩選：

# Good
filter: {
  createdGte: "2024-01-01T00:00:00Z"
  createdLte: "2024-12-31T23:59:59Z"
}

4. 快取已結清的交易

status: SETTLED 的交易為不可變更，適合快取：

// Example caching strategy
const cacheKey = `transactions:${accountId}:${createdGte}:${createdLte}`;
let result = cache.get(cacheKey);

if (!result) {
  result = await getTransactions({
    filter: { status: ['SETTLED'], createdGte, createdLte }
  });
  cache.set(cacheKey, result, '1 hour');
}

5. 高效組合篩選條件

先用範圍條件縮小結果再套用其他篩選：

# Efficient - date range first
filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
  transactionType: ["GIFT_CARD_PURCHASE"]
  amountGte: 50.00
}

速率限制

資源	限制	視窗
每使用者請求數	100	1 分鐘
每 IP 請求數	300	1 分鐘

標頭:

X-RateLimit-Limit - 允許的最大請求數
X-RateLimit-Remaining - 目前視窗剩餘請求數
X-RateLimit-Reset - 速率限制重置時間（Unix timestamp）

程式碼範例

JavaScript/TypeScript

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://transactional-graph.fluzapp.com/api/v1/graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: `Bearer ${accessToken}`,
  },
});

const GET_TRANSACTIONS = gql`
  query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) {
    getTransactions(filter: $filter, paginate: $paginate) {
      transactions {
        record_id
        transaction_type
        amount
        description
        status
        cashback
        created_at
      }
      totalCount
      hasNextPage
    }
  }
`;

async function fetchTransactions() {
  const { data } = await client.query({
    query: GET_TRANSACTIONS,
    variables: {
      filter: {
        status: ['SETTLED'],
        createdGte: '2025-01-01T00:00:00Z',
      },
      paginate: {
        limit: 20,
        offset: 0,
      },
    },
  });
  
  return data.getTransactions;
}

Python

import requests

def get_transactions(access_token, created_gte=None, created_lte=None, limit=20, offset=0):
    url = "https://transactional-graph.fluzapp.com/api/v1/graphql"
    
    query = """
        query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) {
            getTransactions(filter: $filter, paginate: $paginate) {
                transactions {
                    record_id
                    transaction_type
                    amount
                    description
                    status
                    cashback
                    created_at
                }
                totalCount
                hasNextPage
            }
        }
    """
    
    variables = {
        "filter": {},
        "paginate": {
            "limit": limit,
            "offset": offset
        }
    }
    
    if created_gte:
        variables["filter"]["createdGte"] = created_gte
    if created_lte:
        variables["filter"]["createdLte"] = created_lte
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(
        url,
        json={"query": query, "variables": variables},
        headers=headers
    )
    
    return response.json()["data"]["getTransactions"]

# Usage
result = get_transactions(
    access_token="your_token_here",
    created_gte="2025-01-01T00:00:00Z",
    limit=20
)

print(f"Found {result['totalCount']} transactions")
print(f"Has more pages: {result['hasNextPage']}")

cURL

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) { getTransactions(filter: $filter, paginate: $paginate) { transactions { record_id transaction_type amount description status cashback created_at } totalCount hasNextPage } }",
    "variables": {
      "filter": {
        "status": ["SETTLED"],
        "createdGte": "2025-01-01T00:00:00Z"
      },
      "paginate": {
        "limit": 20,
        "offset": 0
      }
    }
  }'

常見問題

問：一次請求最多可擷取多少筆交易？

答：每次請求最多 20 筆。請使用 hasNextPage 來實作分頁。

問：交易歷史可回溯多久？

答：自帳戶建立以來的所有交易會無限期保留可供查詢。

問：包含處理中的交易嗎？

答：是，預設包含。若要排除，請篩選 status: [SETTLED]。

問：時間戳的時區是什麼？

答：所有時間戳均為 UTC（ISO 8601 格式）。

問：需要哪些 scope？

答：你需要同時擁有 LIST_PAYMENT 與 LIST_PURCHASES 這兩個 scope。

問：可以在我的帳戶內依 user ID 篩選嗎？

答：不行。API 一律回傳你帳戶內的所有交易，沒有使用者層級的篩選。

問：`amount` 與 `finalAmount` 的差異是什麼？

答：

amount 針對基礎交易金額做篩選
finalAmount 針對金額加上手續費（向使用者收取的總額）做篩選

問：如何依日期區間篩選？

答：使用 createdGte 與 createdLte 設定建立時間區間：

filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}

支援

API 狀態: https://status.fluz.app
開發者入口: https://developers.fluz.app
支援信箱: api-support@fluz.app
Slack 社群: https://fluz-dev.slack.com

變更日誌

v1.0.0（分支：13-fluz-15659-add-transactions-query-and-webhook-to-api）

初版釋出 Transactions Query API
支援全面性篩選（15+ 種篩選）
以 TransactionConnection 回應型別進行分頁
交易紀錄包含餘額快照
需要 LIST_PAYMENT 與 LIST_PURCHASES scopes
僅提供帳戶層級的交易存取

需要協助嗎？請聯絡我們的開發者支援團隊：api-support@fluz.app，或造訪我們的開發者入口。

​概觀

​快速開始

​基本查詢

​查詢結構

​參數

​回應結構

​TransactionConnection

​篩選選項

​TransactionFilterInput

​篩選欄位詳細說明

​紀錄與狀態篩選

recordId

status

​金額篩選

amount, amountGte, amountLte

finalAmount, finalAmountGte, finalAmountLte

​現金回饋篩選

cashbackAmount, cashbackAmountGte, cashbackAmountLte

cashbackPercentage, cashbackPercentageGte, cashbackPercentageLte

​手續費篩選

feeAmount, feeAmountGte, feeAmountLte

​日期篩選

createdGte, createdLte

updatedGte, updatedLte

​商家篩選

merchantId

merchant

​交易屬性

transactionType

channel

category

​虛擬卡篩選

virtualCardProgram

virtualCard

​其他篩選

fundingSource

referenceId

liabilityId

​分頁

​OffsetInput

​交易型別

​欄位說明

​核心交易欄位

​金融明細

​餘額快照

​交易明細

​商家資訊

​虛擬卡資訊

​貨幣換算

​中繼資料

​範例

​範例 1：基本交易清單

​範例 2：依日期區間篩選

​範例 3：僅購買且含餘額

​範例 4：高現金回饋交易

​範例 5：金額區間篩選

​範例 6：虛擬卡交易

​範例 7：分頁示例

​錯誤處理

​常見錯誤

​缺少或無效權杖

​權限不足

​無效的篩選參數

​超出速率限制

​最佳實務

​1. 有效運用分頁

​2. 僅請求所需欄位

​3. 查詢歷史資料時使用日期篩選

​4. 快取已結清的交易

​5. 高效組合篩選條件

​速率限制

​程式碼範例

​JavaScript/TypeScript

​Python

​cURL

​常見問題

​問：一次請求最多可擷取多少筆交易？

​問：交易歷史可回溯多久？

​問：包含處理中的交易嗎？

​問：時間戳的時區是什麼？

概觀