> ## 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` query。此呼叫會回傳包含基本資訊的禮品卡清單，包括 `giftCardId`。你需要此 ID 才能揭露禮品卡的詳細資訊。

### 範例 Query

```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
    }
  }
}
```

### Query 參數

執行此 query 會用到下列參數：

* `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` — 此禮品卡購買所屬優惠的條款與細則（法律文字、限制、到期政策）。這是購買當下的條款與細則，可能與該商家目前啟用優惠的條款與細則不同 — 與 `deliveryFormat` 相同的理由。

> 📘 請優先使用 `getGiftCards` 回傳的 `deliveryFormat`，而非 `getMerchants`
>
> 商家的有效優惠會隨時間變動。禮品卡購買時的格式可能與商家目前的有效優惠不同，因此在決定如何呈現 `revealGiftCardByGiftCardId` 的兌換詳細資訊時，請一律使用 `getGiftCards` 回傳的 `deliveryFormat`。

## 第 2 步：揭露禮品卡詳細資訊

一旦你擷取到完整的禮品卡訂單清單後，即可使用 `revealGiftCardByGiftCardId` mutation 揭露每張禮品卡的詳細資訊，包括禮品卡代碼與其他資訊。

### 輸入

`revealGiftCardByGiftCardId` mutation 只需要 `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 會將我們從商家針對每筆禮品卡訂單所取得的所有資訊完整傳遞給你。

## 建議的輪詢策略

若禮品卡詳細資訊未立即回傳，你可以使用指數退避策略輪詢 Reveal Gift Card 端點。起始建議如下：

* 初始延遲：300ms
* 退避策略：指數型（例如 300ms → 600ms → 1200ms → 2400ms → …）
* 最大延遲：180000ms（3 分鐘）
* 一旦成功取得禮品卡詳細資訊即停止輪詢

此作法可在回應速度與系統負載間取得平衡，並有助於避免不必要的逾時或過多請求。