1
查找优惠
拉取目录，或仅查询单一商户的最佳费率。→ 阅读目录
2
确认可购金额
固定或可变，有现货或按需生成。→ 固定 vs. 可变
3
购买
一次变更，一张卡，一个幂等键。→ 购买
4
揭示
获取代码、PIN 或 URL，并正确渲染。→ 揭示
术语
本节主要用到五个术语，其中三个听起来相似。
两个标识符容易混淆：
merchantId 标识品牌，offeringMerchantId 标识提供该笔交易的一方。你基于 offerId 或 slug 进行购买，绝不基于 merchantId。
阅读目录
三种入口，对应三类任务。
将
getMerchants 过滤为礼品卡：offerTypes: { giftCardOffer: true, cardLinkedOffer: false }。卡联优惠会出现在目录中，但目前通过 API 仅可购买礼品卡与专属优惠。
完整目录是缓存文件，每日刷新两次。
getOfferQuote 为实时。如果购买时的精确费率很重要——通常如此——请在购买前先报价，而不是相信今天早上的目录拉取。促销费率会反映在两者中，包括促销期间生成的 CSV 导出。专属优惠
费率会按账户定制。若你的账户有协商费率，它们会作为type: "EXCLUSIVE_RATE_OFFER" 的优惠出现，并带有 exclusiveRateId。将该 ID 传给 purchaseGiftCard 可强制按该费率购买；若省略，Fluz 会选择最佳可用费率。
固定 vs. 可变优惠
这是最影响你的集成方式的区分，而且一个商户可以同时有两种。FIXED
该卡采用预设面额——50, $100——你需按其原样购买。常由 Fluz 持有的真实库存背书，因此固定优惠通常具有更优费率与更高购买限额。库存有限，会耗尽。
VARIABLE
你可在最小/最大范围内任意选择金额，并实时生成卡片。无可耗尽的库存——几乎无限供应。通常回报率低于同品牌的固定优惠。
在哪里读取可购买金额
由两个字段决定，其组合决定答案在哪个字段里。搞错会提交该优惠无法满足的金额。
注意，“有库存信息”并不意味着“有可计数库存”。在可变优惠上，
stockInfo 返回的是一个范围，而非数量。只有 StockInfoFixedType 携带可递减的 availableStock 数字。
填充 stockInfo 需要 Fluz 与供应商确认库存，供应商响应时间不一——因此请求它会让查询更慢。仅在你即将基于它采取行动时再请求。→ 获取有库存优惠的库存
购买礼品卡
一个变更：purchaseGiftCard。三个决策点。
1. 如何选择优惠
固定选择给你费率的确定性；自动选择给你履约的确定性。
merchantSlug + minRewardRate 是折中方案，也是自动化下单的常用默认值。
2. 如何支付
至少需要一个资金来源，你可以将 Fluz 余额与其他来源组合使用。3. 幂等性
idempotencyKey 为必填，它决定重试与重复购买的区别。每张欲购的卡使用一个键，对同一张卡的每次重试都复用该键。→ 幂等性
→ 购买礼品卡
购买多张
一次调用只购买一张卡，基于一个优惠、一个费率。没有数量字段，也不能跨优惠混合。要十张卡，就发送十次调用，并使用十个不同的幂等键。 当你跑得比库存快时，结果取决于你如何选择优惠：- 固定（
offerId）——一旦库存型优惠耗尽，其余调用失败。无自动回退。 - 自动选择（
merchantSlug）——其余调用会转向次优优惠，通常是费率更低的可变优惠，除非被minRewardRate阻止。
大批量下单
针对同一 Fluz 账户的购买会顺序处理。一次性发起大批量请求会造成调用互相排队，偶尔需数分钟才返回。客户端超时不等于取消。 即使你不再等待，Fluz 仍会继续处理请求。将超时视为结果未知，而非失败。通过使用相同的
idempotencyKey 重试来确认结果——若原始购买已成功，重试会返回该结果，且不会重复扣款。为已尝试的购买换用新键，正是导致重复下单的方式。将客户端超时设置为约 1 分钟，分批次推进请求而非一股脑发出，并将大流量分散到多个账户。揭示礼品卡
购买后你会得到一个giftCardId。兑换详情通过第二次调用获取。
1
获取礼品卡
若你刚完成购买并已持有
giftCardId，可跳过此步。否则 getGiftCards 会列出它们及 purchaseId、purchaseDisplayId、purchaseValue、currentValue 与 status——足以在不揭示每张卡的情况下对账。2
揭示
revealGiftCardByGiftCardId 返回 code、pin、url 与 termsAndConditions。- 不是每张卡都有这三个字段。 有些商户仅发放无 PIN 的代码；有些只发放 URL。Fluz 原样透传商户提供的内容——请处理空值。
- 根据
deliveryFormat与barcodeType渲染， 且请从getGiftCards获取deliveryFormat，而非商户当前优惠。优惠会变化；卡是在购买时的格式下发行的。barcodeType为NONE、C128、PDF417或QRCODE；当为NONE时，考虑显示faceplateUrl。 - 详情可能不会即刻就绪。 使用指数退避轮询——300ms 起步，倍增，上限三分钟——一旦详情返回即停止。
授权范围（Scopes）
请在应用的 Permissions 选项卡中启用后再开发。未启用却请求的范围会被静默丢弃。→ 配置 OAuth 应用
当出现失败
完整列表：礼品卡错误代码。
在为终端用户处理失败或超时购买的退款之前，请使用相同的
idempotencyKey 重试或按 ID 查询该购买。 超时请求经常已成功，且代码在购买被退款前始终可被揭示。
下一步
获取目录
拉取商户及其优惠。
获取最佳优惠
单一商户与金额的实时报价。
获取库存
固定、带库存优惠的库存信息。
购买礼品卡
完整的变更调用。
批量购买
大批量下单与库存耗尽时的行为。
查看礼品卡
揭示代码、PIN 与 URL。