> ## 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 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 `giftCardOffer`s, `cardLinkedOffer`s 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:
>
> 1. Llama a getMerchants (offset = 0, limit = 20).
> 2. Agrega 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 necesites. 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
# --- 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 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.
}
]
}
]
}
}
```
## 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](/get-gift-card-offers) 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](/features/card-linked-offers) para una explicación detallada y ejemplos de consultas.