Tu primera compra de tarjeta de regalo

Este Quickstart te lleva desde una cuenta nueva de Fluz hasta una compra completada en staging. Registrarás una app, acuñarás un token de acceso con alcance, luego depositarás fondos, explorarás el catálogo de comercios, comprarás una tarjeta de regalo y revelarás sus detalles de canje — todo en el sandbox, donde no se mueve dinero real.

Requisitos previos

Una cuenta de Fluz — crearás credenciales de API de staging y acuñarás un token de acceso en los Pasos 1–2 a continuación.
Las solicitudes van al endpoint GraphQL del sandbox. Nada aquí carga una tarjeta real — ver Entorno de Staging vs. Producción.
Cada mutación necesita un idempotencyKey único (un UUID generado por el cliente) para que una solicitud solo se procese una vez — ver Idempotencia.

Antes de comenzar

Cada llamada es una solicitud POST a un único endpoint de GraphQL. Acuñar tu token (Paso 2) se autentica con tu API Key; todas las demás llamadas se autentican con tu token portador:

POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>
Content-Type: application/json

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query getWallet { getWallet { bankCards { bankCardId lastFourDigits } } }"
  }'

Tu cuenta de sandbox viene con una tarjeta bancaria de prueba preagregada, para que puedas ejecutar todo este flujo de inmediato. Agrega más tarjetas o cuentas bancarias de prueba desde la página de Cuentas de Sandbox usando valores de la lista Tarjetas bancarias de prueba.

El flujo completo

Regístrate y registra una app

Crea una cuenta de Fluz en fluz.app, luego abre la Consola de Desarrolladores y crea una nueva aplicación de Staging. Cuando aparezcan las credenciales, copia tu API Key, User ID y Account ID.Guía completa: Prepara tus cuentas.

Intercambia credenciales por un token de acceso

Acuña un token de acceso de usuario de corta duración y con alcance usando tu API Key. Esta llamada va al mismo endpoint de GraphQL, autorizada con Authorization: Basic <YOUR_API_KEY>; todas las siguientes llamadas usan el token retornado como credencial Bearer.

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Basic <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ($userId: UUID!, $accountId: UUID!, $scopes: [ScopeType!]!) { generateUserAccessToken(userId: $userId, accountId: $accountId, scopes: $scopes) { token scopes } }",
    "variables": {
      "userId": "<YOUR_USER_ID>",
      "accountId": "<YOUR_ACCOUNT_ID>",
      "scopes": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }'

{
  "data": {
    "generateUserAccessToken": {
      "token": "eyJhbGciOi...",
      "scopes": ["LIST_OFFERS", "LIST_PAYMENT", "MANAGE_PAYMENT", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }
}

Guarda el token devuelto y envíalo como Authorization: Bearer <token> en cada solicitud a continuación. Los tokens son de corta duración — acuñalos del lado del servidor y acuña uno nuevo con la misma mutación cuando uno expire (ver Actualizar un token de acceso expirado). Detalles completos: Credenciales de API.

Los alcances controlan lo que el token puede hacer — incluye solo lo que tu flujo necesita: MANAGE_PAYMENT para agregar fuentes de fondos y depositar, LIST_OFFERS para explorar el catálogo, y PURCHASE_GIFTCARD / REVEAL_GIFTCARD para comprar y revelar.

Nunca expongas tu API Key en un navegador o cliente móvil. Acuña tokens del lado del servidor y reenvía solo el token.

Deposita fondos a tu balance de Fluz

Precargar un balance de Fluz generalmente hace que las compras de tarjetas de regalo sean más rápidas y puede evitar ciertos controles de velocidad. Puedes depositar de dos maneras:

Manualmente, vía el sitio web de Fluz en sandbox.
Programáticamente, vía la mutación depositCashBalance (mostrada a continuación).

Primero, obtén un ID de método de pago (getWallet)

Para depositar vía API necesitas el ID de una fuente de fondos (p. ej., un bankCardId). Ejecuta getWallet y guarda el ID que quieras usar.

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query getWallet { getWallet { bankCards { bankCardId lastFourDigits } bankAccounts { bankAccountId } } }"
  }'

Toma el bankCardId o bankAccountId de la respuesta. Administrar fuentes de fondos vía la API requiere el alcance MANAGE_PAYMENT. Más detalle: Ver fuentes de fondos.

Realiza el depósito

Usa la mutación depositCashBalance. Recibe un objeto DepositCashBalanceInput.

mutation depositCashBalance($input: DepositCashBalanceInput!) {
  depositCashBalance(input: $input) {
    cashBalanceDeposits {
      cashBalanceDepositId
      depositDisplayId
      depositAmount
      status
      cashBalanceDepositType
    }
    balances {
      cashBalance { availableBalance totalBalance pendingBalance }
      giftCardCashBalance { availableBalance totalBalance pendingBalance }
    }
  }
}

{
  "input": {
    "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "amount": 100.00,
    "depositType": "CASH_BALANCE",
    "bankCardId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19"
  }
}

Campos de entrada

string

requerido

Un UUID único generado por el cliente que garantiza que el depósito se procese solo una vez.

Float

requerido

El monto a depositar.

CashBalanceDepositType

Balance de destino. Uno de CASH_BALANCE, GIFT_CARD_BALANCE o RESERVE_BALANCE.

UUID

De dónde proviene el dinero — proporciona una de bankAccountId, bankCardId o paypalVaultId.

Int

Solo para GIFT_CARD_BALANCE. Un MCC de cuatro dígitos que clasifica el negocio. Usa getMccList para obtener valores válidos.

UUID

Cuando se selecciona CASH_BALANCE, la cuenta de gasto específica a la cual depositar.

Respuesta de ejemplo

{
  "data": {
    "depositCashBalance": {
      "cashBalanceDeposits": [
        {
          "cashBalanceDepositId": "5f5c5b5f-4c4b-4e4e-9e9e-4f4f4f4f4f4f",
          "depositDisplayId": "102370",
          "depositAmount": "100.00",
          "status": "COMPLETED",
          "cashBalanceDepositType": "CASH_BALANCE"
        }
      ],
      "balances": {
        "cashBalance": {
          "availableBalance": "100.00",
          "totalBalance": "100.00",
          "pendingBalance": "0.00"
        },
        "giftCardCashBalance": {
          "availableBalance": "0.00",
          "totalBalance": "0.00",
          "pendingBalance": "0.00"
        }
      }
    }
  }
}

Los depósitos pueden liquidarse al instante o dentro de 2–5 días hábiles dependiendo de la fuente de fondos y el tipo de liquidación. El objeto balances en la respuesta refleja tu balance disponible actual. Consulta Revisar balance de cuenta para volver a consultarlo en cualquier momento.

Explora comercios y elige una oferta

Con un balance listo, obtiene el catálogo de comercios disponibles y sus ofertas de cashback usando getMerchants.

query GetMerchantCatalog(
  $paginate: OffsetInput
  $offerTypes: OfferTypesInput
  $filterBy: FilterByInput
) {
  getMerchants(paginate: $paginate, offerTypes: $offerTypes, filterBy: $filterBy) {
    merchantId
    name
    slug
    logoUrl
    faceplateUrl
    offers {
      offeringMerchantId
      offerId
      type
      deliveryFormat
      barcodeType
      offerRates {
        maxUserRewardValue
        cashbackVoucherRewardValue
        boostRewardValue
        denominations
        allowedPaymentMethods
      }
    }
  }
}

{
  "paginate": { "limit": 20, "offset": 0 },
  "offerTypes": { "giftCardOffer": true, "cardLinkedOffer": false }
}

El catálogo se ordena por porcentaje de cashback de forma predeterminada, por lo que las ofertas más altas aparecen primero.

Argumentos útiles

String

Filtra comercios por nombre.

OffsetInput

{ limit, offset }. El limit predeterminado y máximo es 20.

OfferTypesInput

Indicadores booleanos de qué tipos de oferta devolver, p. ej. { giftCardOffer: true, cardLinkedOffer: false }.

FilterByInput

Filtra ofertas dentro de cada comercio, p. ej. por deliveryFormat (URL, CODES, PIN_AS_CODE, PIN_WITH_URL).

Paginación: la respuesta puede devolver menos resultados que tu limit. Para extraer el catálogo completo, sigue incrementando offset por tu limit y detente cuando la API devuelva un arreglo vacío ([]). El catálogo sin filtrar es grande — consúltalo como máximo una vez al día y usa name u offerTypes para búsquedas dirigidas.

Opcional: obtén la mejor oferta única para un comercio (getOfferQuote)

Si ya conoces el comercio y el monto, getOfferQuote devuelve directamente la mejor oferta disponible — incluyendo información de stock en vivo.

query getOfferQuote($input: GetOfferQuoteInput!) {
  getOfferQuote(input: $input) {
    offeringMerchantId
    offerId
    type
    hasStockInfo
    denominationsType
    termsAndConditions
    offerRates {
      maxUserRewardValue
      denominations
      allowedPaymentMethods
    }
    stockInfo {
      ... on StockInfoVariableType {
        __typename
        description
        maxDenomination
        minDenomination
      }
      ... on StockInfoFixedType {
        __typename
        denomination
        availableStock
      }
    }
  }
}

{
  "input": {
    "merchantSlug": "starbucks",
    "denomination": 50.00,
    "paymentMethod": "FLUZPAY"
  }
}

merchantSlug y denomination son obligatorios. paymentMethod predetermina a FLUZPAY (tu balance de Fluz) y también acepta BANK_CARD, BANK_ACCOUNT, PAYPAL, APPLE_PAY y GOOGLE_PAY.

Las tasas de cashback cambian regularmente. Confirma siempre la tasa actual antes de comprar.

Compra una tarjeta de regalo

Usa la mutación purchaseGiftCard. Puedes identificar qué comprar de dos maneras:

Opción A — Slug del comercio (recomendado)
Opción B — ID de oferta específica

Pasa un merchantSlug y Fluz aplicará automáticamente la mejor oferta disponible para ese comercio.

mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    giftCard {
      giftCardId
      status
      termsAndConditions
    }
  }
}

{
  "input": {
    "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "merchantSlug": "starbucks",
    "amount": 50.00,
    "balanceAmount": 50.00
  }
}

Pasa un offerId que seleccionaste del catálogo para comprar esa oferta exacta.

mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    giftCard {
      giftCardId
      status
      termsAndConditions
    }
  }
}

{
  "input": {
    "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "offerId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
    "amount": 50.00,
    "balanceAmount": 50.00
  }
}

Campos de entrada

string

requerido

Un UUID único generado por el cliente para que la compra se procese solo una vez.

UUID / String

requerido

Proporciona uno. merchantSlug selecciona automáticamente la mejor tasa; offerId apunta a una oferta específica.

Float

requerido

El monto de la tarjeta de regalo a comprar.

UUID / Float

Cómo pagar. Usa balanceAmount (balance de Fluz), bankAccountId, bankCardId o paypalVaultId. Puedes combinar tu balance de Fluz con otra fuente.

Boolean

predeterminado:"true"

Recurre a tu balance de Fluz si otro método de pago falla. Configura en false para deshabilitar ese respaldo.

Float

Tasa mínima de recompensa a aceptar al comprar mediante merchantSlug.

UUID

Fuerza una tasa exclusiva específica. Se encuentra en getMerchants para ofertas de tipo EXCLUSIVE_RATE_OFFER.

UUID

La cuenta de gasto (balance en efectivo) a cargar.

String / String / UUID

Metadatos opcionales de gasto. memo máximo 255 caracteres; las categorías se crean al primer uso. Ver Agregar detalles de gasto.

Respuesta de ejemplo

{
  "data": {
    "purchaseGiftCard": {
      "purchaseDisplayId": "1019688",
      "purchaseAmount": 50.00,
      "giftCard": {
        "giftCardId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
        "status": "ACTIVE",
        "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
      }
    }
  }
}

Conserva el giftCardId de la respuesta — lo usarás para revelar la tarjeta en el siguiente paso. Si una compra falla, revisa Códigos de error de tarjetas de regalo.

Revela los detalles de la tarjeta de regalo

Finalmente, recupera los detalles canjeables (código, PIN y/o URL).

¿No tienes el giftCardId? Lista tus tarjetas primero (getGiftCards)

Omite esto si acabas de capturar un giftCardId en el Paso 3. De lo contrario, lista tus tarjetas de regalo:

query GetGiftCards {
  getGiftCards(paginate: { limit: 20, offset: 0 }) {
    giftCardId
    status
    createdAt
    deliveryFormat
    termsAndConditions
    merchant { merchantId name slug }
  }
}

Puedes filtrar con status y userCashBalanceId, y paginar con paginate.

Revela los detalles de canje

Llama a revealGiftCardByGiftCardId con el giftCardId.

mutation RevealGiftCard($giftCardId: UUID!) {
  revealGiftCardByGiftCardId(giftCardId: $giftCardId) {
    code
    pin
    url
    termsAndConditions
  }
}

{
  "giftCardId": "7c57c381-4b19-49e4-bbb0-404a45166ee4"
}

Respuesta de ejemplo

{
  "data": {
    "revealGiftCardByGiftCardId": {
      "code": "9877890000000000",
      "pin": "2014",
      "url": null,
      "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
    }
  }
}

Los campos de canje varían por comercio. Algunas tarjetas devuelven un code alfanumérico sin pin; otras devuelven solo una url. Siempre representa según el deliveryFormat devuelto por getGiftCards (no getMerchants) — la oferta activa de un comercio puede cambiar después de la compra, y getGiftCards refleja el formato bajo el cual la tarjeta realmente fue comprada.

¿Los detalles no se devuelven de inmediato? Haz polling a revealGiftCardByGiftCardId con backoff exponencial: comienza en 300ms, luego duplica (300 → 600 → 1200 → 2400ms…) hasta un retraso máximo de 180000ms (3 minutos). Detente tan pronto como regresen los detalles. Esto equilibra la capacidad de respuesta con la carga y evita timeouts innecesarios.

Listo 🎉

Has ejecutado una transacción completa — fondeaste un balance, exploraste ofertas, compraste una tarjeta de regalo y la revelaste. Desde aquí, explora el resto de la API:

Tarjetas virtuales

Emite y administra tarjetas virtuales aceptadas por la red.

Billeteras y transferencias

Abre cuentas de gasto y mueve fondos entre ellas.

Actividad de transacciones

Extrae, filtra y anota el historial de transacciones.

Widgets embebidos

Inserta flujos de Fluz directamente en tu propia interfaz.

¿Quieres saber más? Contáctanos en support@fluz.app para hablar con nuestros expertos o solicitar una demo.

Comienza

Panel de Fluz

Guías rápidas

Tu primera compra de tarjeta de regalo

Antes de comenzar

El flujo completo

Realiza el depósito

Campos de entrada

Argumentos útiles

Campos de entrada

Revela los detalles de canje

Listo 🎉

Tarjetas virtuales

Billeteras y transferencias

Actividad de transacciones

Widgets embebidos

​Antes de comenzar

​El flujo completo

​Realiza el depósito

​Campos de entrada

​Argumentos útiles

​Campos de entrada

​Revela los detalles de canje

​Listo 🎉

Tarjetas virtuales

Billeteras y transferencias

Actividad de transacciones

Widgets embebidos

Antes de comenzar

El flujo completo

Realiza el depósito

Campos de entrada

Argumentos útiles

Campos de entrada

Revela los detalles de canje

Listo 🎉