Descripción general de Open Loop Cards

Requisitos previos: un token Bearer de acceso con el alcance CREATE_SHARE_LINK. La autenticación básica se rechaza. Contacta a tu representante de ventas para habilitar el acceso. Consulta Autenticación.

Qué significan “hosted” / “open-loop”. Un enlace hosted apunta a una página de activación alojada por Fluz. Open-loop significa que la tarjeta virtual resultante es una tarjeta de red (estilo Visa/Mastercard) que se puede gastar en muchos comercios, sujeta a las reglas de tu programa — no una tarjeta de regalo de marca única de circuito cerrado.

Cómo funciona

Tú generas enlaces

Llama a generateVCShareLinks con la oferta, el límite de la tarjeta, la cantidad, la fuente de fondos y un método de entrega. Cada enlace representa una tarjeta con su propio límite, financiada desde la cuenta de gasto que especifiques.

Fluz crea una solicitud de compartición por enlace

Cada enlace se asigna a una solicitud de compartición (PENDING) y a una URL alojada.

El enlace se entrega

Con GENERATE_URL recibes las URL para distribuirlas tú mismo. Con EMAIL o PHONE_NUMBER, Fluz entrega un enlace a cada destinatario por ti.

El destinatario activa y reclama la tarjeta

El destinatario abre el enlace y verifica su número de teléfono con un código de un solo uso — sin descargar app ni contraseña. El límite de la tarjeta se descuenta de tu cuenta de gasto en el momento de la reclamación, no cuando se genera el enlace. La tarjeta no se muestra automáticamente al reclamarla; al revelarla se le pide al destinatario que introduzca su PIN o que cree uno si aún no lo ha configurado. Consulta Experiencia del destinatario para el recorrido completo.

El destinatario se convierte en usuario autorizado solo de ese objeto de tarjeta virtual — no obtiene acceso a tu cuenta, saldos ni a ninguna otra tarjeta. Diagrama del flujo de envío de tarjetas

Disponibilidad y alcance

Capacidad	Estado
Tarjetas virtuales de una sola carga	✅ Compatible
Tarjetas virtuales de un solo uso	✅ Compatible
Tarjetas recargables	❌ No compatible
Generar enlaces vía API	✅ Compatible
Generar enlaces vía Importación CSV	❌ Próximamente
Enlaces alojados de tarjeta de regalo	❌ Fuera de alcance (solo tarjetas virtuales)

El tipo de objeto de enlace de compartición de tarjeta es VIRTUAL_CARD y el tipo de tarjeta es SINGLE_LOAD.

Tarjetas de regalo: A pesar del encuadre “tarjetas virtuales y tarjetas de regalo” de la iniciativa más amplia, hoy no existe un flujo alojado para reclamar tarjetas de regalo. Los saldos de tarjetas de regalo aparecen en esta área solo como una posible fuente de fondos para tarjetas virtuales alojadas (planificado, aún no habilitado). Documenta y construye únicamente para tarjetas virtuales.

Referencia de operaciones

Hay tres operaciones públicas, todas controladas por el alcance CREATE_SHARE_LINK:

Operación	Tipo	Propósito
`generateVCShareLinks`	Mutation	Crear uno o más enlaces alojados de tarjetas virtuales
`getVCShareLinks`	Query	Listar/inspeccionar enlaces generados previamente
`deactivateVCShareLinks`	Mutation	Desactivar (expirar) enlaces que generaste

Todas las operaciones de Send Cards están en la API GraphQL de Fluz en POST https://<your-fluz-api-host>/api/v1/graphql con un encabezado Authorization: Bearer <access_token>. El token debe incluir el alcance CREATE_SHARE_LINK — sin él, toda operación devuelve “Missing permissions! Please contact your sales rep to get access to generate VC share links.”

generateVCShareLinks

Crea quantity solicitudes de compartición y devuelve un enlace alojado por cada solicitud.

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}

Campos de entrada

Campo	Tipo	Requerido	Descripción
`cardLimit`	`Int!`	Sí	Límite de gasto (y monto de carga) para cada tarjeta, en unidades monetarias enteras. Debe ser un número entero ≥ al mínimo del programa.
`offerId`	`String!`	Sí	UUID v4 de la oferta del comercio a la que está vinculada la tarjeta. La oferta debe estar activa y su comercio debe ser compartible.
`quantity`	`Int!`	Sí	Número de enlaces a generar. Se crea una URL alojada distinta por unidad.
`shareMethod`	`ShareMethodType!`	Sí	Cómo se identifican los destinatarios y cómo se entregan los enlaces: `GENERATE_URL`, `EMAIL`, `PHONE_NUMBER`, `EXISTING_USER` o `REGISTER_USER`.
`userCashBalanceId`	`UUID`	Sí*	La cuenta de gasto utilizada para financiar las tarjetas. Marcado como opcional en el esquema, pero requerido en la práctica — omitirlo falla la validación.
`daysUntilExpiration`	`Int`	No	Días hasta que el enlace expira. Mínimo 1. Si se omite, usa el valor predeterminado del programa (30 días). Esta fecha también se convierte en la fecha de bloqueo/congelación de la tarjeta — consulta Vencimiento y congelación.
`recipientListEmail`	`[String]`	Condicional	Requerido y no vacío cuando `shareMethod = EMAIL`. Su longitud debe ser igual a `quantity`. Debe estar vacío en caso contrario.
`recipientListPhone`	`[String]`	Condicional	Requerido y no vacío cuando `shareMethod = PHONE_NUMBER`. Su longitud debe ser igual a `quantity`. Debe estar vacío en caso contrario.
`recipientUserIds`	`[UUID]`	Condicional	IDs de usuario de Fluz conocidos para vincular como destinatarios cuando `shareMethod = EXISTING_USER`. Su longitud debe ser igual a `quantity`. Mutuamente excluyente con `recipientRegistrations`.
`recipientRegistrations`	`[ShareLinkRecipientRegistrationInput]`	Condicional	Cargas útiles de pre-registro en línea cuando `shareMethod = REGISTER_USER` — Fluz crea o reutiliza un usuario provisional (sin asiento) por entrada antes de generar enlaces. Su longitud debe ser igual a `quantity`. Mutuamente excluyente con `recipientUserIds`.
`usePrepaymentBalance`	`Boolean`	No	Configura si se usará tu saldo de Prepago como fuente de fondos adicional. El valor predeterminado es false. Más información sobre cómo se usa: Cómo funciona la financiación.
`useRewardsBalance`	`Boolean`	No	Configura si se usará tu Fluz Rewards Balance como fuente de fondos adicional. El valor predeterminado es false. Más información sobre cómo se usa: Cómo funciona la financiación.

Fuente de fondos. userCashBalanceId (una cuenta de gasto perteneciente a tu cuenta emisora) es la fuente de fondos principal y requerida. Opcionalmente configura usePrepaymentBalance y/o useRewardsBalance en true para permitir que Fluz recurra a tu saldo de prepago o recompensas si la cuenta de gasto no cubre el monto total en el momento de la reclamación. Las cuentas bancarias y tarjetas bancarias no son compatibles como fuentes de fondos.

Identificación del destinatario y entrega (`shareMethod`)

Valor	Comportamiento	Campo del destinatario	Tarjeta creada
`GENERATE_URL`	Fluz devuelve las URL alojadas en la respuesta. Tú mismo las distribuyes.	Ambas listas deben estar vacías/omitidas.	Al reclamar
`EMAIL`	Fluz envía por correo un enlace a cada destinatario.	`recipientListEmail` requerido; la longitud debe ser igual a `quantity`.	Al reclamar
`PHONE_NUMBER`	Fluz envía por SMS un enlace a cada destinatario.	`recipientListPhone` requerido; la longitud debe ser igual a `quantity`.	Al reclamar
`EXISTING_USER`	El enlace se vincula a un usuario conocido de Fluz desde el inicio; solo ese usuario puede reclamarlo. Se entrega mediante el(los) canal(es) de contacto ya registrados para ese usuario.	`recipientUserIds` requerido; la longitud debe ser igual a `quantity`.	Inmediatamente, en el momento de la generación
`REGISTER_USER`	Fluz crea o reutiliza un usuario provisional por entrada y luego vincula el enlace a ese usuario, igual que `EXISTING_USER`.	`recipientRegistrations` requerido; la longitud debe ser igual a `quantity`.	Inmediatamente, en el momento de la generación

EXISTING_USER y REGISTER_USER crean la tarjeta virtual como parte de la llamada a generateVCShareLinks, en lugar de aplazar la creación de la tarjeta al momento de la reclamación. Consulta Registrar y Enviar para el flujo completo de EXISTING_USER, incluido cómo registrar primero a un destinatario con registerUser.

Reglas de validación

cardLimit debe ser un número entero y al menos el mínimo del programa.
offerId debe ser un UUID v4 válido para una oferta activa cuyo comercio sea compartible.
quantity debe ser un número entero.
El campo de destinatario que coincide con shareMethod (recipientListEmail, recipientListPhone, recipientUserIds o recipientRegistrations) debe tener una longitud igual a quantity. Las discrepancias devuelven un error claro y no crean registros.
recipientUserIds y recipientRegistrations son mutuamente excluyentes entre sí y con los campos de listas de entrega.
Cada ID en recipientUserIds debe ser un usuario de Fluz válido y existente.
userCashBalanceId es requerido y debe ser un UUID v4 válido perteneciente a la cuenta del emisor. usePrepaymentBalance y useRewardsBalance son fuentes de respaldo opcionales y pueden habilitarse junto con él.
Tipos de tarjeta inválidos o entradas mal formadas devuelven errores claros y no crean registros.

Ejemplos

  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 3,
      "shareMethod": "GENERATE_URL",
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }

  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 2,
      "shareMethod": "EMAIL",
      "recipientListEmail": ["recipient1@example.com", "recipient2@example.com"],
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }

  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 2,
      "shareMethod": "PHONE_NUMBER",
      "recipientListPhone": ["+12125550101", "+12125550102"],
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }

  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 1,
      "shareMethod": "EXISTING_USER",
      "recipientUserIds": ["f1320ac4-52dc-4c67-9e80-24e506b18450"],
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }

Para EXISTING_USER, registra primero al destinatario (o usa directamente el ID de un usuario existente) — consulta Registrar y Enviar para el recorrido completo, incluida la llamada registerUser y el manejo de la respuesta.

Respuesta

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1",
        "https://fluz.app/virtual-prepaid-card/9b2d...77",
        "https://fluz.app/virtual-prepaid-card/0c41...e3"
      ]
    }
  }
}

shareLinks es un arreglo de URL alojadas, una por quantity, cada una con la forma https://fluz.app/virtual-prepaid-card/{share_request_id}.

La respuesta devuelve solo las URL. Para recuperar el ID del lote y los IDs visibles de los enlaces que acabas de crear (necesarios para listar y desactivar), usa getVCShareLinks filtrado por estado.

getVCShareLinks

Lista los enlaces de compartición generados previamente para que puedas inspeccionar el estado, los destinatarios, el vencimiento y la tarjeta emitida.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    senderAppId
    shareRequestBatchId
    shareRequestDisplayId
    shareObjectStatus
    recipientPhone
    recipientEmail
    linkExpirationDate
    virtualCardId
    linkUrl
    shareRequestDetails {
      cardLimit
      offerId
      daysUntilExpiration
      quantity
      shareMethod
      recipientListEmail
      recipientListPhone
      userCashBalanceId
    }
  }
}

Campos de entrada

Campo	Tipo	Descripción
`shareObjectStatuses`	`[ShareObjectStatus]`	Filtrar por estado: `PENDING`, `ISSUED`, `USED`, `EXPIRED`.
`shareRequestBatchIds`	`[String]`	Devolver solo enlaces en estos lotes.
`shareRequestDisplayIds`	`[String]`	Devolver solo los enlaces con estos IDs visibles.

Flujo recomendado. En la primera llamada, filtra solo por shareObjectStatuses. La respuesta te da shareRequestBatchId y shareRequestDisplayId; úsalos para filtrar con precisión en llamadas posteriores (y para desactivar).

Campos de respuesta (`GeneratedShareLink`)

Campo	Tipo	Descripción
`senderAppId`	`String`	La app/aplicación de desarrollador que generó el enlace.
`shareRequestBatchId`	`String`	Identificador de lote compartido por todos los enlaces generados en una misma llamada.
`shareRequestDisplayId`	`String`	Identificador por enlace, legible para humanos.
`shareObjectStatus`	`ShareObjectStatus`	`PENDING`, `ISSUED`, `USED` o `EXPIRED`.
`recipientEmail`	`String`	Correo del destinatario, si se entregó por email.
`recipientPhone`	`String`	Teléfono del destinatario, si se entregó por SMS.
`linkExpirationDate`	`DateTime`	Cuándo expira el enlace / se congela la tarjeta.
`virtualCardId`	`String`	El ID de la tarjeta virtual emitida, una vez reclamada.
`linkUrl`	`String`	La URL alojada del enlace.
`shareRequestDetails`	`ShareRequestDetails`	La configuración original (límite de tarjeta, oferta, cantidad, entrega, financiación).

Ejemplos

  { "input": { "shareObjectStatuses": ["PENDING", "ISSUED"] } }

  { "input": { "shareRequestBatchIds": ["ABC123", "XYZ789"] } }

  { "input": { "shareRequestDisplayIds": ["SR-000001", "SR-000002"] } }

deactivateVCShareLinks

Desactiva (expira) enlaces que generaste — por ejemplo, si un lote se envió por error o necesitas revocar enlaces no reclamados. Desactivar un enlace lo establece en EXPIRED; un enlace no reclamado ya no se puede reclamar.

mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
  deactivateVCShareLinks(input: $input)
}

Campos de entrada

Campo	Tipo	Descripción
`shareRequestBatchIds`	`[String]`	Desactivar cada enlace en estos lotes.
`shareRequestDisplayIds`	`[String]`	Desactivar solo los enlaces con estos IDs visibles.

Obtén los IDs de lote desde getVCShareLinks.

{ "input": { "shareRequestBatchIds": ["ABC123"] } }

Devuelve una cadena de confirmación legible, p. ej., "3 share requests successfully deactivated!".

Si un destinatario ya ha reclamado un enlace (estado ISSUED/USED), desactivar el enlace no recupera la tarjeta emitida. Para detener el gasto en una tarjeta ya emitida, usa los controles relevantes del ciclo de vida/congelación de la tarjeta.

Vencimiento y congelación

La fecha de vencimiento del enlace cumple doble función:

Vencimiento del enlace — después de esta fecha, un enlace no reclamado ya no se puede reclamar.
Fecha de bloqueo/congelación de la tarjeta — para una tarjeta emitida, esta es la fecha de bloqueo (fin de ese día). Después de ella, la tarjeta se congela y no se puede gastar.
La expiración de la tarjeta se alinea con el fin del mes de la fecha de congelación (p. ej., una fecha de congelación del 15/6/2026 produce una expiración de tarjeta del 30/6/2026).

Configura la ventana con daysUntilExpiration en el momento de la generación. Si se omite, se usa el valor predeterminado del programa (30 días). Esta fecha se muestra al destinatario (normalmente como una fecha de “Válida hasta”) — consulta Experiencia del destinatario.

Referencia de estados y errores

Estados del objeto de compartición

Estado	Significado
`PENDING`	Enlace generado, aún no reclamado.
`ISSUED`	El destinatario reclamó el enlace; se emitió una tarjeta virtual.
`USED`	La tarjeta emitida ha sido utilizada.
`EXPIRED`	El enlace venció o fue desactivado; ya no se puede reclamar.

Para los estados que ve un destinatario cuando un enlace está vencido, revocado o ya reclamado, consulta Errores de enlace visibles para el destinatario.

Errores comunes de la API

Causa	Resultado
Token Bearer faltante/inválido o alcance `CREATE_SHARE_LINK` faltante	Solicitud rechazada (no autorizada).
Longitud del campo de destinatario (`recipientListEmail`, `recipientListPhone`, `recipientUserIds` o `recipientRegistrations`) ≠ `quantity`	Error de validación claro; no se crean registros.
`recipientUserIds` hace referencia a un usuario de Fluz inexistente	Error de validación; no se crean registros.
Oferta inactiva, comercio no compartible o `offerId` inválido	Error de validación; no se crean registros.
`userCashBalanceId` faltante/inválido	Error de validación; no se crean registros.

Notas y limitaciones

La URL devuelta es el destino alojado, no un enlace corto. Internamente, los enlaces también se envuelven con un proveedor de enlaces cortos, pero la API devuelve la URL alojada canónica (/virtual-prepaid-card/{share_request_id}). Distribuye la URL exactamente como se devuelve.
userCashBalanceId es efectivamente requerido aunque el esquema lo marque como opcional.
Campos ocultos/internos no forman parte de esta API. El tipo de objeto y el tipo de tarjeta son fijos (VIRTUAL_CARD / SINGLE_LOAD). La financiación con cuenta bancaria y tarjeta bancaria aún no está habilitada; no las envíes. usePrepaymentBalance y useRewardsBalance son las únicas fuentes de fondos adicionales compatibles hoy.
No se admiten enlaces alojados de tarjetas de regalo. Esta API es solo para tarjetas virtuales.

Próximos pasos

Experiencia del destinatario

Lo que ven tus destinatarios cuando abren un enlace alojado y las reglas que rigen su tarjeta.

Registrar y Enviar

Usa EXISTING_USER para registrar a un destinatario y crear su tarjeta por adelantado, en lugar de al reclamar.

Crear una orden masiva

Emite muchas tarjetas a la vez para su distribución programática.

​Cómo funciona

​Disponibilidad y alcance

​Referencia de operaciones

​generateVCShareLinks

​Campos de entrada

​Identificación del destinatario y entrega (shareMethod)

​Reglas de validación

​Ejemplos

​Respuesta

​getVCShareLinks

​Campos de entrada

​Campos de respuesta (GeneratedShareLink)

​Ejemplos

​deactivateVCShareLinks

​Campos de entrada

​Vencimiento y congelación

​Referencia de estados y errores

​Estados del objeto de compartición

​Errores comunes de la API

​Notas y limitaciones

​Próximos pasos

Experiencia del destinatario

Registrar y Enviar

Crear una orden masiva

Cómo funciona

Disponibilidad y alcance

Referencia de operaciones

generateVCShareLinks

Campos de entrada

Identificación del destinatario y entrega (`shareMethod`)

Reglas de validación

Ejemplos

Respuesta

getVCShareLinks

Campos de entrada

Campos de respuesta (`GeneratedShareLink`)

Ejemplos

deactivateVCShareLinks

Campos de entrada

Vencimiento y congelación

Referencia de estados y errores

Estados del objeto de compartición

Errores comunes de la API

Notas y limitaciones

Próximos pasos