> ## 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 API 的最新更新、增補與重大變更。

<Note>
  訂閱 [Fluz 狀態頁面](https://you-up.fluz.app/) 以接收事故與主動變更通知。你也可以透過 [RSS](/changelog/rss.xml) 訂閱本更新日誌。
</Note>

<Update label="v0.0.65" tags={["Added"]} description="2026 年 7 月">
  * 新增公開帳戶相關被拒交易的 API 端點。請參閱 [取得被拒交易](/features/get-decline-transactions)。
</Update>

<Update label="v0.0.62" tags={["Added"]} description="2026 年 6 月">
  * 新增 Plaid Link 支援。
  * 使用 `llms.txt` 資訊更新 Overview 頁面。
  * 使用指向 `llms.txt` 的 AI 連結更新頁首。
</Update>

<Update label="v0.0.60" tags={["Added"]} description="2026 年 5 月">
  * 新增 `getCardProvisioningUrl` **query** — 產生一個短效、一次性使用的 URL，於行動裝置開啟時會啟動 Fluz，並將虛擬卡加入 Apple Pay（iOS）或 Google Pay（Android）。可透過 QR code、SMS、電子郵件或應用內按鈕呈現。每個 URL 於建立後約 5 分鐘到期。需要 `CREATE_VIRTUALCARD` 範圍。
  * 新增輸入 `GetCardProvisioningUrlInput { offerId, platform }`。
  * 新增列舉 `ProvisioningPlatform`（`IOS` | `ANDROID` | `OTHER`）— 僅控制桌面／未知裝置的後備流程；iOS 與 Android 的開啟會自動導流。
  * 新增回傳型別 `CardProvisioningUrl { url, expiresAt }`。
</Update>

<Update label="v0.0.59" tags={["Improved"]} description="2026 年 5 月">
  * 於 [產生分享連結](/features/generate-share-links) 新增範例。
</Update>

<Update label="v0.0.58" tags={["Added"]} description="2026 年 5 月">
  * 新增 `addVirtualCardAddress` mutation，用於儲存虛擬卡發卡所需的帳單地址。
  * 更新 `createVirtualCard` mutation 以支援代授權使用者建立卡片。
  * 新增完整流程，使用 `registerUser`、`addAuthorizedUser`、`addVirtualCardAddress` 與 `createVirtualCard`。
  * 對於待處理的發卡方審批，可使用 `VC-0020` 與回傳的 `addressId` 重試。
</Update>

<Update label="v0.0.57" tags={["Added"]} description="2026 年 5 月">
  * `redeemFluzGiftCard` — 使用代碼兌換 Fluz Gift Card。入帳至 `giftCardCashBalance`。需要 `MAKE_DEPOSIT`。請參閱 [兌換 Fluz Gift Card](/features/redeem-fluz-gift-card)。
  * `unlockVirtualCard` — 解除先前已鎖定的虛擬卡以恢復交易功能。需要 `EDIT_VIRTUALCARD`。請參閱 [解除鎖定虛擬卡](/features/unlock-virtual-card)。
</Update>

<Update label="v0.0.55" tags={["Improved"]} description="2026 年 5 月">
  **交易相關 webhook**

  * 新增 `TRANSACTION_CREATE`、`TRANSACTION_UPDATE` 與 `TRANSACTION_DECLINE` webhooks 的說明。
  * 納入 webhook 富化後的新欄位（與 MCC 相關、`virtualCardId` 等）。
</Update>

<Update label="v0.0.54" tags={["Added"]} description="2026 年 5 月">
  * 於 `VirtualCardTransaction` 新增 `mcc`、`merchantCountryCode`、`originalCurrencyCode`、`originalCurrencyAmount` 與 `currencyConversionRate`。現由 `getVirtualCardTransactions` 回傳。
  * 將 `getVirtualCardTransactions` 的 `virtualCardIds` 改為選填 — 省略時可查詢已驗證帳戶下所有卡片的交易。新增 `dateRangeStart` 與 `dateRangeEnd` 篩選器。當省略 `virtualCardIds` 時預設 `limit` 為 100；`limit` 上限為 500。對於無結算金額的紀錄（例如僅 AVS 的拒絕紀錄），`transactionAmount` 現可為 nullable。
  * 於 `CreateVirtualCardInput` 新增 `usePrepaymentBalance` 與 `useRewardsBalance`。`createVirtualCard` 現接受這兩者。兩者預設為 `true`（維持既有行為）。同時將兩者設為 `false` 可限制卡片僅自指定的 `userCashBalanceId` 扣款，不含預付（禮品卡）與獎勵資金。
</Update>

<Update label="v0.0.53" tags={["Added"]} description="2026 年 4 月">
  * 新增 `shortDescription`（Merchant）與 `termsAndConditions`（Offer）。現由 `getMerchants` 與 `getOfferQuote` 回傳。
  * 新增 `deliveryFormat`（GiftCard）。現由 `getGiftCards` 回傳 — 對已購買的卡片使用 `deliveryFormat`。
</Update>

<Update label="v0.0.52" tags={["Added"]} description="2026 年 4 月">
  * 新增 `setVirtualCardPIN` mutation，允許使用者為符合資格的虛擬卡設定 PIN。請參閱 [設定虛擬卡 PIN](/recipes/set-virtual-card-pin)。
</Update>

<Update label="v0.0.51" tags={["Added"]} description="2026 年 4 月">
  * 新增 `getUserCashBalances` 與 `getUserCashBalanceById` queries。這些查詢允許使用者擷取其消費帳戶清單以及在其帳戶上建立的特定消費帳戶。
</Update>

<Update label="v0.0.49" tags={["Added"]} description="2026 年 4 月">
  **分享虛擬卡 API**

  * 在管理虛擬卡下新增「分享虛擬卡」功能。請聯絡銷售以取得存取權。
  * 於 [應用程式範圍](/fluz-dashboard/application-scopes) 頁面新增 `CREATE_SHARE_LINK` 範圍。
</Update>

<Update label="v0.0.45" tags={["Added"]} description="2026 年 2 月">
  **企業註冊 API**

  * 新增查詢 `getBusinessCategories: [BusinessCategory]` 以擷取企業類別，並提供回應型別 `BusinessCategory` 與 `BusinessSubCategory`。
  * 新增 mutation `registerBusiness(input: RegisterBusinessInput!): RegisterBusinessResult` 以程式化完成企業註冊。
  * 新增輸入型別：`RegisterBusinessInput`、`BusinessLegalAddressInput`、`BusinessOwnerInput`、`OwnerAddressInput`。
  * 新增列舉：`BusinessStructure`（`LLC`、`CORPORATION`、`PARTNERSHIP`、`SOLE_PROPRIETORSHIP`、`COOP`）與 `BusinessAccountUsage`。
  * 新增回應型別：`RegisterBusinessResult { accountId, kybStatus, success, error }` 與 `RegisterBusinessError { message, code }`。
  * 兩項作業皆需以 `REGISTER_BUSINESS` OAuth 範圍進行驗證。
</Update>

<Update label="v0.0.44" tags={["Improved"]} description="2026 年 1 月">
  **`getMerchants` 查詢更新**

  * `getMerchants` 查詢現在能正確回傳所有可用的 offers。
  * `getMerchants` 查詢現在可回傳 `exclusiveRateId` 欄位（位於 `offers` 物件內）。此值可於 `purchaseGiftCard` 中指定你要以專屬費率購買的 offer。
</Update>

<Update label="v0.0.43" tags={["Added"]} description="2025 年 12 月">
  **提領與消費帳戶 API**

  * 新增 `withdrawCashBalance` mutation，需具備 `MAKE_WITHDRAWAL` 範圍。
  * 新增 `WithdrawMethods` 列舉，支援 `PAYPAL`、`BANK_ACH`、`BANK_CARD` 與 `VENMO` 方法。
  * 新增 `WithdrawSource` 列舉，支援 `CASH_BALANCE` 與 `REWARDS_BALANCE` 來源。
  * 新增具冪等性支援的 `WithdrawCashBalanceInput`，以及完整提領紀錄細節（含費用、狀態與時間戳）的 `Withdraw` 與 `WithdrawCashBalanceResponse` 型別。
  * 新增 `transferUserCashBalance` mutation，需具備 `MAKE_INTERNAL_TRANSFER` 範圍，並包含 `TransferInternalBalanceInput` 與 `TransferInternalBalanceResponse` 型別。
  * 於 `EditVirtualCardInput` 新增 `userCashBalanceId`，可透過 `editVirtualCard` 將資金來源變更為指定的消費帳戶。
  * 於 `TransactionFilterInput` 新增 `userCashBalanceIds` 以透過 `getTransactions` 依消費帳戶篩選交易，並於 `getGiftCards` 新增 `userCashBalanceId` 以依消費帳戶篩選禮品卡。
  * 新增 `updateUserCashBalance` 與 `closeUserCashBalance` mutations，需具備 `MANAGE_PAYMENT` 範圍，並包含支援的輸入與回應型別（`UpdateUserCashBalanceInput`、`CloseUserCashBalanceInput`、`CloseUserCashBalanceResponse`、`ClosedUserCashBalance`、`CloseUserCashBalanceResponseVirtualCard`）。
  * 新增應用程式動作記錄以供稽核追蹤。
</Update>

<Update label="v0.0.42" tags={["Added"]} description="2025 年 11 月">
  * 在 `getWallet` 查詢的 `UserBalances` 型別中新增 `userCashBalances` 欄位。透過 `paginate`（limit/offset）提供分頁，並依建立日期排序（最新優先），回傳個別使用者現金餘額帳戶的詳細資訊。包含 `userCashBalanceId`、`totalCashBalance`、`availableCashBalance`、`lifetimeCashBalance`、`nickname`、`status` 與 `createdAt` — 可用於追蹤每位使用者的多個現金餘額帳戶、客製暱稱與狀態監控。
</Update>

<Update label="v0.0.40" tags={["Added"]} description="2025 年 11 月">
  * 在 `DepositCashBalanceInput` 新增 `userCashBalanceId` 欄位，以指定要存入資金的現金餘額（消費帳戶）。
</Update>

<Update label="v0.0.39" tags={["Added"]} description="2025 年 11 月">
  * 新增管理已儲存銀行卡的 mutations：`updateBankCardNickname`、`updateBankCardPreferredMerchantCategoryCode` 與 `deleteBankCard`，以及相應的輸入型別。
  * 在 `BankCard` 型別新增 `nickname` 欄位。
  * 在 `AddBankCardInput` 新增選填欄位：`nickname` 與 `preferredMerchantCategoryCode`（MCC，正規化為 4 位數）。
</Update>

<Update label="v0.0.37" tags={["Added"]} description="2025 年 9 月">
  * `getVirtualCardBalance`：新的查詢，可擷取一組虛擬卡的餘額資訊，包括 `spentAmount`、`remainingBalance`、`spendLimit` 與 `spendLimitDuration`。
  * `getVirtualCardTransactions`：新的查詢，可擷取一組虛擬卡的交易，並提供如 `transactionTypes` 等篩選條件。
</Update>

<Update label="v0.0.36" tags={["Improved"]} description="2025 年 9 月">
  * `getUserPurchases` 查詢現在可透過新的選填變數 `UserPurchaseFilterInput` 來篩選回應中的購買紀錄。可篩選由使用者、帳戶或兩者所發起的購買。
</Update>

<Update label="v0.0.35" tags={["Added"]} description="2025 年 9 月">
  * `revealVirtualCardByVirtualCardId` mutation 的回應現在包含新增的 `authorizationSetting` 欄位。
  * **大量虛擬卡 API**：新的 API，可非同步建立與管理大量虛擬卡。
  * `createVirtualCardBulkOrder` **mutation**：提交大量訂單並取得唯一的 `orderId`。
  * `getVirtualCardBulkOrderStatus` **query**：透過輪詢追蹤訂單狀態，並於完成後擷取卡片詳細資料。
  * 大量卡片建立流程為非同步 — 請檢查訂單狀態以擷取卡片詳細資料。
</Update>

<Update label="v0.0.32" tags={["Added"]} description="2025 年 7 月">
  * **新查詢 `getVirtualCardOffers`**：完整列出可供建立的所有有效虛擬卡 offer，包括 `offerId`（建立卡片所必需）、`programName`、`bankName`、`rewardValue`，以及詳細的方案限制（每日、每週、每月消費上限）。
  * **更新 mutation `createVirtualCard`**：透過提供 `offerId`（來自 `getVirtualCardOffers`）、`spendLimit`，以及可自訂的屬性如 `cardNickname` 與 `spendLimitDuration`，以程式化方式發行虛擬卡。
  * **新 mutation `editVirtualCard`**：更新現有虛擬卡的關鍵參數 — `spendLimit`、`spendLimitDuration`、`lockDate`、`lockCardNextUse` 與 `cardNickname`。
  * **新 mutation `lockVirtualCard`**：立即鎖定虛擬卡，阻止任何後續交易。
</Update>

<Update label="v0.0.31" tags={["Added"]} description="2025 年 7 月">
  * `getMerchants` 回應中的 `Offer` 型別現在包含 `deliveryFormat` 欄位，用以指定 offer 的履行方式：`URL`、`CODES`、`PIN_AS_CODE` 或 `PIN_WITH_URL`。
  * `getMerchants` 查詢已強化，新增 `filterBy` 參數，允許你僅篩選出其 offers 符合特定 `deliveryFormat` 的商家。
</Update>

<Update label="v0.0.30" tags={["Added"]} description="2025 年">
  * 強化 `getMerchants` 查詢，新增 `offerTypes` 輸入參數，允許依 `giftCardOffer`s、`cardLinkedOffer`s 或兩者皆有來篩選。預設情況下，若未提供 `offerTypes`，查詢僅回傳禮品卡 offers。
</Update>

<Update label="v0.0.29" tags={["Added","Improved"]} description="2025 年">
  * 新增查詢 `getReferralUrl`，根據商家輸入回傳推薦字串，並新增 `MerchantInput` 型別。
  * 於 `purchaseGiftCard` mutation 新增自動重購嘗試。若使用銀行卡、銀行帳戶或 PayPal 購買禮品卡失敗，系統會自動嘗試改用 Fluz 餘額重購。
  * 於 `PurchaseGiftCardInput` 新增 `defaultToBalance` 欄位，以在主要付款方式失敗時將 Fluz 餘額設為後備付款方式。預設為 `true`。
</Update>

<Update label="v0.0.27" tags={["Added","Improved"]} description="2025 年">
  * 新增存取範圍 `CREATE_VIRTUALCARD`，用於建立虛擬卡。
  * 新增函式 `createVirtualCard`，可用特定參數建立虛擬卡。
  * 新增查詢 `getBINs`，以擷取與虛擬卡相關的 BIN。
  * 在現金餘額存款中新增 `merchantCategoryCode` 輸入，以強化交易分類。
  * 新增查詢 `getMccList`，以擷取商家類別代碼清單。
  * 強化 `getApplicationScopes` 查詢的範圍驗證，並改進 GraphQL 型別定義管理。
</Update>

<Update label="v0.0.26" tags={["Improved"]} description="2025 年">
  * 強化商家 offer 的庫存資訊處理：`Offer` 物件的 `stockInfo` 欄位現在會視 offer 為固定或可變而回傳 `StockInfoFixedType` 或 `StockInfoVariableType`。
  * 強化錯誤處理，提供更直覺的錯誤訊息回應 — 改進 `purchaseGiftCard` 無 offer 錯誤與帳戶與付款方式不相符的回應。
</Update>

<Update label="v0.0.17 – v0.0.21" tags={["Added","Fixed"]} description="2025 年">
  **v0.0.21**

  * 為 `depositCashBalance` 與 `purchaseGiftCards` 新增 `idempotencyKey` 參數，以防止重複請求。
  * 新增 `purchaseGiftCardInput` 型別，以簡化交易的參數處理。
  * 在 `UserPurchase` 型別新增 `purchaseDisplayId` 欄位，提供購買紀錄的顯示 ID。
  * 修正 `Offer` 物件的 `offeringMerchantId` 欄位，改為回傳 `offering_merchant_id` 而非 `offer_id`。

  **v0.0.20**

  * 對 `generateUserAccessToken` 新增 `accountId` 要求。
  * 實作新查詢 `getAccountsByUserId`，可依 `userId` 擷取帳戶。
  * 新增 `AccountType` 列舉以將帳戶分類為 `CONSUMER` 或 `BUSINESS`，並新增 `Account`、`Business` 與 `Seat` 物件。

  **v0.0.17**

  * 修正 `depositCashBalance` 的平台通道輸入，使存款交易記錄的來源被記錄為 `API`。
</Update>

## 變更管理

當變更為可加成型（新增欄位、新列舉值、新作業）且需要整合方採取動作時，會至少於發布前 **7 天** 公告。重大變更則會至少提前 **14 天** 公告，且通常會彙整於主要發布時段。

如需 API 作業的完整清單，請參閱 [API 參考](https://storage.googleapis.com/fluz-public-docs/api-reference.html)。