Ofertas Vinculadas a Tarjeta

Esta página detalla cómo recuperar y entender las Ofertas Vinculadas a Tarjeta (CLOs) usando la consulta getMerchants. Las CLOs se identifican por el valor CARD_LINKED_OFFER en el campo type y a menudo están ligadas al uso de la Tarjeta Virtual de Fluz — a veces canjeables exclusivamente a través de ella. Usan una estructura distinta, cloDetails, para su información de tasas y condiciones, que difiere significativamente de las ofertas estándar de Tarjetas de Regalo.

Requisitos previos: un token de acceso de usuario con el alcance LIST_OFFERS. Contrato completo de la consulta: Referencia de la API.

Para obtener solo CLOs, establece el argumento de entrada offerTypes en { cardLinkedOffer: true, giftCardOffer: false }.

Consulta detallada para Ofertas Vinculadas a Tarjeta

Esta consulta solicita campos específicamente relevantes para CLOs, enfocándose en el objeto cloDetails. Campos como offerRates y stockInfo, que son pertinentes a Tarjetas de Regalo, normalmente son null o están vacíos para CLOs y, a menudo, pueden omitirse de la consulta para CLOs.

query GetCLOMerchants(
  $name: String,
  $paginate: OffsetInput,
  $offerTypes: OfferTypesInput
) {
  getMerchants(
    name: $name,
    paginate: $paginate,
    offerTypes: $offerTypes
  ) {
    merchantId
    name
    slug
    offers {
      offerId
      type # Will be CARD_LINKED_OFFER
      hasStockInfo # Usually false for CLOs
      denominationsType # Often VARIABLE for CLOs
      # --- Offer Rates (Usually null/empty for CLOs) ---
      # offerRates { maxUserRewardValue } # Can query, but expect null
      # --- Stock Info (Usually null/empty for CLOs) ---
      # stockInfo { ... on StockInfoVariableType { __typename } } # Usually empty
      # --- CLO Details (Relevant for CLOs) ---
      cloDetails {
        currentRateType
        regularRate
        promoRate
        promoBaseRate
        promoMaxCap
        applyPromoBaseRateAfterCap
        minimumPurchaseAmount
        activePeriodStartDate
        activePeriodEndDate
        periods {
          id
          offerRateType
          periodType
          startDate
          endDate
          startTime
          endTime
          daysOfWeek
          daysOfMonth
        }
      }
    }
  }
}

# Example Variables to pass with the query:
# {
#   "paginate": { "limit": 20, "offset": 0 },
#   "offerTypes": { "cardLinkedOffer": true, "giftCardOffer": false }
# }

Respuesta de ejemplo

Aquí tienes un ejemplo de respuesta que obtendrás de la consulta getMerchants con solo Ofertas CLO:

JSON

{
  "data": {
    "getMerchants": [
      {
        "merchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd",
        "name": "REI",
        "slug": "REI",
        "offers": [
          {
            "offeringMerchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd",
            "offerId": "3edd79b7-aa46-4bd6-96de-b78e4f3a79e0",
            "type": "CARD_LINKED_OFFER",
            "hasStockInfo": false,
            "denominationsType": "VARIABLE",
            "stockInfo": [],
            "offerRates": null,
            "cloDetails": {
              "currentRateType": "PROMO",
              "regularRate": 22,
              "promoRate": 25,
              "promoBaseRate": 20,
              "promoMaxCap": 1523,
              "applyPromoBaseRateAfterCap": false,
              "minimumPurchaseAmount": null,
              "activePeriodStartDate": null,
              "activePeriodEndDate": null,
              "periods": [
                {
                  "id": "0cb1fde3-cfb5-4f31-b75f-eedf55d65ca7",
                  "offerRateType": "PROMO",
                  "periodType": "ALWAYS_AVAILABLE",
                  "startDate": null,
                  "endDate": null,
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                },
                {
                  "id": "21f57686-4139-4392-8eca-00cffad24fa1",
                  "offerRateType": "REGULAR",
                  "periodType": "ALWAYS_AVAILABLE",
                  "startDate": null,
                  "endDate": null,
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                }
              ]
            }
          },
          {
            "offeringMerchantId": "4b4195cb-ba98-49e6-8935-761458a76cdd",
            "offerId": "7ec04538-ad28-4d49-8181-f4ec108facc1",
            "type": "CARD_LINKED_OFFER",
            "hasStockInfo": false,
            "denominationsType": "VARIABLE",
            "stockInfo": [],
            "offerRates": null,
            "cloDetails": {
              "currentRateType": "PROMO",
              "regularRate": 4,
              "promoRate": 17,
              "promoBaseRate": 12,
              "promoMaxCap": 1999,
              "applyPromoBaseRateAfterCap": false,
              "minimumPurchaseAmount": null,
              "activePeriodStartDate": "2025-04-21",
              "activePeriodEndDate": "2025-04-27",
              "periods": [
                {
                  "id": "9f887399-7bd6-44ad-af04-3fccdafeb092",
                  "offerRateType": "PROMO",
                  "periodType": "MULTIPLE_DAYS",
                  "startDate": "2025-04-21",
                  "endDate": "2025-04-27",
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                },
                {
                  "id": "3769f838-f0a8-4971-9415-6bb15eae64be",
                  "offerRateType": "REGULAR",
                  "periodType": "ALWAYS_AVAILABLE",
                  "startDate": null,
                  "endDate": null,
                  "startTime": null,
                  "endTime": null,
                  "daysOfWeek": null,
                  "daysOfMonth": null
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

Campos específicos de las Ofertas Vinculadas a Tarjeta explicados

Cuando offer.type es CARD_LINKED_OFFER, la fuente principal de información es el objeto cloDetails dentro de Offer.

type (String!): Siempre será CARD_LINKED_OFFER.
cloDetails (CloDetails): Este objeto complejo contiene todas las reglas y condiciones específicas de tasas, promociones y tiempos para la Oferta Vinculada a Tarjeta. Devuelve null para tipos que no son CLO. Consulta las tablas a continuación para un desglose de sus campos.
offerRates: Normalmente null o vacío para CLOs. La información de tasas está contenida dentro de cloDetails.
stockInfo: Normalmente vacío para CLOs ya que usualmente están vinculadas al uso de la tarjeta en lugar de stock predefinido.
hasStockInfo: Usualmente false para CLOs.
denominationsType: A menudo VARIABLE para CLOs, reflejando que la oferta aplica a un valor de transacción en lugar de un monto fijo de tarjeta de regalo.

Entendiendo el Objeto `CloDetails`

Este objeto proporciona la estructura específica de tasas para las Ofertas Vinculadas a Tarjeta.

Field Name	Type	Description
`currentRateType`	CloRateTypeEnum!	Indica si la tasa `REGULAR` o `PROMO` está actualmente activa, determinada evaluando todos los `periods` contra la hora actual. (`REGULAR`, `PROMO`)
`regularRate`	Float	La tasa de recompensa estándar aplicada cuando no hay una promoción activa.
`promoRate`	Float	La tasa de recompensa promocional aplicada cuando un periodo `PROMO` está activo y el monto de la compra está por debajo o igual a `promoMaxCap` (si aplica).
`promoBaseRate`	Float	La tasa de recompensa aplicada durante un periodo `PROMO` después de que se ha excedido `promoMaxCap`, si`applyPromoBaseRateAfterCap` es true.
`promoMaxCap`	Float	El monto máximo de compra (valor en moneda) hasta el cual aplica `promoRate` durante un periodo `PROMO`. Las compras por encima de este monto pueden ganar `promoBaseRate` o la `regularRate`, dependiendo de banderas.
`applyPromoBaseRateAfterCap`	Boolean	Si es `true`, `promoBaseRate` se aplica a la porción del monto de compra que excede `promoMaxCap` durante un periodo `PROMO` activo. Si es `false`, los montos por encima del tope podrían no ganar recompensa o ganar la `regularRate`.
`minimumPurchaseAmount`	Float	El valor mínimo de transacción requerido para calificar para cualquier recompensa de esta CLO, si se especifica.
`activePeriodStartDate`	String	La fecha de inicio (YYYY-MM-DD) del periodo de oferta actualmente activo (podría ser regular o promocional), si el periodo activo tiene fechas de inicio/fin definidas. `null` si siempre está activa o basada en otros criterios.
`activePeriodEndDate`	String	La fecha de fin (YYYY-MM-DD) del periodo de oferta actualmente activo, si aplica. `null` si siempre está activa o es de final abierto.
`periods`	[CloPeriod!]!	Una lista de todos los periodos de tiempo definidos asociados con esta oferta. El sistema evalúa estos periodos para determinar el `currentRateType`. Consulta la tabla de `CloPeriod` a continuación.

Entendiendo el Objeto `CloPeriod` (dentro de `CloDetails.periods`)

Cada objeto en el arreglo periods define una ventana de tiempo específica y el tipo de tasa (REGULAR o PROMO) asociado a ella. La combinación de estos periodos determina la disponibilidad de la oferta y la tasa activa.

Field Name	Type	Description
`id`	UUID!	Identificador único para esta definición específica de periodo.
`offerRateType`	CloRateTypeEnum!	Indica si este periodo corresponde a la estructura de tasa `REGULAR` o `PROMO` definida en el `CloDetails` padre.
`periodType`	String	Describe la naturaleza del tiempo del periodo (por ejemplo, `ALWAYS_AVAILABLE`, `MULTIPLE_DAYS`, `SPECIFIC_DAY`, `RECURRING_WEEKLY`).
`startDate`	String	Fecha de inicio (YYYY-MM-DD) cuando esta regla de periodo se vuelve potencialmente activa.
`endDate`	String	Fecha de fin (YYYY-MM-DD) cuando esta regla de periodo deja de estar activa.
`startTime`	String	Hora de inicio (por ejemplo, “HH:MM” en UTC o una zona horaria definida) para aplicabilidad diaria, a menudo usada con `daysOfWeek`.
`endTime`	String	Hora de fin (por ejemplo, “HH:MM” en UTC o una zona horaria definida) para aplicabilidad diaria.
`daysOfWeek`	[String]	Arreglo de días (por ejemplo, [“MONDAY”, “FRIDAY”]) cuando esta regla de periodo está activa. Usado para periodos recurrentes semanales.
`daysOfMonth`	[String]	Arreglo de días específicos del mes (por ejemplo, [“1”, “15”]) cuando esta regla de periodo está activa. Usado para periodos recurrentes mensuales.

Próximos pasos

Crear una tarjeta virtual

Emite la tarjeta que estas ofertas recompensan: las ganancias de CLO aplican a su gasto.

Editar una tarjeta virtual

Ajusta límites, financiamiento y configuraciones de ciclo de vida en una tarjeta existente.

​Consulta detallada para Ofertas Vinculadas a Tarjeta

​Respuesta de ejemplo

​Campos específicos de las Ofertas Vinculadas a Tarjeta explicados

​Entendiendo el Objeto CloDetails

​Entendiendo el Objeto CloPeriod (dentro de CloDetails.periods)

​Próximos pasos

Crear una tarjeta virtual

Editar una tarjeta virtual

Consulta detallada para Ofertas Vinculadas a Tarjeta

Respuesta de ejemplo

Campos específicos de las Ofertas Vinculadas a Tarjeta explicados

Entendiendo el Objeto `CloDetails`

Entendiendo el Objeto `CloPeriod` (dentro de `CloDetails.periods`)

Próximos pasos