purchaseGiftCard 变更来购买礼品卡。此变更需要一个 PurchaseGiftCardInput 输入对象。
示例变更
以下是开始购买礼品卡的最快方式。你可以从UserPurchase 对象自定义查询。参见 API 参考。
字段
必填
idempotencyKey — 一个由客户端生成的唯一 UUID，确保请求只被处理一次。
offerId 或 merchantSlug — 使用 getOfferQuote 查询返回的 offerId 或 merchantSlug 来获取最佳优惠。使用 merchantSlug 将自动为该商户购买最佳费率的优惠。
amount — 你想要购买的礼品卡金额。
费率选择
exclusiveRateId — 某个专属费率优惠的唯一标识符。提供时，将强制购买使用该指定专属费率。如果未提供，系统将自动选择最佳可用费率。exclusiveRateId 可在你在查询请求的 offers 下提供 exclusiveRateId 时，对类型为 EXCLUSIVE_RATE_OFFER 的优惠的 getMerchants 查询响应中找到。
minRewardRate — 当选择 merchantSlug 选项时，如果你想指定可接受的最低返利率，可在此设置。
付款
至少需要一种资金来源。你也可以选择将你的 Fluz 余额与另一种资金来源组合使用。balanceAmount — 如果你想用 Fluz 余额支付礼品卡，请在此定义余额金额。你可以使用 getWallet 查询检查你的余额。
userCashBalanceId — 从中提取 balanceAmount 的消费账户。当你的账户持有多个消费账户时，请显式传递该字段。如果省略，Fluz 将从标记为 isDefault: true 的消费账户中提取。这是对 balanceAmount 的修饰，而不是另一种资金来源——参见选择消费账户。
bankAccountId — 如果你想用已链接的外部银行账户付款，请定义银行账户 ID。此项不是消费账户。
bankCardId — 如果你想用银行卡付款，请定义银行卡 ID。
paypalVaultId — 如果你想用 PayPal 账户付款，请定义 PayPal 账户 ID。
defaultToBalance — 如果你希望在其他支付方式失败时，将 Fluz 余额作为后备支付方式，请将 defaultToBalance 设为 true。默认即为 true。如果将此设置更改为 false，系统将不会尝试使用 Fluz 余额作为备用支付方式。
费用明细
memo — 如果你想在此交易中附加备注，请在此提供自由文本的备注。最多 255 个字符。
transactionCategory — 如果你想为此交易分类，请提供类别名称。类别在首次使用时自动创建，如果再次传入相同名称则复用。
attachmentId — 如果你想为此交易附加文件，请提供上传端点返回的 ID。参见添加费用明细。
PurchaseGiftCardInput
选择消费账户
消费账户是 Fluz 内部的现金余额账户，购买将从中提取资金。你的账户可以持有多个此类账户——例如“Main account”“Operations”或“Client A”——每个都有自己的昵称和余额。参见消费账户以了解完整模型。“消费账户”“现金余额”和
UserCashBalance 都指向同一个对象。产品将其呈现为消费账户。API 中类型命名为 UserCashBalance，因此该变更上的字段是 userCashBalanceId——而不是 accountId。注意，bankAccountId 无关：它指的是外部已链接的银行账户，而非消费账户。各字段作用
当你使用 Fluz 余额为购买提供资金时，有两个字段协同工作：
它们并不互斥。除非购买动用了余额（通过
balanceAmount 或 defaultToBalance 后备），否则 userCashBalanceId 不会产生任何影响。
省略 userCashBalanceId 时的默认行为
如果省略 userCashBalanceId，Fluz 将从标记为 isDefault: true 的消费账户中提取。
要在消费账户之间移动资金——例如，解锁一个错误账户扣款导致受阻的订单——请参见在消费账户之间转账。内部转账会立即结算。
步骤 1 — 获取你的消费账户 ID
使用getUserCashBalances 查询列出你的消费账户。这需要 LIST_PAYMENT 权限范围。
userCashBalanceId。该 ID 是稳定的，因此你可以将其保存在配置中，而无需每次购买都查找——不过在进行高频次下单前，应检查 availableCashBalance。
参见获取消费账户以了解完整字段参考、过滤选项和分页。
步骤 2 — 在购买中传入消费账户
defaultToBalance: false 设为 false 可防止任何隐式回退，因此购买要么从你指定的消费账户扣款，要么直接失败。在自动化下单流程中，这通常是你想要的行为。
在余额与另一资金来源之间拆分支付
userCashBalanceId 仅限定购买中余额部分的来源。要部分使用消费账户、其余从已链接银行卡支付：
示例响应
一旦购买完成，你将收到类似如下的响应：返现费率可能会变化。
我们尽最大努力始终为客户提供可用的最佳优惠。这意味着我们的费率会定期变化。在购买前请务必确认费率。购买多张礼品卡
一次purchaseGiftCard 调用恰好购买一张礼品卡、使用一个优惠、按一个费率。没有数量字段，且一次调用从不在多个优惠或费率之间拆分或混合。要购买多张，请为每张卡发送一次变更，并各自使用唯一的 idempotencyKey。
由于每张卡都是独立的调用，当订购数量超过某一有库存的优惠时，将按调用逐一处理结果：
offerId（固定优惠）： 一旦该库存优惠耗尽，剩余调用将以GC-0009失败。不会自动回退到其他优惠或费率。merchantSlug（自动选择）： 剩余调用将自动选择下一个最佳可用优惠——通常是返利率更低的浮动优惠——除非minRewardRate阻止更低费率。
minRewardRate 设定最低费率的模式，以及 GC-0009 响应，请参见批量购买。
大批量下单：并发、超时与重试
对同一 Fluz 账户扣款的购买会被顺序处理。当许多purchaseGiftCard 调用同时针对单一账户提交时，它们会彼此排队，单个调用的返回可能更慢——在高负载下偶尔可达数分钟。未排队的调用通常会在数秒内返回。
为保持可预测的延迟并避免在大批量下单时出现误判失败：
- 控制并发请求节奏。 不要把整批请求同时打向同一账户，而是分小波次提交，或将流量分散到多个账户。这能保持单调用延迟较低。
- 使用较宽松的客户端超时。 Fluz 不会在数秒后放弃进行中的购买——请求可能仍在合法处理，并会返回有效结果。过短的客户端超时（例如 30 秒）可能导致你放弃一个最终会成功的购买。请将超时设置得足够高，以吸收在负载下偶发的多分钟处理。我们建议 1 分钟。
- 客户端超时不等于取消。 关闭连接并不会取消 Fluz 已接受的请求；它仍会继续处理直至完成。将超时视为结果未知，而非失败。
- 通过使用相同的
idempotencyKey重试来解决超时。 使用完全相同的请求与完全相同的idempotencyKey重新发起。由于该键保证购买至多被处理一次，如果原请求已成功，重试将返回原始购买——不会创建重复或第二次扣款。切勿为已经尝试过的购买使用新的idempotencyKey；那样才会产生重复订单。
idempotencyKey 重试，或在退款给终端用户前通过 purchase ID 查询该购买。 在 Fluz 端，超时的请求往往已成功，且礼品卡代码在退款前仍可被展示。