Obtener catálogo

getMerchants Usa la consulta GraphQL getMerchants para recuperar la lista actual de comercios disponibles y sus ofertas del catálogo de Fluz. Esta es la forma principal de descubrir qué comercios están disponibles y qué tipos de ofertas tienen. Puedes refinar los resultados usando argumentos de entrada opcionales:

name: Filtra comercios por un nombre específico.
paginate: Controla la cantidad de resultados por página (limit) y el punto de inicio (offset).
offerTypes: Especifica si quieres giftCardOffers, cardLinkedOffers o ambos usando banderas booleanas (por ejemplo, { giftCardOffer: true, cardLinkedOffer: false }).
categoryId: Devuelve solo comercios en una categoría de compras, por ejemplo, Dining o Travel. Los ids de categoría provienen de getMerchantCategories. Una categoría desconocida o inactiva devuelve una lista vacía.
filterBy: Un objeto usado para aplicar filtros específicos a las ofertas dentro de cada comercio. Si un comercio no tiene ofertas restantes después de filtrar, se excluye de los resultados finales.
Filtros disponibles:
1. deliveryFormat: Filtra ofertas de tarjetas de regalo por su método de entrega.
  Valores permitidos: URL, CODES, PIN_AS_CODE, PIN_WITH_URL.

📘 Recuperar el catálogo completo de comercios sin filtros puede tomar tiempo. Recomendamos obtener el catálogo completo y sin filtrar solo una vez al día. Para actualizaciones más frecuentes o búsquedas específicas, usa los filtros name u offerTypes.

📘 Notas sobre la paginación: El límite predeterminado y máximo para la paginación es 20. El resultado no necesariamente devolverá la cantidad que defines como límite. Por ejemplo, puedes solicitar un límite de 10, pero la respuesta puede tener solo 7 resultados. Cuando se incluye un offset, recuerda incluir el monto del límite en tu cálculo de offset para el siguiente lote. Si no se especifica un límite, tendrás que aumentar el offset por el límite predeterminado de 20 (por ejemplo, offset+20).

📘 Obtención del catálogo completo de comercios: Si quieres todos los comercios disponibles, debes paginar hasta que la API devuelva un arreglo vacío. Pasos para obtener el catálogo completo:

Llama a getMerchants (offset = 0, limit = 20).

Anexa los comercios devueltos a tu lista local.

Incrementa el offset por tu límite (offset += 20).

Repite la solicitud.

Detente solo cuando la API devuelva un arreglo vacío ([]).

Estructura básica de la consulta

Aquí tienes una estructura de consulta flexible usando variables. Puedes ajustar la variable offerTypes para obtener las ofertas específicas que necesitas. Este ejemplo solicita solo los campos básicos más comunes. Solicitud de ejemplo:

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

Estructura de respuesta de ejemplo (ejemplo de tarjeta de regalo):

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.
          }
        ]
      }
    ]
  }
}

Detalles de la respuesta

El objeto Merchant devuelto por la consulta getMerchants incluye los siguientes campos:

Field name	Type	Description
merchantId	UUID!	El identificador único del comercio. Este ID es esencial para referenciar el comercio en otras consultas o transacciones de la API.
name	String	El nombre del comercio. Este es el nombre visible que los usuarios reconocerán al seleccionar un comercio para usar tarjetas de regalo o cargos con tarjeta virtual.
slug	String	Una versión del nombre del comercio amigable para URLs. El slug se usa con frecuencia en direcciones web o como referencia en la interfaz de usuario para facilitar su uso.
logoUrl	String	La URL de la imagen del logo del comercio. Normalmente una imagen cuadrada (1:1) adecuada para mostrar en listas de comercios y encabezados. Devuelve null si no está disponible.
faceplateUrl	String	La URL de la imagen rectangular de la tarjeta/faceplate del comercio. Es ideal para mostrar cuando no hay código de barras presente (barcodeType === “NONE”) o como fondo de tarjeta. Devuelve null si no está disponible.
categories	[MerchantCategory!]!	Las categorías de compras a las que pertenece este comercio, ordenadas por prioridad de visualización. Un comercio puede pertenecer a más de una, y la lista está vacía cuando el comercio no está categorizado. Cada entrada tiene un `categoryId` y un `name`.
offers	[Offer]	Un arreglo de objetos `Offer` que representan las promociones, descuentos u ofertas disponibles en el comercio. Cada objeto Offer proporciona detalles adicionales como el monto de descuento, fecha de vencimiento y condiciones aplicables.

Campos comunes de Offer (dentro del arreglo offers): Estos campos están presentes en cada objeto Offer, independientemente de su tipo.

Field Name	Type	Description
offeringMerchantId	UUID!	Un identificador único para el comercio que ofrece el descuento u oferta específica. Este es un campo requerido y debe ser un UUID válido.
offerId	UUID!	Un identificador único para la oferta en sí.
type	String!	Indica el tipo de la oferta. Puede ser una oferta estándar de tarjeta de regalo o una oferta de tasa exclusiva.
deliveryFormat	DeliveryFormatType	Especifica el método por el cual la oferta será entregada al usuario. Esto determina cómo el usuario recibirá y redimirá la oferta. Para ofertas vinculadas a tarjeta, este campo será null ya que la oferta se aplica automáticamente.
barcodeType	BarcodeTypeEnum	Especifica el formato de código de barras usado para esta oferta. Valores posibles: NONE (sin código de barras), C128 (Code 128), PDF417, QRCODE. Úsalo para determinar si debes renderizar un código de barras o mostrar elementos visuales alternativos como faceplateUrl.

Filtrar por categoría

Los comercios se agrupan en las mismas categorías de compras usadas en el catálogo de Fluz, como Dining, Travel y Grocery. Llama a getMerchantCategories una vez para obtener la lista, luego pasa un categoryId a getMerchants para mostrar una categoría a la vez.

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

Notas:

categoryId se combina con los otros argumentos, por lo que puedes filtrar por categoría y name en la misma llamada.
Un categoryId que no sea un UUID devuelve APPLICATIONS-0012 (InvalidArgument) con el mensaje categoryId must be a UUID. Category ids come from getMerchantCategories. Una cadena en blanco es la excepción: solo elimina el filtro de categoría — name, offerTypes, filterBy y la paginación aún aplican.
Si creas un caché del mapeo, almacena el categoryId en lugar del nombre — los ids son estables y una categoría puede ser renombrada.
Las asignaciones de categorías en el sandbox son datos de prueba y no coincidirán con producción.
Las mismas reglas de paginación aplican a una llamada filtrada que a una no filtrada.

Detalles específicos por tipo de oferta

Los detalles reales de una oferta dependen de su type. Debes solicitar e interpretar diferentes campos según el tipo de oferta:

Para ofertas de tarjetas de regalo (GIFT_CARD_OFFER, EXCLUSIVE_RATE_OFFER):
- Los campos clave incluyen offerRates, stockInfo, hasStockInfo, denominationsType, allowedPaymentMethods.
- Consulta la subpágina Ofertas de tarjetas de regalo para una explicación detallada y ejemplos de consultas.
Para ofertas vinculadas a tarjeta (CARD_LINKED_OFFER):
- El campo principal es cloDetails, que contiene tasas, periodos y condiciones.
- Consulta la subpágina Ofertas vinculadas a tarjeta para una explicación detallada y ejemplos de consultas.

​Estructura básica de la consulta

​Detalles de la respuesta

​Filtrar por categoría

​Detalles específicos por tipo de oferta

Estructura básica de la consulta

Detalles de la respuesta

Filtrar por categoría

Detalles específicos por tipo de oferta