Skip to main content
Fluz 帳戶上每一筆資金變動都會產生一筆交易記錄：禮品卡購買、虛擬卡授權、存款、提款、內部轉帳、錢包間轉帳、帳單支付，以及現金回饋。一個資訊流、一種結構、一個查詢。 記錄是帳戶層級的。沒有使用者層級的篩選——一次查詢會回傳你的權杖所限定帳戶上的所有內容。

​
我該使用哪個查詢？

拒絕不是一種交易狀態。 status 只會是 PENDING 或 SETTLED——遭拒絕的授權永遠不會變成已結算的交易，因此它根本不會出現在 getTransactions 中。如果你要排查「扣款沒有成功」的問題，該用的是 getDeclinedTransactions 與拒絕代碼，而不是這個資訊流。
欄位命名並不統一，你必須精確比對。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 的運作方式

​
一筆記錄包含哪些內容

大約五十個欄位，分為六組。只請求你需要的欄位——若請求全部欄位，回應會非常龐大。
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，還是僅在內部流轉。
參見下文——每筆記錄都攜帶每一種餘額的事後狀態。
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——參見加註。
reference_id、transfer_id、liability_id、used_user_cash_balance_id、descriptor_id——用於對帳的欄位。參見對帳。

​
餘額快照

每筆交易都攜帶每一種餘額類型，在該筆交易套用_之後_的餘額。這使得這個資訊流成為一個可重播的分類帳——你不需要另一個餘額歷史 API，就能重建帳戶在其歷史上任一時間點的狀態。
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）會告訴你這筆交易實際影響了哪些餘額——比對快照做差值判斷的成本更低。 → 錢包總覽，了解每種餘額分別是什麼。

​
篩選

getTransactions 接受功能豐富的 TransactionFilterInput。各欄位家族如下： 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 個請求，且回應中不帶任何速率限制標頭。參見速率限制。
在建置同步作業之前，先算一下這筆帳。 每次查詢 20 筆記錄、每秒 20 個請求，上限是每秒 400 筆交易，而一次只發一個請求的實際吞吐量會遠低於這個數字。一個累計有 50 萬筆交易的帳戶，需要 25,000 次請求才能完整遍歷一次。請以增量同步的方式設計：用 createdGte/updatedGte 搭配你上一次成功同步的水位線來限定每個作業的範圍，絕不要重新遍歷你已經擁有的歷史資料。

​
為交易加註

你可以為任何交易附加一段自由文字 memo（最多 255 個字元）、一個 transactionCategory，以及一個檔案——可以在存款、購買與轉帳發生的當下附加，也可以之後透過 updateTransactionMetadata 補上。分類會在首次使用時建立，之後再次使用相同名稱時會被重複使用。
attachmentUrl 是一個會過期的簽署 URL，切勿儲存它。 需要用到檔案時，請重新取得該筆交易。這也會破壞單純的快取方案。已結算的交易看起來是不可變的，但 memo、transactionCategory 與 attachmentUrl 在結算之後仍然是可變的——因此被快取的 SETTLED 記錄會提供過期的註解與失效的附件連結。你可以快取財務欄位，但註解部分需要重新取得。
→ 新增費用明細

​
與你自己的系統對帳

有五個欄位負責關聯： 一種可行的模式：
  1. 在建立訂單當下，將 record_id 與 reference_id 儲存在你自己的訂單記錄上。不要試圖之後再靠金額與時間戳記去比對。
  2. **依 updatedGte 做增量同步，**而不是 createdGte——一筆 PENDING 交易之後結算時會變更 updated_at，依建立日期同步會漏掉這次轉變。
  3. 預期會有結算延遲。 ACH 提款會維持 PENDING 狀態 1 到 3 個工作天；卡片授權則依各自的時間軸結算。expectedClearedDate 會告訴你該在什麼時候再次查看。
  4. **依快照核對餘額，**而不是靠加總金額。*_available_balance 欄位是權威資料，已經把手續費、現金回饋與待處理的預留款都計算在內。
externalReferenceId 不會出現在交易記錄上。如果你需要在一筆資金變動上帶上自己的使用者 ID，請透過帳戶進行關聯，或在交易發生當下把它寫進 memo。→ 管理外部參照 ID

​
權限範圍

getTransactions 同時需要 LIST_PAYMENT 與 LIST_PURCHASES。缺少任一個，都會回傳 FORBIDDEN 錯誤並指出所需的權限範圍。 在你開始建置之前，請先在你應用程式的 Permissions 分頁啟用這兩項權限——已請求但未啟用的權限範圍會被靜默捨棄，而不是被拒絕。→ 設定 OAuth 應用程式

​
後續步驟

取得所有交易

完整的篩選、欄位與分頁參考。

已拒絕交易

從未變成交易的授權。

拒絕代碼

每種拒絕原因分別代表什麼。

虛擬卡交易

限定在一張或多張卡片上。

禮品卡購買

訂單，而非分類帳條目。

新增費用明細

備註、分類與附件。