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 utilizando 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 }).
filterBy: Un objeto usado para aplicar filtros específicos a las ofertas dentro de cada comercio. Si un comercio no tiene ofertas después de aplicar los filtros, se excluye de los resultados finales.
Filtros disponibles:
1. deliveryFormat: Filtra las ofertas de tarjeta de regalo por su método de entrega.
  Valores permitidos: URL, CODES, PIN_AS_CODE, PIN_WITH_URL.

📘 Recuperar todo el catálogo de comercios sin filtros puede llevar 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 definas como límite. Por ejemplo, puedes solicitar un límite de 10, pero la respuesta puede tener solo 7 resultados. Cuando incluyas un offset, recuerda incluir la cantidad del límite en tu cálculo de offset para el siguiente lote. Si no se especifica un límite, deberás incrementar el offset por el límite predeterminado de 20 (p. ej., 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).

Agrega 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 necesites. 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

    # --- 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 (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",
        "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 uso de tarjeta de regalo o cargos de tarjeta virtual.
slug	String	Una versión del nombre del comercio apta para URL. El slug suele usarse en direcciones web o como referencia en la interfaz de usuario para facilitar su uso.
logoUrl	String	La URL de la imagen del logotipo del comercio. Normalmente es una imagen cuadrada (1:1) adecuada para mostrarse en listas de comercios y encabezados. Devuelve null si no está disponible.
faceplateUrl	String	La URL de la imagen rectangular de la placa/arte de la tarjeta 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.
offers	[Offer]	Un arreglo de objetos `Offer` que representan las promociones, descuentos o deals disponibles en el comercio. Cada objeto Offer proporciona detalles adicionales como el monto del descuento, la fecha de vencimiento y las 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 deal o descuento específico. Este es un campo obligatorio 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 canjeará la oferta. Para las 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.

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 tarjeta de regalo (GIFT_CARD_OFFER, EXCLUSIVE_RATE_OFFER):
- Campos clave incluyen offerRates, stockInfo, hasStockInfo, denominationsType, allowedPaymentMethods.
- Consulta la subpágina Ofertas de tarjeta 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

​Detalles específicos por tipo de oferta

Estructura básica de la consulta

Detalles de la respuesta

Detalles específicos por tipo de oferta