> ## 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.
# 交易總覽
> 帳戶上每一筆資金變動的統一分類帳——該使用哪個查詢、交易記錄包含哪些內容，以及如何與你自己的系統對帳。
Fluz 帳戶上每一筆資金變動都會產生一筆交易記錄：禮品卡購買、虛擬卡授權、存款、提款、內部轉帳、錢包間轉帳、帳單支付，以及現金回饋。一個資訊流、一種結構、一個查詢。
記錄是**帳戶層級**的。沒有使用者層級的篩選——一次查詢會回傳你的權杖所限定帳戶上的所有內容。
***
## 我該使用哪個查詢？
| 你想要 | 使用 | 頁面 |
| :- | :- | :- |
| 所有資料，可任意方式篩選 | `getTransactions` | [取得所有交易](/features/get-all-transactions) |
| 僅遭拒絕的授權 | `getDeclinedTransactions` | [取得已拒絕交易](/features/get-decline-transactions) |
| 特定虛擬卡上的活動 | `getVirtualCardTransactions` | [取得虛擬卡交易](/features/get-virtual-card-transactions) |
| 以購買形式呈現的禮品卡訂單 | `getUserPurchases` | [取得禮品卡購買記錄](/features/get-gift-card-purchases) |
| 以資產形式呈現的禮品卡及其剩餘價值 | `getGiftCards` | [檢視禮品卡](/view-gift-card) |
**拒絕不是一種交易狀態。** `status` 只會是 `PENDING` 或 `SETTLED`——遭拒絕的授權永遠不會變成已結算的交易，因此它根本不會出現在 `getTransactions` 中。如果你要排查「扣款沒有成功」的問題，該用的是 `getDeclinedTransactions` 與[拒絕代碼](/features/decline-codes)，而不是這個資訊流。
***
**欄位命名並不統一，你必須精確比對。**
`Transaction` 型別上多數欄位使用 snake\_case——`record_id`、`transaction_type`、`created_at`、`cash_balance_available_balance`。但較新加入的欄位使用 camelCase——`memo`、`transactionCategory`、`attachmentUrl`、`connectedAppId`、`connectedAppName`、`expectedClearedDate`。
記錄\_周邊\_的一切都是 camelCase：篩選輸入（`createdGte`、`amountGte`、`virtualCardProgram`）以及連線欄位（`totalCount`、`hasNextPage`）。
在撰寫查詢之前先檢視 schema，而不要假設某種慣例。→ [GraphQL API 的運作方式](/concepts/graphql)
***
## 一筆記錄包含哪些內容
大約五十個欄位，分為六組。只請求你需要的欄位——若請求全部欄位，回應會非常龐大。
`record_id`、`account_id`、`user_id`、`user`、`transaction_type`、`channel`（`WEB`、`MOBILE`、`API`）、`connectedAppId` 與 `connectedAppName`——由你的哪個應用程式發起。
`amount`、`fee`、`cashback`、`cashback_rate`、`bonus_cashback_rate`，再加上兩個值得了解的方向性欄位：
* `external_funding_source_activity`——外部資金來源（銀行卡與帳戶）的變動
* `fluz_balance_activity`——Fluz 內部餘額的變動
兩者合在一起，能告訴你資金是流入了 Fluz、流出了 Fluz，還是僅在內部流轉。
參見[下文](#balance-snapshots)——每筆記錄都攜帶每一種餘額的事後狀態。
`source` 與 `destination` 為顯示字串（如「Visa \*\*\*\*1234」、「Amazon」）、`description`、`merchant_id`、`logo_url`、`card_last_four`、`card_display_name`、`virtual_card_program`、`source_type`。
外幣交易還會附加 `original_currency_amount`、`original_currency_code` 與 `conversion_rate`。
`memo`、`transactionCategory`、`attachmentUrl`——參見[加註](#annotating-transactions)。
`reference_id`、`transfer_id`、`liability_id`、`used_user_cash_balance_id`、`descriptor_id`——用於對帳的欄位。參見[對帳](#reconciling-against-your-own-system)。
### 餘額快照
每筆交易都攜帶**每一種**餘額類型，在該筆交易套用\_之後\_的餘額。這使得這個資訊流成為一個可重播的分類帳——你不需要另一個餘額歷史 API，就能重建帳戶在其歷史上任一時間點的狀態。
| 欄位前綴 | 餘額 | 產品名稱 |
| :- | :- | :- |
| `cash_balance_*` | 現金 | 現金餘額 |
| `seat_balance_*` | 獎勵 | 獎勵餘額 |
| `gift_card_prepayment_balance_*` | 預付款 | 預付款餘額 |
| `reserve_balance_*` | 準備金 | 準備金餘額 |
| `other_cash_balance_*` | 其他現金 | — |
`seat_balance_*` 是**獎勵**餘額。這個命名是歷史遺留的——不必去尋找一個獨立的 seat 概念。
每一種都有 `_available_balance` 與 `_total_balance` 兩個版本。成對出現的 `is_*_affected` 布林欄位（`is_cash_balance_affected`、`is_seat_balance_affected`、`is_gift_card_balance_affected`、`is_reserve_balance_affected`）會告訴你這筆交易實際影響了哪些餘額——比對快照做差值判斷的成本更低。
→ [錢包總覽](/features/move-funds-with-external-accounts)，了解每種餘額分別是什麼。
***
## 篩選
`getTransactions` 接受功能豐富的 `TransactionFilterInput`。各欄位家族如下：
| 家族 | 欄位 |
| :- | :- |
| **記錄與狀態** | `recordId`、`status` |
| **金額** | `amount`、`amountGte`、`amountLte`，以及 `finalAmount` 對應的同樣三個欄位 |
| **現金回饋** | `cashbackAmount`、`cashbackPercentage`，各自搭配 `Gte`/`Lte` |
| **手續費** | `feeAmount`、`feeAmountGte`、`feeAmountLte` |
| **日期** | `createdGte`、`createdLte`、`updatedGte`、`updatedLte`——ISO 8601，UTC |
| **商家** | `merchantId`、`merchant` |
| **屬性** | `transactionType`、`channel`、`category` |
| **虛擬卡** | `virtualCard`、`virtualCardProgram` |
| **其他** | `fundingSource`、`userCashBalanceId`、`referenceId`、`liabilityId` |
`amount` 是基礎金額；`finalAmount` 是金額加上手續費，即實際扣款總額。核對資金來源實際被扣了多少款項時，請以 `finalAmount` 篩選。
**在依賴 `transactionType` 之前，請先確認其可接受的值。** 參考頁面在一處列出人類可讀的字串（`Add Money`、`Gift Card Purchase`、`Transfer - Out`），又在範例與範例回應中使用列舉風格的常數（`GIFT_CARD_PURCHASE`、`DEPOSIT`）。兩者不可互換。請先查詢一小頁未篩選的資料，看看你的帳戶實際回傳的 `transaction_type` 值。
### 分頁與吞吐量
`limit` **上限為 20**，`offset` 用來向前翻頁。請檢查 `hasNextPage`，而不要從短頁面去推斷；`totalCount` 會給出篩選後結果集的完整大小。
GraphQL API 對每個 IP 與每個存取權杖都限制為每秒 20 個請求，且回應中不帶任何速率限制標頭。參見[速率限制](/concepts/rate-limits)。
**在建置同步作業之前，先算一下這筆帳。** 每次查詢 20 筆記錄、每秒 20 個請求，上限是**每秒 400 筆交易**，而一次只發一個請求的實際吞吐量會遠低於這個數字。一個累計有 50 萬筆交易的帳戶，需要 25,000 次請求才能完整遍歷一次。
請以增量同步的方式設計：用 `createdGte`/`updatedGte` 搭配你上一次成功同步的水位線來限定每個作業的範圍，絕不要重新遍歷你已經擁有的歷史資料。
***
## 為交易加註
你可以為任何交易附加一段自由文字 `memo`（最多 255 個字元）、一個 `transactionCategory`，以及一個檔案——可以在存款、購買與轉帳發生的當下附加，也可以之後透過 `updateTransactionMetadata` 補上。分類會在首次使用時建立，之後再次使用相同名稱時會被重複使用。
**`attachmentUrl` 是一個會過期的簽署 URL，切勿儲存它。** 需要用到檔案時，請重新取得該筆交易。
這也會破壞單純的快取方案。已結算的交易看起來是不可變的，但 `memo`、`transactionCategory` 與 `attachmentUrl` 在結算之後仍然是可變的——因此被快取的 `SETTLED` 記錄會提供過期的註解與失效的附件連結。你可以快取財務欄位，但註解部分需要重新取得。
→ [新增費用明細](/features/add-expense-details)
***
## 與你自己的系統對帳
有五個欄位負責關聯：
| 欄位 | 關聯至 |
| :- | :- |
| `reference_id` | 購買顯示 ID——一個簡短、人類可讀的 Fluz 交易 ID（例如 `1047283`），也會出現在禮品卡記錄與匯出檔案中，也是 Fluz 支援團隊引用的編號 |
| `transfer_id` | 產生此記錄的轉帳，用於錢包間資金移動 |
| `used_user_cash_balance_id` | 資金來自哪個消費帳戶——對於按預算產生報表至關重要 |
| `liability_id` | 此記錄所結算的帳單支付 |
| `connectedAppId` | 當多個應用程式共用同一帳戶時，由哪個應用程式發起 |
一種可行的模式：
1. **在建立訂單當下，將 `record_id` 與 `reference_id` 儲存**在你自己的訂單記錄上。不要試圖之後再靠金額與時間戳記去比對。
2. \*\*依 `updatedGte` 做增量同步，\*\*而不是 `createdGte`——一筆 `PENDING` 交易之後結算時會變更 `updated_at`，依建立日期同步會漏掉這次轉變。
3. **預期會有結算延遲。** ACH 提款會維持 `PENDING` 狀態 1 到 3 個工作天；卡片授權則依各自的時間軸結算。`expectedClearedDate` 會告訴你該在什麼時候再次查看。
4. \*\*依快照核對餘額，\*\*而不是靠加總金額。`*_available_balance` 欄位是權威資料，已經把手續費、現金回饋與待處理的預留款都計算在內。
`externalReferenceId` **不會**出現在交易記錄上。如果你需要在一筆資金變動上帶上自己的使用者 ID，請透過帳戶進行關聯，或在交易發生當下把它寫進 `memo`。→ [管理外部參照 ID](/managing-external-reference-ids)
***
## 權限範圍
`getTransactions` **同時**需要 `LIST_PAYMENT` **與** `LIST_PURCHASES`。缺少任一個，都會回傳 `FORBIDDEN` 錯誤並指出所需的權限範圍。
在你開始建置之前，請先在你應用程式的 Permissions 分頁啟用這兩項權限——已請求但未啟用的權限範圍會被靜默捨棄，而不是被拒絕。→ [設定 OAuth 應用程式](/configure-o-auth-app)
***
## 後續步驟
完整的篩選、欄位與分頁參考。
從未變成交易的授權。
每種拒絕原因分別代表什麼。
限定在一張或多張卡片上。
訂單，而非分類帳條目。
備註、分類與附件。