Descripción general

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

Qué significan “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 puede gastarse en muchos comercios, sujeta a las reglas de tu programa — no una tarjeta de regalo de marca única y circuito cerrado.

Cómo funciona

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.

Se entrega el enlace

Con GENERATE_URL recibes las URL para distribuirlas tú. 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, verifica su número de teléfono con un código de un solo uso y define un PIN de la tarjeta — 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. 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 ni a ninguna otra tarjeta. Mira la experiencia del destinatario en acción: flujo en escritorio · flujo en móvil. Diagrama del flujo de envío de tarjetas

Disponibilidad y alcance

Funcionalidad	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	❌ Próximamente
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 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 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`	Mutación	Crear uno o más enlaces de tarjetas virtuales alojadas
`getVCShareLinks`	Consulta	Listar/inspeccionar enlaces generados previamente
`deactivateVCShareLinks`	Mutación	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 enteras de moneda. 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 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 expire el enlace. 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 — ver 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.

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 email un enlace a cada destinatario.	`recipientListEmail` requerida; la longitud debe igualar `quantity`.
`PHONE_NUMBER`	Fluz envía por SMS un enlace a cada destinatario.	`recipientListPhone` requerida; la longitud debe igualar `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 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 y pertenecer a 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 de lote y los ID visibles 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]`	Filtrar por estado: `PENDING`, `ISSUED`, `USED`, `EXPIRED`.
`shareRequestBatchIds`	`[String]`	Devolver solo enlaces en estos lotes.
`shareRequestDisplayIds`	`[String]`	Devolver solo los enlaces con estos ID visibles.

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 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`	Email 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`	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]`	Desactiva todos los enlaces en estos lotes.
`shareRequestDisplayIds`	`[String]`	Desactiva solo los enlaces con estos ID visibles.

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

La experiencia del destinatario

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

Página de aterrizaje e inicio de sesión

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 obligatorio antes de poder ver o reclamar la tarjeta.

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 obligatoria para compras en línea.

PIN (si aún no se emitió)

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

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 sea compatible) agregar la tarjeta a una billetera móvil.

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

Vencimiento y congelación

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

Vencimiento del enlace — después de esta fecha, un enlace no reclamado ya no se puede reclamar.
Congelación/bloqueo 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.
Vencimiento de la tarjeta se alinea con el final del mes de la fecha de congelación (p. ej., una fecha de congelación 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 predeterminado 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 — varios son negociados con socios.

Regla	Predeterminado	Notas
Límite diario de gasto de la cuenta	$250,000/día	Algunos socios tienen un límite personalizado.
Margen en transacciones de restaurantes	25%	Se aplica un margen del 25% a todos los programas (para acomodar propinas/retenciones en restaurantes).
Comercios / categorías restringidas	Específico del programa	Ciertas categorías de comercios están restringidas.
Financiación	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 financiación, categorías restringidas y soporte) se encuentra en la Guía para Socios — Tarjetas Virtuales por URL alojada. Solicita a tu contacto de Fluz la última copia 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`	Se ha utilizado la tarjeta emitida.
`EXPIRED`	El enlace expiró o fue desactivado; ya no es reclamable.

Errores del enlace visibles para el 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 antes de tiempo	”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 ausente/inválido o sin el alcance `CREATE_SHARE_LINK`	Solicitud rechazada (no autorizado).
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` ausente/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 encapsulan 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, en la práctica, 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) 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

Crear una orden en lote

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 congelación

​Reglas del programa para comunicar a los destinatarios

​Referencia de estados y errores

​Estados del objeto de compartición

​Errores del enlace visibles para el destinatario

​Errores comunes de la API

​Notas y limitaciones

​Próximos pasos

Crear una orden en lote

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 congelación

Reglas del programa para comunicar a los destinatarios

Referencia de estados y errores

Estados del objeto de compartición

Errores del enlace visibles para el destinatario

Errores comunes de la API

Notas y limitaciones

Próximos pasos