Descripción general de tarjetas open loop

Requisitos previos: un token Bearer de acceso con el CREATE_SHARE_LINK scope. La autenticación básica es rechazada. 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 usar en muchos comercios, sujeta a las reglas de tu programa — no una tarjeta de regalo de marca única (closed-loop).

Cómo funciona

Tú generas enlaces

Llama a generateVCShareLinks con la oferta, límite de la tarjeta, cantidad, 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 es entregado

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, sin 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 revela automáticamente al reclamarla; al revelarla se solicita al destinatario ingresar su PIN, o crear uno si aún no lo ha configurado. Consulta Experiencia del destinatario para el recorrido completo.

El destinatario se convierte en un usuario autorizado únicamente de ese objeto de tarjeta virtual — no obtiene acceso a tu cuenta, saldos u otras tarjetas. Diagrama del flujo de Send cards

Disponibilidad y alcance

Capacidad	Estado
Tarjetas virtuales de una sola carga	✅ Compatible
Tarjetas virtuales de un solo uso	✅ Compatible
Tarjetas recargables	❌ No compatible

e

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 marco de “tarjetas virtuales y tarjetas de regalo” de la iniciativa más amplia, hoy no existe un flujo alojado de reclamación de 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 desarrolla únicamente contra tarjetas virtuales.

Referencia de operación

ce

Hay tres operaciones públicas, todas protegidas por el CREATE_SHARE_LINK scop

Operación	Tipo	Propósito
`generateVCShareLinks`	Mutación	Crea uno o más enlaces de tarjetas virtuales alojadas
`getVCShareLinks`	Consulta	Lista/inspecciona enlaces generados previamente
`deactivateVCShareLinks`	Mutación	Desactiva (expira) 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 `CREATE_SHARE_LINK` scope — 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 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 usada para financiar las tarjetas. Marcado como opcional en el esquema pero requerido en la práctica — omitirlo falla la validación.

s

`daysUntilExpiration`	`Int`	No	Días hasta que el enlace expire. Mínimo 1. Predetermina al valor por defecto del programa (30 días) si se omite. 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`. La 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`. La longitud debe ser igual a `quantity`. Debe estar vacío en caso contrario.
`recipientUserIds`	`[UUID]`	Condicional	IDs de usuarios de Fluz conocidos para vincular como destinatarios cuando `shareMethod = EXISTING_USER`. La longitud debe ser igual a `quantity`. Mutuamente excluyente con `recipientRegistrations`.
`recipientRegistrations`	`[ShareLinkRecipientRegistrationInput]`	Condicional	Payloads de preregistro en línea cuando `shareMethod = REGISTER_USER` — Fluz crea o reutiliza un usuario provisional (sin asiento) por entrada antes de generar los enlaces. La longitud debe ser igual a `quantity`. Mutuamente excluyente con `recipientUserIds`.
`usePrepaymentBalance`	`Boolean`	No	Define si se usa tu saldo de Prepayment 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	Define si se usa tu saldo de Fluz Rewards 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 obligatoria. Opcionalmente configura usePrepaymentBalance y/o useRewardsBalance en true para permitir que Fluz recurra a tu saldo de prepayment o de recompensas si la cuenta de gasto no cubre el monto total al 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ú las distribuyes.	Ambas listas deben estar vacías/omitidas.	Al reclamar
`EMAIL`	Fluz envía por email 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 por 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, 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 diferir la creación de la tarjeta al momento de la reclamación. Consulta Registrar y enviar para el flujo completo de EXISTING_USER, incluyendo 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 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 válido y existente de Fluz.
userCashBalanceId es obligatorio y debe ser un UUID v4 válido propiedad de la cuenta del remitente. usePrepaymentBalance y useRewardsBalance son fuentes de respaldo opcionales y pueden habilitarse ambas junto con ella.
Tipos de tarjeta inválidos o entradas con formato incorrecto 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 a 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 solo devuelve las URL. Para recuperar el ID del lote y los IDs de display de los enlaces que acabas de crear (necesarios para listar y desactivar), usa getVCShareLinks filtrado por estado.

getVCShareLinks

Lista enlaces de compartición generados previamente para que puedas inspeccionar estado, destinatarios, 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

s

`shareObjectStatuses`	`[ShareObjectStatus]`	Filtra por estado: `PENDING`, `ISSUED`, `USED`, `EXPIRED`.	.
`shareRequestBatchIds`	`[String]`	Devuelve solo enlaces en estos lotes.
	`shareRequestDisplayIds`	`[String]`	Devuelve solo los enlaces con estos IDs de display.

Flujo recomendado. En la primera llamada, filtra solo por shareObjectStatuses. La respuesta te da valores de 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 aplicación/desarrollador que generó el enlace.

)

`shareRequestBatchId`	`String`	Identificador de lote compartido por todos los enlaces generados en una llamada.
`shareRequestDisplayId`	`String`	Identificador por enlace, legible por humanos.
`shareObjectStatus`	`ShareObjectStatus`	`PENDING`, `ISSUED`, `USED` o `EXPIRED`.
`recipientEmail`	`String`	Email del destinatario, si se entregó por email.
`recipientPhone`	`String`	Teléfono del destinatario, si se entregó por SMS.
`linkExpirationDate`	`DateTime`	Cuándo el enlace expira / la tarjeta se congela.
`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 la tarjeta, oferta, cantidad, entrega, financiación).
Ejemplos

By status

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

By batch

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

By display ID

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

By display ID

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 puede reclamarse.

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

Campos de entrada

Campo	Tipo	Descripción

s

`shareRequestBatchIds`	`[String]`	Desactiva todos los enlaces en estos lotes.	.
`shareRequestDisplayIds`	`[String]`	Desactiva solo los enlaces con estos IDs de display.
			Obtén los IDs de lote desde `getVCShareLinks`.

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

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

Si un destinatario ya reclamó 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 puede ser reclamado.
Fecha de congelación/bloqueo de la tarjeta — para una tarjeta emitida, esta es la fecha de bloqueo (fin de ese día). Después, la tarjeta se congela y no se puede usar.
Vencimiento de la tarjeta se alinea con el fin del mes de la fecha de congelación (por ejemplo, una fecha de congelación de 15/6/2026 produce un vencimiento de tarjeta de 30/6/2026).
. Define la ventana con daysUntilExpiration en el momento de la generación. Si se omite, se usa el valor por defecto del programa (30 días). Esta fecha se muestra al destinatario (normalmente como una fecha “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.

s

`ISSUED`	El destinatario reclamó el enlace; se emitió una tarjeta virtual.	s
`USED`	La tarjeta emitida ha sido utilizada.
`EXPIRED`	El enlace expiró o fue desactivado; ya no es reclamable.
Para los estados que ve un destinatario cuando un enlace está vencido, revocado o ya reclamado, consulta Errores del enlace de cara al destinatario. Errores comunes de la API

Causa	Resultado
Token Bearer faltante/inválido o `CREATE_SHARE_LINK` scope ausente	Solicitud rechazada (no autorizado).
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 mediante 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 obligatorio 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 financiación adicionales compatibles hoy.
Los enlaces alojados de tarjetas de regalo no son compatibles. 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

​e

​Referencia de operación

​ce

generateVCShareLinks

​Campos de entrada

​s

​Identificación del destinatario y entrega (shareMethod)

​)

​Reglas de validación

​Ejemplos

​Respuesta

​getVCShareLinks

​Campos de entrada

​s

​Campos de respuesta (GeneratedShareLink)

​)

s

Ejemplos

​deactivateVCShareLinks

​Campos de entrada

​s

​Vencimiento y congelación

​Referencia de estados y errores

​Estados del objeto de compartición

​s

s

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

e

Referencia de operación

ce

Campos de entrada

s

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

)

Reglas de validación

Ejemplos

Respuesta

getVCShareLinks

Campos de entrada

s

Campos de respuesta (`GeneratedShareLink`)

)

deactivateVCShareLinks

Campos de entrada

s

Vencimiento y congelación

Referencia de estados y errores

Estados del objeto de compartición

s

Notas y limitaciones

Próximos pasos