> ## 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.

# 查看礼品卡

getGiftCards, revealGiftCardByGiftCardId

购买礼品卡后，您需要调用 API 来显示礼品卡详情。按照以下步骤获取必要信息：

1. **获取礼品卡订单列表** — 如果您刚完成购买并已拥有 `giftCardId`，可以跳过此步骤。
2. **显示礼品卡详情** — 使用 `revealGiftCardByGiftCardId` mutation 来显示礼品卡的兑换详情。

## 第 1 步：获取礼品卡订单列表

> 📘 将礼品卡与您的订单进行对账
>
> `getGiftCards` 会返回 `purchaseId`（与 `purchaseGiftCard` 和 `getUserPurchases` 返回的相同 UUID）、`purchaseDisplayId`（简短的 Fluz 交易 ID，例如 `1047283`），以及通过 `purchaseValue` / `currentValue` / `currency` 返回的订单金额。使用这些字段可将每个 `giftCardId` 映射回其来源订单及金额，而无需显示每一张卡。

要获取您账户中已订购的礼品卡列表，请使用 `getGiftCards` 查询。该调用会返回包含基本信息的礼品卡列表，其中包括 `giftCardId`。您需要此 ID 才能显示礼品卡详情。

### 示例查询

```graphql theme={null}
query GetGiftCards {
  getGiftCards(
    paginate: { limit: 20, offset: 0 }
  ) {
    giftCardId
    purchaseId
    purchaseDisplayId
    purchaserUserId
    endDate
    status
    purchaseValue
    currentValue
    currency
    createdAt
    deliveryFormat
    termsAndConditions
    merchant {
      merchantId
      name
      slug
    }
  }
}
```

### 查询参数

运行此查询会用到以下参数：

* `status` — 如果您想按状态筛选礼品卡。
* `userCashBalanceId` — 如果您想按现金余额（消费账户）筛选礼品卡。
* `paginate` — 分页字段
  * `paginate.limit` — 每页最大礼品卡数量
  * `paginate.offset` — 需要偏移的记录数量

### 示例响应

```json theme={null}
{
  "data": {
    "getGiftCards": [
      {
        "giftCardId": "7c57c381-4b19-49e4-bbb0-404a45166ee4",
        "purchaseId": "785f57ff-f756-4f5c-afca-b896881e3e87",
        "purchaseDisplayId": "1047283",
        "purchaserUserId": "7c57c381-4b19-49e4-bbb0-404a45166ee4",
        "endDate": "2007-12-03T10:15:30Z",
        "status": "ACTIVE",
        "purchaseValue": 25,
        "currentValue": 25,
        "currency": "USD",
        "createdAt": "2007-12-03T10:15:30Z",
        "deliveryFormat": "PIN_WITH_URL",
        "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for...",
        "merchant": {
          "merchantId": "123",
          "name": "Merchant",
          "slug": "merchant"
        }
      }
    ]
  }
}
```

### 响应字段

`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

```graphql theme={null}
mutation RevealGiftCardByGiftCardId {
  revealGiftCardByGiftCardId(
    giftCardId: "86dd5fcf-fea3-4531-aa5d-1d196957f7d7"
  ) {
    code
    pin
    url
    termsAndConditions
  }
}
```

### 示例响应

```json theme={null}
{
  "data": {
    "revealGiftCardByGiftCardId": {
      "code": "9877890000000000",
      "pin": "2014",
      "url": null,
      "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
    }
  }
}
```

> 📘 并非所有商户礼品卡都同时提供代码、PIN 和 URL
>
> 具体详情因商户和合作方而异。有些商户使用字母数字组合代码且不提供 PIN；有些商户或合作方只提供 URL 而不提供代码和 PIN。
>
> Fluz 会始终将我们从商户处获得的每张礼品卡的全部信息原样传递给您。

## 推荐的轮询策略

如果礼品卡详情未能立即返回，您可以使用指数回退策略轮询“显示礼品卡”端点。初始建议：

* **初始延迟：** 300ms
* **回退策略：** 指数型（例如 300ms → 600ms → 1200ms → 2400ms → …）
* **最大延迟：** 180000ms（3 分钟）
* 当成功返回礼品卡详情后停止轮询

此方法在响应速度与系统负载之间取得平衡，并有助于避免不必要的超时或过多请求。