purchaseGiftCard mutation 來購買禮品卡。此 mutation 需要 PurchaseGiftCardInput 輸入物件。
範例 Mutation
以下是開始購買禮品卡的最快方式。你可以從UserPurchase 物件自訂查詢。請參閱 API 參考。
欄位
必填
idempotencyKey — 由客戶端產生的唯一 UUID，用於確保請求只被處理一次。
offerId 或 merchantSlug — 使用 getOfferQuote 查詢中的 offerId 或 merchantSlug 以取得最佳優惠。使用 merchantSlug 將自動購買該商家的最佳優惠費率。
amount — 你想購買的禮品卡金額。
費率選擇
exclusiveRateId — 特定專屬費率優惠的唯一識別碼。當提供時，會強制以該指定的專屬費率購買。若未提供，系統將自動選擇最佳可用費率。在你於查詢請求的 offers 下提供 exclusiveRateId 時，可在 getMerchants 查詢回應中，對於 EXCLUSIVE_RATE_OFFER 類型的優惠找到 exclusiveRateId。
minRewardRate — 若選擇 merchantSlug 選項時，希望指定可接受的最低回饋率。
付款
至少需要一個資金來源。你也可以選擇將 Fluz 餘額與其他資金來源併用。balanceAmount — 若要使用 Fluz 餘額支付禮品卡，請在此定義使用的餘額金額。你可以使用 getWallet 查詢來檢查你的餘額。
userCashBalanceId — 提領 balanceAmount 的消費帳戶。當你的帳戶持有多個消費帳戶時，請明確傳入此值。若省略，Fluz 會自預設標記為 isDefault: true 的消費帳戶提領。這是 balanceAmount 的修飾欄位，而不是替代資金來源 — 請參見選擇消費帳戶。
bankAccountId — 若要以外部連結的銀行帳戶付款，請提供銀行帳戶 ID。這不是消費帳戶。
bankCardId — 若要以銀行卡付款，請提供銀行卡 ID。
paypalVaultId — 若要以 PayPal 帳戶付款，請提供 PayPal 帳戶 ID。
defaultToBalance — 若希望當其他付款方式失敗時，使用 Fluz 餘額作為後備付款方式，請將 defaultToBalance 設為 true。預設為 true。若將此設為 false，系統將不會嘗試使用 Fluz 餘額作為備援付款方式。
費用明細
memo — 若要為這筆交易附註，請在此提供純文字備註。最多 255 個字元。
transactionCategory — 若要為這筆交易分類，請提供分類名稱。分類在首次使用時會自動建立，並在再次傳入相同名稱時重複使用。
attachmentId — 若要為這筆交易附加檔案，請提供由上傳端點回傳的 ID。請參見 新增費用明細。
PurchaseGiftCardInput
選擇消費帳戶
消費帳戶是 Fluz 內部的現金餘額帳戶，用於支付購買所需的資金。你的帳戶可以擁有多個消費帳戶——例如「Main account」、「Operations」或「Client A」——每個都有自己的暱稱與餘額。完整模型請參見 消費帳戶。「Spend account」、「cash balance」以及
UserCashBalance 都指同一個物件。在產品介面中稱為消費帳戶。API 的型別名稱為 UserCashBalance，因此此 mutation 上的欄位為 userCashBalanceId —— 而非 accountId。請注意，bankAccountId 無關：它指的是「外部」連結的銀行帳戶，而非消費帳戶。各欄位的作用
當你以 Fluz 餘額為購買提供資金時，有兩個欄位會共同運作：
這兩者並不互斥。除非購買動用了餘額——不論是透過
balanceAmount 或 defaultToBalance 後備機制——否則 userCashBalanceId 不會產生效果。
省略 userCashBalanceId 時的預設行為
若你省略 userCashBalanceId，Fluz 會自預設標記為 isDefault: true 的消費帳戶提領。
若要在消費帳戶間移轉資金——例如修正訂單提領自錯誤帳戶的情況——請參見在消費帳戶間轉帳。內部轉帳會立即結算。
第一步 — 取得你的消費帳戶 ID
使用getUserCashBalances 查詢列出你的消費帳戶。此操作需要 LIST_PAYMENT 權限範圍。
userCashBalanceId。此 ID 穩定可用，因此你可以將其存於設定中，而不必在每次購買時查詢——但在高交易量執行前，仍應檢查 availableCashBalance。
完整欄位參考、篩選選項與分頁，請參見取得消費帳戶。
第二步 — 在購買時傳入消費帳戶
defaultToBalance: false 設定為關閉任何隱性後備，因此此購買將從你指定的消費帳戶提領，否則就乾淨地失敗。在自動化下單流程中，這通常是你想要的行為。
將購買分攤於餘額與其他資金來源
userCashBalanceId 僅作用於購買中的餘額部分。若要部分由消費帳戶支付，餘額由連結的銀行卡支付：
範例回應
當你的購買完成後，你將會收到如下的回應：現金回饋費率可能變動。
我們盡力隨時為客戶提供最佳可用優惠。這代表我們的費率會定期調整。購買前請務必確認費率。購買多張卡
一次purchaseGiftCard 呼叫只會購買「一張」禮品卡、對應「一個」優惠、以「一個」費率。沒有數量欄位，且一次呼叫不會在多個優惠或費率間拆分或混合。若要購買多張卡，請每張卡送出一次 mutation，且各自使用唯一的 idempotencyKey。
由於每張卡都是獨立的呼叫，當訂購數量超過某個有庫存的優惠時，結果會逐次決定：
offerId（固定優惠）： 一旦該有庫存的優惠被買完，其餘呼叫將以GC-0009失敗。系統不會自動回退到其他優惠或費率。merchantSlug（自動選擇）： 其餘呼叫將自動選擇次佳的可用優惠——通常是較低回饋率的變動優惠——除非minRewardRate阻擋較低的費率。
minRewardRate 最低費率門檻模式，以及 GC-0009 回應，請參見大量購買。
大量下單：併發、逾時與重試
對同一個 Fluz 帳戶提領資金的購買會以序列方式處理。當許多purchaseGiftCard 呼叫同時對單一帳戶送出時，它們會彼此排隊，單筆呼叫的回應時間可能會拉長——在大量負載下偶爾可達數分鐘。未進入佇列的呼叫通常在數秒內回應。
為了在大量下單時保持可預期的延遲並避免誤判失敗：
- 調節你的併發請求。 不要一次性對同一帳戶發送整批請求，改以較小波次送出，或分散到多個帳戶。這能壓低單筆呼叫延遲。
- 使用寬鬆的用戶端逾時。 Fluz 不會在數秒後放棄進行中的購買——請求仍可能在合法處理並回傳有效結果。過短的用戶端逾時（例如 30 秒）可能導致你放棄一筆最終成功的購買。請將逾時設得足夠高以承受偶發的多分鐘處理。我們建議 1 分鐘。
- 用戶端逾時不代表取消。 關閉連線不會取消 Fluz 已接受的請求；該請求會持續處理至完成。將逾時視為「未知」結果，而非失敗。
- 以相同的
idempotencyKey重試以解決逾時。 使用相同的請求與相同的idempotencyKey重新送出。由於此鍵可保證購買至多被處理一次，若原請求已成功，重試會回傳原先的購買結果——不會建立重複或第二次扣款。切勿對已嘗試的購買改用新的idempotencyKey；那才會造成重複訂單。
idempotencyKey 重試，或在退款給終端使用者前，先用購買 ID 查詢該筆交易。 逾時的請求往往已在 Fluz 端成功，且在退款前該禮品卡代碼仍可被揭露。