> ## 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.

# 購買禮品卡

一旦你決定了偏好的優惠，請使用 `purchaseGiftCard` mutation 來購買你的禮品卡。此 mutation 需要一個 `PurchaseGiftCardInput` 輸入物件。

## 範例 Mutation

以下是開始購買禮品卡的最快方式。你可以從 `UserPurchase` 物件自訂你的查詢。請參閱 [API 參考](https://storage.googleapis.com/fluz-public-docs/api-reference.html)。

```graphql theme={null}
mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    giftCard {
      giftCardId
      status
      termsAndConditions
    }
  }
}
```

## 欄位

以下欄位用於執行此 mutation：

`idempotencyKey` — 必填。由用戶端產生的唯一 UUID，以確保請求只被處理一次。

`offerId `**或** `merchantSlug` — 必填。使用 [`getOfferQuote`](/get-best-offer) 查詢中的 `offerId` 或 `merchantSlug` 來取得最佳優惠。使用 `merchantSlug` 將會自動以該商家的最佳優惠費率進行購買。

`amount` — 必填。你想購買的禮品卡金額。

***

以下欄位擇一提供即可。你也可以選擇將 Fluz 餘額與其他資金來源組合使用。

`exclusiveRateId` — 特定獨家費率優惠的唯一識別碼。若提供，將強制以該獨家費率進行購買；若未提供，系統會自動選擇最佳可用費率。`exclusiveRateId` 可在你於查詢的 `offers` 下提供 `exclusiveRateId` 時，從 [`getMerchants`](/get-catalog) 查詢回應中、類型為 `EXCLUSIVE_RATE_OFFER` 的優惠找到。

`balanceAmount` — 若要使用你的 Fluz 餘額支付禮品卡，請在此定義要使用的餘額金額。你可以使用 [`getWallet`](/check-account-balance) 查詢來檢查你的餘額。

`bankAccountId` — 若要使用銀行帳戶付款，請提供銀行帳戶 ID。

`bankCardId` — 若要使用銀行卡付款，請提供銀行卡 ID。

`paypalVaultId` — 若要使用 PayPal 帳戶付款，請提供 PayPal 帳戶 ID。

`defaultToBalance` — 若要在其他付款方式失敗時，改用你的 Fluz 餘額作為備援付款方式，將 `defaultToBalance` 設為 `true`。預設為 `true`。若將此設定變更為 `false`，系統將不會嘗試使用你的 Fluz 餘額作為備援付款方式。

`minRewardRate` — 若選擇 `merchantSlug` 方案時，想要指定可接受的最低回饋率。

`userCashBalanceId` — 若想指定此次購買所使用的現金餘額（消費帳戶）。

`memo` — 若想在此交易附加備註，請在此提供純文字備忘。最多 255 個字元。

`transactionCategory` — 若想為此交易分類，請提供分類名稱。分類在首次使用時會自動建立，之後若再次傳入相同名稱則會重複使用。

`attachmentId` — 若想在此交易附加檔案，請提供上傳端點回傳的 ID。請參閱 [新增費用明細](/features/add-expense-details)。

<Callout icon="📘">
  ### 請參閱 [新增費用明細](/features/add-expense-details) 以取得有關上傳附件以及使用備忘與分類的完整說明。
</Callout>

## PurchaseGiftCardInput

```json theme={null}
{
  "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "offerId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "amount": 987.65,
  "balanceAmount": 123.45,
  "bankAccountId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "bankCardId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "paypalVaultId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "exclusiveRateId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "merchantSlug": "xyz789",
  "minRewardRate": 5.6,
  "userCashBalanceId": "85de1b3e-4e72-462c-8ed1-a6f4982e22f7"
}
```

## 範例回應

當你的購買完成後，你將會收到類似以下的回應：

```json theme={null}
{
  "data": {
    "purchaseGiftCard": {
      "purchaseId": "255f8245-02c7-4817-901e-15fe265f6968",
      "purchaseDisplayId": "1019688",
      "purchaseBankCardId": "255f8245-02c7-4817-901e-15fe265f6968",
      "bankAccountId": "255f8245-02c7-4817-901e-15fe265f6968",
      "purchaseAmount": 123.45,
      "fluzpayAmount": 85.0,
      "seatRewardValue": 0.05,
      "paypalVaultId": "255f8245-02c7-4817-901e-15fe265f6968",
      "createdAt": "2007-12-03T10:15:30Z",
      "giftCard": {
        "giftCardId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
        "purchaserUserId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
        "endDate": "2007-12-03T10:15:30Z",
        "status": "ACTIVE",
        "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for...",
        "createdAt": "2007-12-03T10:15:30Z",
        "merchant": {
          "merchantId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
          "name": "Starbucks",
          "slug": "starbucks",
          "logoUrl": "https://storage.googleapis.com/.../starbucks-logo.jpg",
          "faceplateUrl": "https://storage.googleapis.com/.../starbucks-faceplate.png",
          "offers": [
            {
              "offeringMerchantId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
              "offerId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
              "type": "GIFT_CARD_OFFER",
              "deliveryFormat": "CODES",
              "barcodeType": "C128",
              "hasStockInfo": false,
              "offerRates": [
                {
                  "maxUserRewardValue": 5.0,
                  "cashbackVoucherRewardValue": 1.0,
                  "boostRewardValue": 0.5,
                  "displayBoostReward": true,
                  "denominations": [25, 50, 100],
                  "allowedPaymentMethods": ["CREDIT_CARD", "PAYPAL"]
                }
              ],
              "denominationsType": "VARIABLE",
              "stockInfo": []
            }
          ]
        }
      }
    }
  }
}
```

<Callout icon="🚧">
  ### 現金回饋比率可能變動。

  我們盡力為客戶提供最佳可用優惠。這表示回饋比率會定期變動。請在購買前務必確認當前比率。
</Callout>

## 購買多於一張卡

單次 `purchaseGiftCard` 呼叫只會以一個優惠、在一個費率下，購買一張禮品卡。沒有數量欄位，且單次呼叫不會在不同優惠或費率間拆分或混合。若要購買多張卡，請每張卡各送出一次 mutation，且各自使用唯一的 `idempotencyKey`。

由於每張卡各自為一次呼叫，當你訂購的數量超過某個有庫存的優惠時，將會依每次呼叫逐一處理：

* `offerId `（鎖定的優惠）：一旦該有庫存的優惠售罄，剩餘的呼叫將以 `GC-0009` 失敗。系統不會自動改用其他優惠或費率。
* `merchantSlug `（自動選擇）：剩餘的呼叫會自動選擇次佳的可用優惠——通常是較低回饋率的可變動優惠——除非 `minRewardRate` 阻擋了較低的比率。

如需每次呼叫的完整解析、`minRewardRate` 的最低比率策略，以及 `GC-0009` 的回應，請參閱 [大量購買](/purchase-in-bulk)。

### 大量下單：並行度、逾時與重試

對同一個 Fluz 帳戶進行扣款的購買會以序列方式處理。當許多 `purchaseGiftCard` 呼叫同時送至同一帳戶時，它們會彼此排隊，單次呼叫的回應時間可能變長——在高負載下偶爾會長達數分鐘。未進入佇列的呼叫通常在數秒內回應。

為了在大量下單時維持可預期的延遲並避免誤判為失敗：

* 請調節你的並行請求數量。與其同時對同一帳戶發送整個批次，不如分成較小的波段送出，或將量能分散到多個帳戶。這能維持較低的單次呼叫延遲。
* 使用較寬鬆的用戶端逾時。Fluz 不會在數秒後就放棄一筆進行中的購買——請求可能仍在合法處理中，且會回傳有效結果。過短的用戶端逾時（例如 30 秒）可能導致你放棄一筆最終會成功的購買。請將逾時設得足夠高，以吸收在高負載下偶發的數分鐘處理時間。我們建議 1 分鐘。
* 用戶端逾時不等於取消。關閉連線不會取消 Fluz 已接受的請求；它仍會持續處理至完成。將逾時視為未知結果，而非失敗。
* 以相同的 `idempotencyKey` 重試以解決逾時。使用完全相同的請求與相同的 `idempotencyKey` 重新發送。由於此鍵能保證購買至多處理一次，若原先已成功，重試會回傳原有購買——不會產生重複訂單或第二次扣款。切勿為已嘗試過的購買改用新的 `idempotencyKey`；那才會導致重複下單。

<Callout icon="📘">
  ### 若你的端發生逾時且不確定結果，請以相同的 `idempotencyKey` 重試，或在退款給最終用戶前，先以購買 ID 查詢該筆購買。逾時的請求往往已在 Fluz 端成功，且在退款前，禮品卡代碼依然可被揭示。
</Callout>

## 下一步

現在是時候揭示你的禮品卡詳細資訊以供使用。瞭解如何操作：

[檢視禮品卡](/view-gift-card)