Descripción general

Genera enlaces alojados de tarjetas virtuales (Send Cards “open-loop”) desde tu plataforma. Llamas a una API para crear uno o más enlaces y luego entregas esos enlaces a los destinatarios como prefieras: por correo electrónico, SMS o devolviendo las URL sin procesar para incrustarlas en tus propios flujos. Cuando un destinatario abre el enlace, llega a una página alojada por Fluz, se verifica y reclama una tarjeta virtual de una sola carga financiada desde tu cuenta.

Requisitos previos: un token Bearer de acceso con el alcance CREATE_SHARE_LINK, y una cuenta habilitada para Send Cards (la bandera de campaña send_virtual_cards_enabled). La autenticación básica es rechazada. Contacta a tu representante de ventas para habilitar el acceso. Consulta Autenticación.

Qué significa “alojado” / “open-loop”. Un enlace alojado 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 (closed-loop).

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 corresponde a una solicitud de compartición (PENDING) y una URL alojada.

Se entrega el enlace

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

El destinatario activa y reclama la tarjeta

El destinatario abre el enlace, verifica su número de teléfono con un código de un solo uso y configura un NIP de la tarjeta — sin descargar app, sin contraseña. El límite de la tarjeta se descuenta de tu cuenta de gasto al momento de la reclamación, no cuando se genera el enlace. Luego puede ver los datos de la tarjeta, gastar en línea y agregar la tarjeta a Apple Pay o Google Pay con un toque.

El destinatario se convierte en usuario autorizado solo de ese objeto de tarjeta virtual — no obtiene acceso a tu cuenta, saldos u otras tarjetas. Mira la experiencia del destinatario en acción: flujo de escritorio · flujo móvil. Diagrama del flujo de Send cards

Disponibilidad y alcance

Capacidad	Estado
Tarjetas virtuales de una sola carga	✅ Compatible
Tarjetas de un solo uso / recargables	❌ No compatible
Generar enlaces vía API	✅ Compatible
Generar enlaces vía Importación CSV	✅ Compatible
Enlaces alojados de tarjetas 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 para tarjetas virtuales.

Referencia de operaciones

Hay tres operaciones públicas, todas protegidas 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, y tu cuenta debe tener Send Cards habilitado — sin esto, cada 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 entregan los enlaces: `GENERATE_URL`, `EMAIL` o `PHONE_NUMBER`.
`userCashBalanceId`	`UUID`	Sí*	La cuenta de gasto usada para financiar las tarjetas. Marcado como opcional en el esquema pero requerido en la práctica — si se omite falla la validación.
`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 — ver Vencimiento y congelamiento.
`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.

Fuente de fondos. Hoy, la única fuente de fondos compatible es una cuenta de gasto (userCashBalanceId), y debe pertenecer a tu cuenta (la del remitente). Fuentes de fondos adicionales (cuenta bancaria, tarjeta bancaria, saldo de prepago/recompensas) aún no están disponibles.

Métodos de entrega (`shareMethod`)

Valor	Comportamiento	Lista de destinatarios
`GENERATE_URL`	Fluz devuelve las URL alojadas en la respuesta. Tú las distribuyes.	Ambas listas deben estar vacías/omitidas.
`EMAIL`	Fluz envía por correo un enlace a cada destinatario.	`recipientListEmail` requerido; la longitud debe ser igual a `quantity`.
`PHONE_NUMBER`	Fluz envía por SMS un enlace a cada destinatario.	`recipientListPhone` requerido; la longitud debe ser igual a `quantity`.

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.
Al entregar por EMAIL o PHONE_NUMBER, la longitud de la lista de destinatarios correspondiente debe ser igual a quantity. Las discrepancias devuelven un error claro y no crean registros.
Solo se puede proporcionar una fuente de fondos. userCashBalanceId debe ser un UUID v4 válido propiedad de la cuenta del remitente.
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"
  }
}

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 ID de visualización 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
`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 ID de visualización.

Flujo recomendado. En la primera llamada, filtra solo por shareObjectStatuses. La respuesta te da los valores 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 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 vence el enlace / se congela la tarjeta.
`virtualCardId`	`String`	ID de la tarjeta virtual emitida, una vez reclamada.
`linkUrl`	`String`	La URL alojada del enlace.
`shareRequestDetails`	`ShareRequestDetails`	La configuración original (límite, oferta, cantidad, entrega, financiamiento).

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 puede ser reclamado.

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

Campos de entrada

Campo	Tipo	Descripción
`shareRequestBatchIds`	`[String]`	Desactiva todos los enlaces en estos lotes.
`shareRequestDisplayIds`	`[String]`	Desactiva solo los enlaces con estos ID de visualización.

Obtén los ID 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 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.

La experiencia del destinatario

Cuando un destinatario abre un enlace alojado (https://fluz.app/virtual-prepaid-card/{share_request_id}):

Inicio y acceso

El destinatario ve la página de activación con la marca del negocio remitente. Inicia sesión a través del portal de autenticación de Fluz (los destinatarios nuevos se incorporan aquí).

Autenticación de dos factores

En la carga inicial, los usuarios existentes son llevados a la pantalla de 2FA. 2FA es requerido antes de que la tarjeta pueda verse o reclamarse.

Dirección de facturación (si es necesaria)

Si el destinatario no tiene una dirección de facturación registrada, se le solicita agregar una. La dirección de facturación es requerida para compras en línea.

NIP (si aún no está emitida)

Antes de emitir la tarjeta, el destinatario configura un NIP.

Tarjeta emitida y reclamada

Se crea una tarjeta virtual de una sola carga y se asigna al destinatario, financiada desde la cuenta del remitente, con una fecha de bloqueo igual a la fecha de vencimiento del enlace.

Usar la tarjeta

Una vez reclamada, el destinatario puede ver los datos de la tarjeta, transacciones y (donde se admite) agregar la tarjeta a una billetera móvil.

¿Ya fue reclamada? Si el mismo usuario abre un enlace que ya reclamó, ve los datos de su tarjeta. Si un usuario diferente abre un enlace que otra persona ya reclamó, se le muestra un estado de acceso denegado después del 2FA.

Vencimiento y congelamiento

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

Vencimiento del enlace — después de esta fecha, un enlace no reclamado ya no se puede reclamar.
Congelamiento/bloqueo de la tarjeta — para una tarjeta emitida, esta es la fecha de bloqueo (fin de ese día). Después de esa fecha, la tarjeta se congela y no se puede usar.
Vencimiento de la tarjeta se alinea al fin del mes de la fecha de congelamiento (por ejemplo, una fecha de congelamiento de 15/6/2026 produce un vencimiento de tarjeta de 30/6/2026).

Configura la ventana con daysUntilExpiration al 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 de “Válida hasta”).

Reglas del programa para comunicar a los destinatarios

Estas son reglas a nivel de programa para tarjetas virtuales alojadas (open-loop). Confirma los valores exactos para tu programa con tu representante de Fluz — varias son negociadas con socios.

Regla	Predeterminado	Notas
Límite de gasto diario de la cuenta	$250,000/día	Algunos socios tienen un límite personalizado.
Buffer en transacciones de restaurantes	25%	Un buffer de 25% aplica a todos los programas (para propinas/retenciones en restaurantes).
Comercios / categorías restringidas	Específico del programa	Ciertas categorías de comercios están restringidas.
Financiamiento	Cuenta de gasto del remitente	Las tarjetas se financian desde la cuenta del remitente al momento de la reclamación.

Atención al cliente para destinatarios: 1-888-360-6660 · humans@fluz.app

La referencia completa para socios (terminología, recorrido del destinatario con capturas, instrucciones de financiamiento, categorías restringidas y soporte) está en la Guía para Socios — Tarjetas Virtuales con URL alojada. Pide a tu contacto de Fluz la última versión para tu programa.

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 expiró o fue desactivado; ya no se puede reclamar.

Errores del enlace mostrados al destinatario

Condición	Lo que ve el destinatario
El enlace expiró antes de ser reclamado	”Expired before issued” — el enlace ya no se puede reclamar.
El remitente desactivó el enlace anticipadamente	”Frozen by sender” — el enlace fue revocado antes del vencimiento.
La tarjeta fue reclamada y luego pasó su fecha de bloqueo	”Expired after issued” — la tarjeta está congelada.
Un usuario diferente abre un enlace ya reclamado	”Access denied”.

Errores comunes de la API

Causa	Resultado
Token Bearer faltante/inválido o alcance `CREATE_SHARE_LINK` faltante	Solicitud rechazada (no autorizado).
La cuenta no tiene acceso a Send Cards (`send_virtual_cards_enabled`)	Error de permisos que te dirige a tu representante de ventas.
Longitud de la lista de destinatarios ≠ `quantity`	Error de validación claro; 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, o más de una fuente de fondos	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 por 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) y otros campos de fuente de fondos aún no están habilitados; no los envíes.
No se admiten enlaces alojados de tarjetas de regalo. Esta API es solo para tarjetas virtuales.

Próximos pasos

Generar enlaces de compartición

La referencia enfocada para generateVCShareLinks, si es todo lo que necesitas.

Crear una orden masiva

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

​Cómo funciona

​Disponibilidad y alcance

​Referencia de operaciones

​generateVCShareLinks

​Campos de entrada

​Métodos de entrega (shareMethod)

​Reglas de validación

​Ejemplos

​Respuesta

​getVCShareLinks

​Campos de entrada

​Campos de respuesta (GeneratedShareLink)

​Ejemplos

​deactivateVCShareLinks

​Campos de entrada

​La experiencia del destinatario

​Vencimiento y congelamiento

​Reglas del programa para comunicar a los destinatarios

​Referencia de estados y errores

​Estados del objeto de compartición

​Errores del enlace mostrados al destinatario

​Errores comunes de la API

​Notas y limitaciones

​Próximos pasos

Generar enlaces de compartición

Crear una orden masiva

Cómo funciona

Disponibilidad y alcance

Referencia de operaciones

generateVCShareLinks

Campos de entrada

Métodos de entrega (`shareMethod`)

Reglas de validación

Ejemplos

Respuesta

getVCShareLinks

Campos de entrada

Campos de respuesta (`GeneratedShareLink`)

Ejemplos

deactivateVCShareLinks

Campos de entrada

La experiencia del destinatario

Vencimiento y congelamiento

Reglas del programa para comunicar a los destinatarios

Referencia de estados y errores

Estados del objeto de compartición

Errores del enlace mostrados al destinatario

Errores comunes de la API

Notas y limitaciones

Próximos pasos