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

# 取得目錄

getMerchants

使用 `getMerchants` GraphQL 查詢，從 Fluz 目錄擷取目前可用商家及其優惠清單。這是發現可用商家及其提供之優惠類型的主要方式。

你可以使用選用的輸入參數來細化結果：

* `name`: 依特定名稱篩選商家。
* `paginate`: 控制每頁結果數量（`limit`）與起始位置（`offset`）。
* `offerTypes`: 使用布林旗標指定要 `giftCardOffer`、`cardLinkedOffer`，或兩者皆要（例如 `{ giftCardOffer: true, cardLinkedOffer: false }`）。
* `filterBy`: 用於對每個商家內的優惠套用特定篩選的物件。若商家在篩選後沒有任何剩餘優惠，將從最終結果中排除。\
  可用篩選：
  1. `deliveryFormat`: 依禮品卡優惠的傳遞方式篩選。\
     允許的值：`URL`、`CODES`、`PIN_AS_CODE`、`PIN_WITH_URL`。

> 📘 在沒有篩選條件的情況下擷取整個商家目錄可能會花費較多時間。我們建議一天僅擷取一次完整且未篩選的目錄。若需更頻繁更新或特定查詢，請使用 `name` 或 `offerTypes` 篩選。

> 📘 分頁注意事項：
>
> 分頁的預設與最大限制為 20。回應不一定會回傳你所設定的限制數量。例如，你請求 limit 為 10，但回應可能只有 7 筆結果。
>
> 當包含 offset 時，請記得在計算下一批次的 offset 時一併加入 limit 的數量。若未指定 limit，則需要以預設的 20 進行偏移（例如 offset+20）。

> 📘 擷取完整商家目錄：
>
> 若你想要所有可用商家，必須持續分頁直到 API 回傳空陣列為止。
>
> 擷取完整目錄的步驟：
>
> 1. 呼叫 getMerchants（offset = 0, limit = 20）。
> 2. 將回傳的商家附加到你的本地清單。
> 3. 依你的 limit 增加 offset（offset += 20）。
> 4. 重複請求。
> 5. 只有在 API 回傳空陣列（\[]）時才停止。

## 基本查詢結構

以下是使用變數的彈性查詢結構。你可以調整 `offerTypes` 變數以擷取所需的特定優惠。此範例僅請求最常見、基本的欄位。

範例請求：

```graphql theme={null}
# Define the query with variables
query GetMerchantCatalogBasic(
  $paginate: OffsetInput,
  $offerTypes: OfferTypesInput,  # Controls which offer types are returned
  $filterBy: FilterByInput
) {
  getMerchants(
    paginate: $paginate,
    offerTypes: $offerTypes,
    filterBy: $filterBy
  ) {
    # --- Common Merchant Fields ---
    merchantId
    name
    slug
    logoUrl        # Merchant logo image URL
    faceplateUrl   # Rectangular card art/faceplate image URL

    # --- Basic Offer Info (Common to all types) ---
    offers {
      offeringMerchantId
      offerId
      type          # Crucial field to identify offer type
      barcodeType   # Barcode format (NONE, C128, PDF417, QRCODE)
      # Request offer-specific fields like offerRates, stockInfo,
      # or cloDetails here based on expected types.
      # See subpages for details.
    }
  }
}

# Example Variables (Fetch Gift Cards Only):
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "offerTypes": { "giftCardOffer": true, "cardLinkedOffer": false }
# }

# Example Variables (Fetch CLOs Only):
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "offerTypes": { "giftCardOffer": false, "cardLinkedOffer": true }
# }

# Example Variables (Filter by deliveryFormat: CODES):
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "filterBy": { "deliveryFormat": URL }
# }
```

範例回應結構（禮品卡範例）：

```json json theme={null}
{
  "data": {
    "getMerchants": [
      {
        "merchantId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Example Merchant",
        "slug": "example-merchant",
        "logoUrl": "https://storage.googleapis.com/.../example-merchant-logo.jpg",
        "faceplateUrl": "https://storage.googleapis.com/.../example-merchant-faceplate.png",
        "offers": [
          {
            "offeringMerchantId": "3c7b4d5e-6f7g-8h9i-10jk-11l12m13n14o",
            "offerId": "1a2b3c4d-5e6f-7g8h-9i10-jk11l12m13n14",
            "type": "GIFT_CARD_OFFER",
            "barcodeType": "C128"
            // Other fields like offerRates, stockInfo would be here
            // if requested and applicable.
          }
        ]
      }
    ]
  }
}
```

## 回應細節

`getMerchants` 查詢所回傳的 `Merchant` 物件包含以下欄位：

| Field name   | Type     | Description                                                                   |
| :----------- | :------- | :---------------------------------------------------------------------------- |
| merchantId   | UUID!    | 商家的唯一識別碼。此 ID 對於在其他 API 查詢或交易中引用該商家至關重要。                                      |
| name         | String   | 商家的名稱。這是使用者在選擇用於禮品卡使用或虛擬卡付款時會辨識的顯示名稱。                                         |
| slug         | String   | 商家名稱的 URL 友善版本。slug 常用於網址中，或作為使用者介面中的參照以便於使用。                                 |
| logoUrl      | String   | 商家商標圖像的 URL。通常為正方形（1:1）圖像，適合顯示於商家清單與標題處。若不可用則回傳 null。                         |
| faceplateUrl | String   | 商家長方形卡面/卡片美術圖的 URL。當沒有條碼（barcodeType === "NONE"）時非常適合顯示，或作為卡片背景。若不可用則回傳 null。 |
| offers       | \[Offer] | 代表該商家可用之促銷、折扣或優惠的 `Offer` 物件陣列。每個 Offer 物件提供額外細節，例如折扣金額、到期日與任何適用條件。           |

常見 Offer 欄位（位於 offers 陣列中）：

以下欄位存在於每個 `Offer` 物件中，無論其類型為何。

| Field Name         | Type               | Description                                                                                          |
| :----------------- | :----------------- | :--------------------------------------------------------------------------------------------------- |
| offeringMerchantId | UUID!              | 提供該筆優惠或折扣之商家的唯一識別碼。此為必填欄位且必須為有效的 UUID。                                                               |
| offerId            | UUID!              | 該優惠本身的唯一識別碼。                                                                                         |
| type               | String!            | 指示優惠的類型。可能是一般禮品卡優惠或專屬費率優惠。                                                                           |
| deliveryFormat     | DeliveryFormatType | 指定優惠傳遞給使用者的方式。這決定使用者將如何接收並兌換優惠。對於卡片連結優惠而言，此欄位將為 null，因為優惠會自動套用。                                      |
| barcodeType        | BarcodeTypeEnum    | 指定此優惠所使用的條碼格式。可能值：NONE（無條碼）、C128（Code 128）、PDF417、QRCODE。使用此欄位來判斷是否要繪製條碼或改為顯示如 faceplateUrl 等替代視覺元素。 |

## 針對不同優惠類型的詳細資訊

優惠的實際細節取決於其 `type`。你需要依優惠類型請求並解析不同的欄位：

* 對於禮品卡優惠（`GIFT_CARD_OFFER`、`EXCLUSIVE_RATE_OFFER`）：
  * 重要欄位包含 `offerRates`、`stockInfo`、`hasStockInfo`、`denominationsType`、`allowedPaymentMethods`。
  * 請參閱子頁面 [Gift Card Offers](/get-gift-card-offers) 以取得詳細說明與查詢範例。
* 對於卡片連結優惠（`CARD_LINKED_OFFER`）：
  * 主要欄位為 `cloDetails`，其中包含費率、期間與條件。
  * 請參閱子頁面 [Card Linked Offers](/features/card-linked-offers) 以取得詳細說明與查詢範例。

<br />

<StickyContactSalesBanner />