> ## 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` 信息。
  * 更新页眉，加入指向 `llms.txt` 的 AI 链接。
</Update>

<Update label="v0.0.60" tags={["Added"]} description="2026年5月">
  * 新增 `getCardProvisioningUrl` **查询** —— 生成一个短期的一次性 URL，在移动设备上打开时会启动 Fluz 并将虚拟卡添加到 Apple Pay（iOS）或 Google Pay（Android）。可通过二维码、短信、电子邮件或应用内按钮呈现。每个 URL 在创建约 5 分钟后过期。需要 `CREATE_VIRTUALCARD` scope。
  * 新增输入 `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` 变更，用于保存开卡所需的账单地址。
  * 更新 `createVirtualCard` 变更，支持代表授权用户创建卡。
  * 新增完整流程：使用 `registerUser`、`addAuthorizedUser`、`addVirtualCardAddress` 和 `createVirtualCard`。
  * 对带有 `VC-0020` 且返回了 `addressId` 的发行方待审批进行重试。
</Update>

<Update label="v0.0.57" tags={["Added"]} description="2026年5月">
  * `redeemFluzGiftCard` —— 使用代码兑换 Fluz 礼品卡。入账至 `giftCardCashBalance`。需要 `MAKE_DEPOSIT`。参见 [兑换 Fluz 礼品卡](/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` 现在可为空。
  * 在 `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` 变更，允许用户为符合条件的虚拟卡设置 PIN。参见 [设置虚拟卡 PIN](/recipes/set-virtual-card-pin)。
</Update>

<Update label="v0.0.51" tags={["Added"]} description="2026年4月">
  * 新增 `getUserCashBalances` 和 `getUserCashBalanceById` 查询。这些查询允许用户检索其消费账户列表以及其账户上创建的特定消费账户。
</Update>

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

  * 在“管理虚拟卡”下新增“分享虚拟卡”功能。请联系销售获取访问权限。
  * 在[应用程序 scope](/fluz-dashboard/application-scopes) 页面新增 `CREATE_SHARE_LINK` scope。
</Update>

<Update label="v0.0.45" tags={["Added"]} description="2026年2月">
  **企业注册 API**

  * 新增查询 `getBusinessCategories: [BusinessCategory]` 以获取业务类别，响应类型为 `BusinessCategory` 和 `BusinessSubCategory`。
  * 新增变更 `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 scope 的认证。
</Update>

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

  * `getMerchants` 查询现在能正确返回所有可用的优惠。
  * `getMerchants` 查询现在可在 `offers` 对象中返回 `exclusiveRateId` 字段。该值可用于 `purchaseGiftCard` 以指定要购买的专属费率优惠。
</Update>

<Update label="v0.0.43" tags={["Added"]} description="2025年12月">
  **提现与消费账户 APIs**

  * 新增 `withdrawCashBalance` 变更，需具备 `MAKE_WITHDRAWAL` scope。
  * 新增 `WithdrawMethods` 枚举，支持 `PAYPAL`、`BANK_ACH`、`BANK_CARD` 和 `VENMO` 方法。
  * 新增 `WithdrawSource` 枚举，支持 `CASH_BALANCE` 和 `REWARDS_BALANCE` 来源。
  * 新增带幂等支持的 `WithdrawCashBalanceInput`，以及包含完整提现记录详情（费用、状态与时间戳）的 `Withdraw` 与 `WithdrawCashBalanceResponse` 类型。
  * 新增 `transferUserCashBalance` 变更，需具备 `MAKE_INTERNAL_TRANSFER` scope，并新增 `TransferInternalBalanceInput` 与 `TransferInternalBalanceResponse` 类型。
  * 在 `EditVirtualCardInput` 中新增 `userCashBalanceId`，以便通过 `editVirtualCard` 将资金来源更改为指定的消费账户。
  * 在 `TransactionFilterInput` 中新增 `userCashBalanceIds` 用于通过 `getTransactions` 按消费账户过滤交易，并在 `getGiftCards` 中新增 `userCashBalanceId` 用于按消费账户过滤礼品卡。
  * 新增 `updateUserCashBalance` 和 `closeUserCashBalance` 变更，需具备 `MANAGE_PAYMENT` scope，并新增支持的输入与响应类型（`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月">
  * 新增用于管理已保存银行卡的变更：`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` 变更的响应现包含新的 `authorizationSetting` 字段。
  * **批量虚拟卡 API**：用于异步创建和管理大量虚拟卡的新 API。
  * `createVirtualCardBulkOrder` **变更**：提交批量订单并接收唯一的 `orderId`。
  * `getVirtualCardBulkOrderStatus` **查询**：轮询以跟踪订单状态并在完成后获取卡详情。
  * 批量制卡过程是异步的 —— 请检查订单状态以获取卡详情。
</Update>

<Update label="v0.0.32" tags={["Added"]} description="2025年7月">
  * **新增查询 `getVirtualCardOffers`**：提供所有可用于创建的在售虚拟卡优惠的完整列表，包括 `offerId`（制卡所必需）、`programName`、`bankName`、`rewardValue` 以及详细的项目限额（每日、每周、每月消费限额）。
  * **更新变更 `createVirtualCard`**：通过提供 `offerId`（来自 `getVirtualCardOffers`）、`spendLimit`，以及可自定义属性如 `cardNickname` 与 `spendLimitDuration`，以编程方式发行虚拟卡。
  * **新增变更 `editVirtualCard`**：更新现有虚拟卡的关键参数 —— `spendLimit`、`spendLimitDuration`、`lockDate`、`lockCardNextUse` 和 `cardNickname`。
  * **新增变更 `lockVirtualCard`**：立即锁定虚拟卡，阻止任何后续交易。
</Update>

<Update label="v0.0.31" tags={["Added"]} description="2025年7月">
  * `getMerchants` 响应中的 `Offer` 类型现包含 `deliveryFormat` 字段，用于指定优惠的履约方式：`URL`、`CODES`、`PIN_AS_CODE` 或 `PIN_WITH_URL`。
  * `getMerchants` 查询新增 `filterBy` 参数，允许你将结果过滤为仅包含具有特定 `deliveryFormat` 的优惠的商户。
</Update>

<Update label="v0.0.30" tags={["Added"]} description="2025年">
  * 增强 `getMerchants` 查询，新增 `offerTypes` 输入参数，允许按 `giftCardOffer`、`cardLinkedOffer` 或两者进行过滤。默认情况下，如果未提供 `offerTypes`，查询仅返回礼品卡优惠。
</Update>

<Update label="v0.0.29" tags={["Added","Improved"]} description="2025年">
  * 引入新查询 `getReferralUrl`，根据商户输入返回推荐字符串，并新增 `MerchantInput` 类型。
  * 为 `purchaseGiftCard` 变更引入自动重购尝试。如果使用银行卡、银行账户或 PayPal 购买礼品卡失败，系统会自动尝试使用 Fluz 余额重新购买。
  * 在 `PurchaseGiftCardInput` 中引入 `defaultToBalance` 字段，用于在主要支付方式失败时将 Fluz 余额设为备用支付方式。默认值为 `true`。
</Update>

<Update label="v0.0.27" tags={["Added","Improved"]} description="2025年">
  * 引入新的访问 scope：`CREATE_VIRTUALCARD`，用于创建虚拟卡。
  * 引入新函数 `createVirtualCard`，可按特定参数创建虚拟卡。
  * 新增查询 `getBINs`，用于检索与虚拟卡关联的 BIN。
  * 为现金余额充值引入 `merchantCategoryCode` 输入，以增强交易分类。
  * 新增查询 `getMccList`，用于检索商户类别码列表。
  * 增强 `getApplicationScopes` 查询的 scope 校验并改进 GraphQL 类型定义管理。
</Update>

<Update label="v0.0.26" tags={["Improved"]} description="2025年">
  * 增强商户优惠的库存信息处理：`Offer` 对象的 `stockInfo` 字段现在会根据优惠是固定还是可变，返回 `StockInfoFixedType` 或 `StockInfoVariableType`。
  * 增强错误处理，提供更直观的错误消息响应 —— 改进了 `purchaseGiftCard` 无可用优惠错误与账户与支付方式不匹配的响应。
</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)。