- 擷取禮品卡訂單清單 — 如果你剛完成購買且已經有
giftCardId，可以略過此步驟。 - 揭露禮品卡詳細資訊 — 使用
revealGiftCardByGiftCardIdmutation 以揭露禮品卡兌換詳細資訊。
第 1 步：擷取禮品卡訂單清單
📘 將禮品卡與你的訂單對帳若要取得你帳戶中訂購的禮品卡清單，請使用getGiftCards會回傳purchaseId（與purchaseGiftCard和getUserPurchases回傳的相同 UUID）、purchaseDisplayId（短版 Fluz 交易 ID，例如1047283），以及透過purchaseValue/currentValue/currency回傳的訂單金額。使用這些欄位即可將每個giftCardId對應回其來源訂單與金額，而不必揭露每一張卡片。
getGiftCards query。此呼叫會回傳包含基本資訊的禮品卡清單，包括 giftCardId。你需要此 ID 才能揭露禮品卡的詳細資訊。
範例 Query
Query 參數
執行此 query 會用到下列參數：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 — 此禮品卡購買所屬優惠的條款與細則（法律文字、限制、到期政策）。這是購買當下的條款與細則，可能與該商家目前啟用優惠的條款與細則不同 — 與 deliveryFormat 相同的理由。
📘 請優先使用getGiftCards回傳的deliveryFormat，而非getMerchants商家的有效優惠會隨時間變動。禮品卡購買時的格式可能與商家目前的有效優惠不同，因此在決定如何呈現revealGiftCardByGiftCardId的兌換詳細資訊時，請一律使用getGiftCards回傳的deliveryFormat。
第 2 步：揭露禮品卡詳細資訊
一旦你擷取到完整的禮品卡訂單清單後，即可使用revealGiftCardByGiftCardId mutation 揭露每張禮品卡的詳細資訊，包括禮品卡代碼與其他資訊。
輸入
revealGiftCardByGiftCardId mutation 只需要 giftCardId 作為輸入參數，即可在回應中取得你的禮品卡兌換詳細資訊。
範例 Mutation
範例回應
📘 並非所有商家的禮品卡都同時具有代碼、PIN 與 URL 視商家與合作夥伴而定，禮品卡詳細內容可能有所不同。有些商家使用英數代碼且不提供 PIN；有些商家或合作夥伴則只提供 URL，而不提供代碼與 PIN。 Fluz 會將我們從商家針對每筆禮品卡訂單所取得的所有資訊完整傳遞給你。
建議的輪詢策略
若禮品卡詳細資訊未立即回傳，你可以使用指數退避策略輪詢 Reveal Gift Card 端點。起始建議如下：- 初始延遲：300ms
- 退避策略：指數型（例如 300ms → 600ms → 1200ms → 2400ms → …）
- 最大延遲：180000ms（3 分鐘）
- 一旦成功取得禮品卡詳細資訊即停止輪詢