- 获取礼品卡订单列表 — 如果您刚完成购买并已拥有
giftCardId，可以跳过此步骤。 - 显示礼品卡详情 — 使用
revealGiftCardByGiftCardIdmutation 来显示礼品卡的兑换详情。
第 1 步：获取礼品卡订单列表
📘 将礼品卡与您的订单进行对账要获取您账户中已订购的礼品卡列表，请使用getGiftCards会返回purchaseId（与purchaseGiftCard和getUserPurchases返回的相同 UUID）、purchaseDisplayId（简短的 Fluz 交易 ID，例如1047283），以及通过purchaseValue/currentValue/currency返回的订单金额。使用这些字段可将每个giftCardId映射回其来源订单及金额，而无需显示每一张卡。
getGiftCards 查询。该调用会返回包含基本信息的礼品卡列表，其中包括 giftCardId。您需要此 ID 才能显示礼品卡详情。
示例查询
查询参数
运行此查询会用到以下参数：status— 如果您想按状态筛选礼品卡。userCashBalanceId— 如果您想按现金余额（消费账户）筛选礼品卡。paginate— 分页字段paginate.limit— 每页最大礼品卡数量paginate.offset— 需要偏移的记录数量
示例响应
响应字段
purchaseId — 创建此礼品卡的购买的 UUID。使用它将礼品卡与您在调用 purchaseGiftCard / 从 getUserPurchases 时存储的 purchaseId 进行对账。如果未找到关联购买则返回 null。
purchaseDisplayId — 该笔购买的简短、易读的 Fluz 交易 ID（例如 1047283）。这是 Fluz 支持在人工审核和导出中引用的 ID。如果未找到关联购买则返回 null。
purchaseValue — 礼品卡购买时的面额（名义价值），以该卡的货币计。用于订单金额对账。
currentValue — 礼品卡的剩余余额，以该卡的货币计。对于一次性使用的卡，通常等于 purchaseValue。
currency — 礼品卡面额所使用的 ISO 货币代码（例如 USD）。
deliveryFormat — 购买该礼品卡时所对应优惠的交付格式。可能是 URL、CODES、PIN_AS_CODE、PIN_WITH_URL 或 CODE_WITH_PREFIX 之一。
termsAndConditions — 购买该礼品卡时对应优惠的条款与条件文本（法律条款、限制、到期政策）。这是下单时的 T&C，可能与该商户当前有效优惠的 T&C 不同——与 deliveryFormat 相同的原因。
📘 优先使用getGiftCards返回的deliveryFormat而非getMerchants商户的在售优惠可能随时间变更。礼品卡购买时的格式可能与商户当前活动优惠的格式不同，因此在决定如何渲染revealGiftCardByGiftCardId返回的兑换详情时，请始终使用getGiftCards返回的deliveryFormat。
第 2 步：显示礼品卡详情
在获取完整的礼品卡订单列表后，您可以使用revealGiftCardByGiftCardId mutation 显示每张礼品卡的详情，包括礼品卡代码及其他信息。
输入
revealGiftCardByGiftCardId 仅需要一个 giftCardId 输入参数即可返回您的礼品卡兑换详情。
示例 Mutation
示例响应
📘 并非所有商户礼品卡都同时提供代码、PIN 和 URL 具体详情因商户和合作方而异。有些商户使用字母数字组合代码且不提供 PIN；有些商户或合作方只提供 URL 而不提供代码和 PIN。 Fluz 会始终将我们从商户处获得的每张礼品卡的全部信息原样传递给您。
推荐的轮询策略
如果礼品卡详情未能立即返回，您可以使用指数回退策略轮询“显示礼品卡”端点。初始建议：- 初始延迟： 300ms
- 回退策略： 指数型（例如 300ms → 600ms → 1200ms → 2400ms → …）
- 最大延迟： 180000ms（3 分钟）
- 当成功返回礼品卡详情后停止轮询