取得目錄 - Fluz

getMerchants 使用 getMerchants GraphQL 查詢，從 Fluz 目錄擷取目前可用的商家及其優惠清單。這是探索可用商家與其提供之優惠類型的主要方式。你可以使用可選的輸入參數來調整結果：

name: 依指定名稱篩選商家。
paginate: 控制每頁結果數量（limit）與起始點（offset）。
offerTypes: 使用布林旗標指定要 giftCardOffer、cardLinkedOffer，或兩者（例如 { giftCardOffer: true, cardLinkedOffer: false }）。
categoryId: 只回傳某一個購物分類中的商家，例如 Dining 或 Travel。分類 ID 來自 getMerchantCategories。未知或未啟用的分類會回傳空清單。
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 回傳空陣列為止。 擷取完整目錄的步驟：

呼叫 getMerchants（offset = 0, limit = 20）。

將回傳的商家附加到你的本地清單。

依你的 limit 增加 offset（offset += 20）。

重複請求。

僅當 API 回傳空陣列（[]）時才停止。

基本查詢結構

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

# 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

    # --- Shopping categories (a merchant can be in more than one) ---
    categories {
      categoryId
      name
    }

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

{
  "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",
        "categories": [
          { "categoryId": "223e4567-e89b-12d3-a456-426614174001", "name": "Dining" }
        ],
        "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。
categories	[MerchantCategory!]!	該商家所屬的購物分類，依顯示優先序排列。一個商家可屬於多個分類，若未分類則為空清單。每個項目包含 `categoryId` 與 `name`。
offers	[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 等替代視覺元素。

依分類篩選

商家會依 Fluz 目錄中的相同購物分類分組，例如 Dining、Travel、Grocery。先呼叫一次 getMerchantCategories 取得清單，接著在 getMerchants 傳入 categoryId 以一次顯示一個分類。

query GetMerchantCategories {
  getMerchantCategories {
    categoryId
    name
  }
}

query GetMerchantsByCategory($categoryId: UUID, $paginate: OffsetInput) {
  getMerchants(categoryId: $categoryId, paginate: $paginate) {
    merchantId
    name
    slug
    categories {
      categoryId
      name
    }
  }
}

# Example Variables:
# {
#   "categoryId": "223e4567-e89b-12d3-a456-426614174001",
#   "paginate": { "limit": 20, "offset": 0 }
# }

注意事項：

categoryId 可與其他參數一同使用，因此你可以在同一次呼叫中同時依分類與 name 篩選。
不是 UUID 的 categoryId 會回傳 APPLICATIONS-0012（InvalidArgument），訊息為 categoryId must be a UUID. Category ids come from getMerchantCategories.。空字串則是例外：它只會移除分類篩選 —— name、offerTypes、filterBy 與分頁仍然適用。
若你快取對應關係，請儲存 categoryId 而非名稱 —— ID 穩定，分類名稱可能被更改。
沙盒中的分類指派屬於測試資料，與正式環境不一定相同。
針對已套用篩選的呼叫，與未篩選的呼叫適用相同的分頁規則。

依優惠類型的詳細資訊

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

對於禮品卡優惠（GIFT_CARD_OFFER、EXCLUSIVE_RATE_OFFER）：
- 重要欄位包含 offerRates、stockInfo、hasStockInfo、denominationsType、allowedPaymentMethods。
- 請參考 Gift Card Offers 子頁以取得詳細說明與查詢範例。
對於卡片連結優惠（CARD_LINKED_OFFER）：
- 主要欄位為 cloDetails，其中包含費率、期間與條件。
- 請參考 Card Linked Offers 子頁以取得詳細說明與查詢範例。

​基本查詢結構

​回應詳細資訊

​依分類篩選

​依優惠類型的詳細資訊

基本查詢結構

回應詳細資訊

依分類篩選

依優惠類型的詳細資訊