> ## 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` 筛选。

> 📘 分页注意事项：
>
> 分页的默认和最大 limit 为 20。结果不一定会返回你定义的 limit 数量。例如，你请求 limit 为 10，但响应可能只有 7 条结果。
>
> 当包含 offset 时，记得在计算下一批的 offset 时加入 limit 数量。如果未指定 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` 对象包含以下字段：

| 字段名          | 类型       | 描述                                                                             |
| :----------- | :------- | :----------------------------------------------------------------------------- |
| 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` 对象中，无论其类型如何。

| 字段名                | 类型                 | 描述                                                                                                    |
| :----------------- | :----------------- | :---------------------------------------------------------------------------------------------------- |
| 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`。
  * 详细说明与查询示例请参见[礼品卡优惠](/get-gift-card-offers)子页面。
* 针对卡链接优惠（`CARD_LINKED_OFFER`）：
  * 主要字段为 `cloDetails`，其中包含费率、周期及条件。
  * 详细说明与查询示例请参见[卡链接优惠](/features/card-linked-offers)子页面。

<br />

<StickyContactSalesBanner />