purchaseGiftCard mutation 來購買你的禮品卡。此 mutation 需要一個 PurchaseGiftCardInput 輸入物件。
範例 Mutation
以下是開始購買禮品卡的最快方式。你可以從UserPurchase 物件自訂你的查詢。請參閱 API 參考。
欄位
以下欄位用於執行此 mutation：idempotencyKey — 必填。由用戶端產生的唯一 UUID，以確保請求只被處理一次。
offerId 或 merchantSlug — 必填。使用 getOfferQuote 查詢中的 offerId 或 merchantSlug 來取得最佳優惠。使用 merchantSlug 將會自動以該商家的最佳優惠費率進行購買。
amount — 必填。你想購買的禮品卡金額。
以下欄位擇一提供即可。你也可以選擇將 Fluz 餘額與其他資金來源組合使用。
exclusiveRateId — 特定獨家費率優惠的唯一識別碼。若提供，將強制以該獨家費率進行購買；若未提供，系統會自動選擇最佳可用費率。exclusiveRateId 可在你於查詢的 offers 下提供 exclusiveRateId 時，從 getMerchants 查詢回應中、類型為 EXCLUSIVE_RATE_OFFER 的優惠找到。
balanceAmount — 若要使用你的 Fluz 餘額支付禮品卡，請在此定義要使用的餘額金額。你可以使用 getWallet 查詢來檢查你的餘額。
bankAccountId — 若要使用銀行帳戶付款，請提供銀行帳戶 ID。
bankCardId — 若要使用銀行卡付款，請提供銀行卡 ID。
paypalVaultId — 若要使用 PayPal 帳戶付款，請提供 PayPal 帳戶 ID。
defaultToBalance — 若要在其他付款方式失敗時，改用你的 Fluz 餘額作為備援付款方式，將 defaultToBalance 設為 true。預設為 true。若將此設定變更為 false，系統將不會嘗試使用你的 Fluz 餘額作為備援付款方式。
minRewardRate — 若選擇 merchantSlug 方案時，想要指定可接受的最低回饋率。
userCashBalanceId — 若想指定此次購買所使用的現金餘額（消費帳戶）。
memo — 若想在此交易附加備註，請在此提供純文字備忘。最多 255 個字元。
transactionCategory — 若想為此交易分類，請提供分類名稱。分類在首次使用時會自動建立，之後若再次傳入相同名稱則會重複使用。
attachmentId — 若想在此交易附加檔案，請提供上傳端點回傳的 ID。請參閱 新增費用明細。
PurchaseGiftCardInput
範例回應
當你的購買完成後，你將會收到類似以下的回應：現金回饋比率可能變動。
我們盡力為客戶提供最佳可用優惠。這表示回饋比率會定期變動。請在購買前務必確認當前比率。購買多於一張卡
單次purchaseGiftCard 呼叫只會以一個優惠、在一個費率下，購買一張禮品卡。沒有數量欄位，且單次呼叫不會在不同優惠或費率間拆分或混合。若要購買多張卡，請每張卡各送出一次 mutation，且各自使用唯一的 idempotencyKey。
由於每張卡各自為一次呼叫，當你訂購的數量超過某個有庫存的優惠時，將會依每次呼叫逐一處理：
offerId（鎖定的優惠）：一旦該有庫存的優惠售罄，剩餘的呼叫將以GC-0009失敗。系統不會自動改用其他優惠或費率。merchantSlug（自動選擇）：剩餘的呼叫會自動選擇次佳的可用優惠——通常是較低回饋率的可變動優惠——除非minRewardRate阻擋了較低的比率。
minRewardRate 的最低比率策略，以及 GC-0009 的回應，請參閱 大量購買。
大量下單：並行度、逾時與重試
對同一個 Fluz 帳戶進行扣款的購買會以序列方式處理。當許多purchaseGiftCard 呼叫同時送至同一帳戶時，它們會彼此排隊，單次呼叫的回應時間可能變長——在高負載下偶爾會長達數分鐘。未進入佇列的呼叫通常在數秒內回應。
為了在大量下單時維持可預期的延遲並避免誤判為失敗：
- 請調節你的並行請求數量。與其同時對同一帳戶發送整個批次，不如分成較小的波段送出，或將量能分散到多個帳戶。這能維持較低的單次呼叫延遲。
- 使用較寬鬆的用戶端逾時。Fluz 不會在數秒後就放棄一筆進行中的購買——請求可能仍在合法處理中，且會回傳有效結果。過短的用戶端逾時（例如 30 秒）可能導致你放棄一筆最終會成功的購買。請將逾時設得足夠高，以吸收在高負載下偶發的數分鐘處理時間。我們建議 1 分鐘。
- 用戶端逾時不等於取消。關閉連線不會取消 Fluz 已接受的請求；它仍會持續處理至完成。將逾時視為未知結果，而非失敗。
- 以相同的
idempotencyKey重試以解決逾時。使用完全相同的請求與相同的idempotencyKey重新發送。由於此鍵能保證購買至多處理一次，若原先已成功，重試會回傳原有購買——不會產生重複訂單或第二次扣款。切勿為已嘗試過的購買改用新的idempotencyKey；那才會導致重複下單。