取得所有交易

總覽

交易 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
說明：依確切金額或美元金額範圍篩選。

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 { recordId }
    hasNextPage  # Use this to determine if there are more results
    totalCount   # Total matching records
  }
}

Transaction 型別

type Transaction {
  recordId: UUID
  user: String!
  accountId: UUID!
  userId: UUID
  transactionType: String
  amount: Float!
  destination: String
  source: String
  externalFundingSourceActivity: Float
  fluzBalanceActivity: Float
  fee: Float
  cashback: Float
  
  # Ending balances after transaction
  giftCardPrepaymentBalanceAvailableBalance: Float
  giftCardPrepaymentBalanceTotalBalance: Float
  cashBalanceAvailableBalance: Float
  cashBalanceTotalBalance: Float
  seatBalanceAvailableBalance: Float
  seatBalanceTotalBalance: Float
  reserveBalanceAvailableBalance: Float
  reserveBalanceTotalBalance: Float
  otherCashBalanceAvailableBalance: Float
  otherCashBalanceTotalBalance: Float
  
  status: TransactionStatus
  referenceId: String
  description: String
  note: String
  category: String
  cardLastFour: String
  cardDisplayName: String
  originalCurrencyAmount: Float
  originalCurrencyCode: String
  conversionRate: Float
  merchantId: UUID
  descriptorId: UUID
  virtualCardProgram: String
  cashbackRate: Float
  bonusCashbackRate: Float
  channel: String
  sourceType: String
  logoUrl: String
  platformInstitutionLogo: String
  challengeLogoUrl: String
  invitedAccountId: UUID
  expectedClearedDate: DateTime
  liabilityId: UUID
  isGiftCardBalanceAffected: Boolean
  isCashBalanceAffected: Boolean
  isSeatBalanceAffected: Boolean
  isReserveBalanceAffected: Boolean
  transferId: UUID
  usedUserCashBalanceId: UUID
  connectedAppId: UUID
  connectedAppName: String
  
  memo: String
  transactionCategory: String
  attachmentUrl: String

  createdAt: DateTime
  updatedAt: DateTime
}

欄位說明

核心交易欄位

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

財務詳情

欄位	類型	說明
`externalFundingSourceActivity`	Float	外部資金來源（銀行卡／帳戶）的變動
`fluzBalanceActivity`	Float	Fluz 內部餘額的變動
`fee`	Float	此交易收取的手續費
`cashback`	Float	此交易獲得的現金回饋
`cashbackRate`	Float	現金回饋比例
`bonusCashbackRate`	Float	額外的獎勵現金回饋比例

餘額快照

重要：所有餘額欄位顯示的皆為此交易套用之後的餘額。

欄位	說明
`cashBalanceAvailableBalance`	交易後的可用現金餘額
`cashBalanceTotalBalance`	交易後的現金總餘額
`seatBalanceAvailableBalance`	交易後的可用獎勵餘額
`seatBalanceTotalBalance`	交易後的獎勵總餘額
`giftCardPrepaymentBalanceAvailableBalance`	交易後的可用預付款餘額
`giftCardPrepaymentBalanceTotalBalance`	交易後的預付款總餘額
`reserveBalanceAvailableBalance`	交易後的可用準備金餘額
`reserveBalanceTotalBalance`	交易後的準備金總餘額
`otherCashBalanceAvailableBalance`	交易後的其他現金可用餘額
`otherCashBalanceTotalBalance`	交易後的其他現金總餘額

交易詳情

欄位	類型	說明
`referenceId`	String	外部參照（例如：購買顯示 ID）
`description`	String	人類可讀的說明
`note`	String	額外備註
`category`	String	交易類別
`cardLastFour`	String	使用卡片的末四碼（如適用）
`cardDisplayName`	String	付款方式的顯示名稱
`memo`	String	附加於此交易的自由文字備註。可透過 `updateTransactionMetadata` 設定，或在存款、購買及轉帳時於交易當下設定。
`transactionCategory`	String	附加於此交易的類別標籤。可透過 `updateTransactionMetadata` 設定，或在存款、購買及轉帳時於交易當下設定。
`attachmentUrl`	String	此交易附加檔案的簽署網址。可透過 `updateTransactionMetadata` 設定，或於交易當下設定。此網址會過期，請勿儲存。需要存取檔案時請重新取得該筆交易。

商家資訊

欄位	類型	說明
`merchantId`	UUID	商家識別碼
`descriptorId`	UUID	交易敘述 ID
`logoUrl`	String	商家／來源標誌的網址

虛擬卡資訊

欄位	類型	說明
`virtualCardProgram`	String	虛擬卡方案（LITHIC、MARQETA 等）

貨幣換算

欄位	類型	說明
`originalCurrencyAmount`	Float	發卡機構回報為請求金額的數值，以商家貨幣的最小單位表示（`6300` HKD 即為 63.00 HKD）。若為退款，此欄位為該筆退款前仍在保留中的金額，因此請以 `amount` 為準進行核對
`originalCurrencyCode`	String	原始貨幣代碼（例如：“EUR”）
`conversionRate`	Float	套用的匯率

中繼資料

欄位	類型	說明
`channel`	String	平台管道（WEB、MOBILE、API）
`sourceType`	String	資金來源類型
`liabilityId`	UUID	關聯的負債（用於帳單繳費）
`transferId`	UUID	關聯的轉帳（用於 P2P）
`usedUserCashBalanceId`	UUID	使用的特定現金餘額
`isGiftCardBalanceAffected`	Boolean	是否影響禮品卡餘額
`isCashBalanceAffected`	Boolean	是否影響現金餘額
`isSeatBalanceAffected`	Boolean	是否影響獎勵餘額
`isReserveBalanceAffected`	Boolean	是否影響準備金餘額
`connectedAppId`	UUID	關聯的應用程式 ID
`connectedAppName`	String	關聯的應用程式名稱
`createdAt`	DateTime	交易建立時間
`updatedAt`	DateTime	交易最後更新時間

範例

範例 1：基本交易清單

查詢：

query GetRecentTransactions {
  getTransactions(
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      recordId
      transactionType
      amount
      description
      status
      cashback
      createdAt
    }
    totalCount
    hasNextPage
  }
}

回應：

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "recordId": "550e8400-e29b-41d4-a716-446655440000",
          "transactionType": "GIFT_CARD_PURCHASE",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "status": "SETTLED",
          "cashback": 2.50,
          "createdAt": "2025-01-15T14:30:00Z"
        },
        {
          "recordId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "transactionType": "DEPOSIT",
          "amount": 100.00,
          "description": "Cash Balance Deposit",
          "status": "SETTLED",
          "cashback": 0.00,
          "createdAt": "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 {
      recordId
      transactionType
      amount
      description
      status
      createdAt
    }
    totalCount
    hasNextPage
  }
}

範例 3：僅購買項目（含餘額）

查詢：

query GetPurchaseHistory {
  getTransactions(
    filter: {
      transactionType: ["GIFT_CARD_PURCHASE"]
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      recordId
      referenceId
      amount
      description
      source
      destination
      cashback
      cashbackRate
      cashBalanceAvailableBalance
      seatBalanceAvailableBalance
      createdAt
    }
    totalCount
    hasNextPage
  }
}

回應：

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "recordId": "550e8400-e29b-41d4-a716-446655440000",
          "referenceId": "1000123",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "source": "Visa ****1234",
          "destination": "Amazon",
          "cashback": 2.50,
          "cashbackRate": 5.0,
          "cashBalanceAvailableBalance": 102.50,
          "seatBalanceAvailableBalance": 25.00,
          "createdAt": "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 {
      recordId
      transactionType
      amount
      description
      cashback
      cashbackRate
      status
      createdAt
    }
    totalCount
  }
}

範例 5：金額範圍篩選

查詢：

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

範例 6：虛擬卡交易

查詢：

query GetVirtualCardTransactions {
  getTransactions(
    filter: {
      virtualCardProgram: ["LITHIC", "MARQETA"]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      recordId
      amount
      description
      virtualCardProgram
      merchantId
      status
      createdAt
    }
    totalCount
  }
}

範例 7：分頁範例

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

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

回應顯示 hasNextPage=true：

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

查詢 - 取得第二頁：

query GetSecondPage {
  getTransactions(paginate: { limit: 20, offset: 20 }) {
    transactions {
      recordId
      amount
      transactionType
    }
    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

超出速率限制

{
  "message": "Rate limit exceeded"
}

HTTP 狀態：429 Too Many Requests 這是純 JSON 內容，而非 GraphQL 的 errors 陣列。請參閱速率限制以了解封鎖時間。

最佳實務

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 {
    recordId
    amount
    transactionType
    createdAt
  }
  totalCount
  hasNextPage
}

# Less efficient - requesting all 40+ fields
getTransactions {
  transactions {
    recordId
    transactionType
    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
}

速率限制

此查詢與 GraphQL API 共用相同的限制。詳細數字及請求遭拒時的回應內容請參閱速率限制。

程式碼範例

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 {
        recordId
        transactionType
        amount
        description
        status
        cashback
        createdAt
      }
      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 {
                    recordId
                    transactionType
                    amount
                    description
                    status
                    cashback
                    createdAt
                }
                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 { recordId transactionType amount description status cashback createdAt } totalCount hasNextPage } }",
    "variables": {
      "filter": {
        "status": ["SETTLED"],
        "createdGte": "2025-01-01T00:00:00Z"
      },
      "paginate": {
        "limit": 20,
        "offset": 0
      }
    }
  }'

常見問題

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

答：每次請求最多可取得 20 筆交易。請使用 hasNextPage 欄位來實作分頁。

問：交易紀錄可以回溯多久？

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

問：是否包含處理中的交易？

答：是，處理中的交易預設會包含在內。若要排除，請使用 status: [SETTLED] 篩選。

問：時間戳記使用什麼時區？

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

問：我需要哪些權限範圍？

答：您需要同時具備 LIST_PAYMENT 與 LIST_PURCHASES 這兩個權限範圍。

問：我可以在帳戶內依使用者 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）

初次發布交易查詢 API
支援完整的篩選功能（15+ 種篩選類型）
使用 TransactionConnection 回應型別進行分頁
交易紀錄包含餘額快照
需要 LIST_PAYMENT 與 LIST_PURCHASES 權限範圍
僅提供帳戶層級的交易存取權限

**需要協助？**請透過 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

​Transaction 型別

​欄位說明

​核心交易欄位

​財務詳情

​餘額快照

​交易詳情

​商家資訊

​虛擬卡資訊

​貨幣換算

​中繼資料

​範例

​範例 1：基本交易清單

​範例 2：依日期範圍篩選

​範例 3：僅購買項目（含餘額）

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

​範例 5：金額範圍篩選

​範例 6：虛擬卡交易

​範例 7：分頁範例

​錯誤處理

​常見錯誤

​缺少或無效的權杖

​權限不足

​無效的篩選參數

​超出速率限制

​最佳實務

​1. 有效使用分頁

​2. 僅請求所需欄位

​3. 針對歷史查詢使用日期篩選

​4. 快取已結清的交易

​5. 有效組合篩選條件

​速率限制

​程式碼範例

​JavaScript/TypeScript

​Python

​cURL

​常見問題

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

​問：交易紀錄可以回溯多久？

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

​問：時間戳記使用什麼時區？

總覽