Skip to main content
透過 Fluz 購買禮品卡共有四個步驟，每一步都有對應的頁面。這是導覽圖。
1

尋找優惠

取用目錄，或查詢單一商家的最佳費率。→ 閱讀目錄
2

確認可購買的金額

固定或可變、現貨或即時產生。→ 固定 vs. 可變
3

購買

一次 mutation、一張卡、一個冪等鍵。→ 購買
4

揭示

取得代碼、PIN 或 URL，並正確呈現。→ 揭示
費率不斷變動。 Fluz 會持續重新定價以提供最佳可用優惠，且你的費率會針對你的帳戶客製化。切勿快取一個費率並稍後再依該費率購買——請在購買前立即重新確認。

​
詞彙

本節主要使用五個術語，其中有三個聽起來很像。 兩個識別碼容易混淆：merchantId 代表品牌，offeringMerchantId 代表提供該筆優惠的一方。你會針對 offerId 或 slug 下單，從不會針對 merchantId 下單。

​
Reading the catalog

三種進入方式，對應三種工作。 將 getMerchants 過濾為僅包含禮品卡：offerTypes: { giftCardOffer: true, cardLinkedOffer: false }。卡片連結型優惠會出現在目錄中，但目前透過 API 僅能購買禮品卡與專屬優惠。
完整目錄是一個快取檔案，每日更新兩次。 getOfferQuote 是即時資料。若購買時精準費率很重要——通常都很重要——請在購買前進行報價，而不要信任今天早上的目錄拉取。促銷費率會在兩者中反映，包括促銷期間產生的 CSV 匯出。
這兩個查詢都受速率限制，請分頁拉取完整目錄，而非一次請求全部。→ Get Catalog · Get Gift Card Offers · Get the Best Offer

​
專屬優惠

費率會依帳戶客製化。若你的帳戶有協議費率，它們會以 type: "EXCLUSIVE_RATE_OFFER" 的優惠出現，並帶有 exclusiveRateId。在 purchaseGiftCard 傳入該 ID 可強制使用該費率；若省略，Fluz 會挑選最佳可用的。

​
固定 vs. 可變優惠

這個區別最影響你的建置方式，而且同一個商家可以同時擁有兩種。

FIXED

卡片採用預設面額——25、25、50、$100——必須精確購買其中之一。經常由 Fluz 持有的真實庫存支撐，因此固定優惠通常具有更佳的費率與更高的購買上限。庫存是有限的。會售罄。

VARIABLE

你可以在最小/最大範圍內任選金額，卡片會即時產生。沒有庫存可耗盡——供應量實質上不受限。通常相較於同品牌的固定優惠，獎勵費率較低。
實務上的取捨：固定優惠回饋較高但可能在執行中途售罄；可變優惠永遠可用但回饋較低。大量下單通常先吃固定庫存，再退回可變。

​
何處讀取可購買的金額

由兩個欄位決定，且其組合決定哪個欄位包含答案。搞錯的話，你會提交優惠無法兌付的金額。
stockInfo 是一個聯合型別。你必須以行內片段查詢兩種形態，否則其中一種你會拿不到資料：
無論你自以為會拿到哪一種，都要同時包含兩個片段。請參考 How the GraphQL API works。
注意，「有庫存資訊」不代表「有可計數的庫存」。在可變優惠上，stockInfo 回傳的是一個「範圍」，而非數量。只有 StockInfoFixedType 會帶有可遞減的 availableStock 數字。 填充 stockInfo 需要 Fluz 與供應商確認庫存，而供應商回應時間不一——因此請求該欄位會使查詢較慢。只在你即將據此行動時才請求。→ Get Inventory on Stocked Offers

​
購買禮品卡

一個 mutation：purchaseGiftCard。三個決策。

​
1. 如何選擇優惠

固定鎖定可讓你確定費率；自動選擇可讓你確保成交。merchantSlug + minRewardRate 是折衷，通常是自動化下單的預設正解。

​
2. 如何付款

至少需要一種資金來源，你可以把 Fluz 餘額與另一來源併用。
若你的帳戶持有多個消費帳戶，請一律明確傳入 userCashBalanceId。 若省略，Fluz 會從被標記為 isDefault 的任一帳戶扣款——該標記可能在你的程式碼不變的情況下被更動，默默改變資金來源。這是最常見的「餘額不足」驚訝來源。在自動化流程中，也請設定 defaultToBalance: false，以便購買要嘛只從你指定的帳戶扣款，要嘛乾脆明確失敗。

​
3. 冪等性

idempotencyKey 為必填，這是重試與重複購買的分水嶺。每張預期購買的卡片一個鍵，重試同一張卡時重用同一個鍵。→ Idempotency → Purchase Gift Card

​
一次購買多張

一次呼叫只會購買一張卡、對應一個優惠、以一個費率。沒有數量欄位，也不會跨優惠混購。要十張，就送十次呼叫，使用十個不同的冪等鍵。 當你超過庫存時會發生什麼，取決於你如何選擇優惠：
  • 固定鎖定（offerId）——一旦庫存型優惠售罄，剩餘呼叫全部失敗。不會自動退回。
  • 自動選擇（merchantSlug）——剩餘呼叫會轉往次佳優惠，通常是費率較低的可變優惠，除非被 minRewardRate 阻擋。
→ Purchase in Bulk

​
大量下單

針對同一個 Fluz 帳戶的購買會依序處理。若一次發送大量批次，呼叫會彼此排隊，有時需要數分鐘才回應。
用戶端逾時不等於取消。 即使你不再等待，Fluz 仍會持續處理該請求。請將逾時視為「未知結果」，而非失敗。解法是使用相同的 idempotencyKey 重新嘗試——若原始購買已成功，重試會回傳同一結果，且不會重複扣款。為已嘗試過的購買換一個新鍵，正是造成重複下單的作法。將用戶端逾時設為約一分鐘，以波段節奏送出請求而非一次全發，並將重量級流量分散到多個帳戶。

​
揭示卡片

購買會給你一個 giftCardId。兌換細節透過第二次呼叫取得。
1

取得禮品卡

若剛完成購買且已持有 giftCardId，可略過此步。否則 getGiftCards 會列示它們，並附帶 purchaseId、purchaseDisplayId、purchaseValue、currentValue 與 status——足以在不揭示每張卡的情況下進行對帳。
2

揭示它

revealGiftCardByGiftCardId 會回傳 code、pin、url 與 termsAndConditions。
三件常見的踩雷點：
  • 不是每張卡都有三個欄位。 有些商家只發一組代碼、沒有 PIN；有些只發 URL。Fluz 會原樣轉交商家提供的內容——請處理 null。
  • 依 deliveryFormat 與 barcodeType 呈現， 且 deliveryFormat 要從 getGiftCards 取得，而不是從商家目前的優惠。優惠會變；卡片是依購買當下生效的格式發行。barcodeType 可能是 NONE、C128、PDF417 或 QRCODE；當為 NONE 時，考慮改顯示 faceplateUrl。
  • 細節可能不會即時就緒。 請以指數退避輪詢——300ms 起跳、每次加倍、上限三分鐘——並在細節回來時立即停止。
→ View Gift Cards

​
權限範圍

請先在你的應用程式的 Permissions 分頁啟用這些權限再開始開發。你請求但未啟用的 scope 會被靜默移除。→ Configure OAuth App

​
當事情失敗時

完整清單：Gift Card Error Codes。 在對終端使用者進行退款之前（針對失敗或逾時的購買），請使用相同的 idempotencyKey 重試，或以 ID 查詢該筆購買。 逾時的請求常常其實已成功，而代碼會在購買被退款之前一直可揭示。

​
下一步

取得目錄

拉取商家與其優惠。

取得最佳優惠

單一商家與金額的即時報價。

取得庫存

固定且有庫存的優惠之存量。

購買禮品卡

完整的 mutation。

批次購買

大量下單與售罄時的行為。

檢視禮品卡

揭示代碼、PIN 與 URL。