获取目录 - 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 筛选器。

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

字段名	类型	描述
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 对象提供额外详情，例如折扣金额、到期日期和适用条件。

通用 Offer 字段（位于 offers 数组内）：这些字段在每个 Offer 对象中都存在，无论其类型如何。

字段名	类型	描述
offeringMerchantId	UUID!	提供该特定优惠或折扣的商户的唯一标识符。该字段为必填，且必须为有效的 UUID。
offerId	UUID!	优惠自身的唯一标识符。
type	String!	表示优惠的类型。可能是标准礼品卡优惠或专属费率优惠。
deliveryFormat	DeliveryFormatType	指定该优惠将以何种方式交付给用户。这决定了用户如何接收和兑换优惠。对于卡链接优惠，此字段为 null，因为该优惠会自动应用。
barcodeType	BarcodeTypeEnum	指定该优惠使用的条码格式。可能的值：NONE（无条码）、C128（Code 128）、PDF417、QRCODE。使用此字段来决定是渲染条码还是显示诸如 faceplateUrl 等替代视觉元素。

按类别筛选

商户被分组到与 Fluz 目录相同的购物类别中，例如 Dining、Travel 和 Grocery。先调用一次 getMerchantCategories 获取列表，然后将 categoryId 传给 getMerchants，以一次显示一个类别。

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。
- 详见子页面 礼品卡优惠 的说明与查询示例。
对于卡链接优惠（CARD_LINKED_OFFER）：
- 主要字段为 cloDetails，其中包含费率、有效期和条件。
- 详见子页面 卡链接优惠 的说明与查询示例。

​基本查询结构

​响应详情

​按类别筛选

​按优惠类型查看详情

基本查询结构

响应详情

按类别筛选

按优惠类型查看详情