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

# 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 `giftCardOffer`s, `cardLinkedOffer`s 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`](https://docs.fluz.app/api-reference/queries/get-merchant-categories). 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:
>
> 1. Llama a getMerchants (offset = 0, limit = 20).
> 2. Anexa los comercios devueltos a tu lista local.
> 3. Incrementa el offset por tu límite (offset += 20).
> 4. Repite la solicitud.
> 5. 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:

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

    # --- 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 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",
        "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`](https://docs.fluz.app/api-reference/queries/get-merchant-categories) una vez para obtener la lista, luego pasa un `categoryId` a `getMerchants` para mostrar una categoría a la vez.

```graphql theme={null}
query GetMerchantCategories {
  getMerchantCategories {
    categoryId
    name
  }
}
```

```graphql theme={null}
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](https://docs.fluz.app/get-gift-card-offers.md) 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](https://docs.fluz.app/features/card-linked-offers.md) para una explicación detallada y ejemplos de consultas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.