Métodos de entrega

La versión corta: no necesitas saber nada sobre tu destinatario para generar una tarjeta.Los datos de contacto del destinatario solo son necesarios cuando quieres que Fluz haga la entrega. Si entregas el enlace tú mismo, nos envías un límite de tarjeta, una oferta y una cuenta de fondos — nada más. El destinatario completa sus propios datos en la página alojada.

Elige tu método

¿Quieres que Fluz entregue el enlace o lo harás tú?

Si lo entregas tú mismo — por tu propio email, tu propio SMS, en tu app, en un portal, o entregando la URL a un cliente downstream — usa GENERATE_URL. No se requieren datos del destinatario.

Si Fluz lo entrega, ¿cómo?

Email (EMAIL) o SMS (PHONE_NUMBER). Proporcionas una dirección o número por tarjeta.

¿Ya tienes los datos de identidad completos del destinatario?

Si los tienes — y quieres que el destinatario omita la captura de datos por completo — consulta con tu representante de Fluz sobre la inscripción prellenada. Es una opción restringida, no parte del flujo estándar de generateVCShareLinks.

Las cuatro opciones de un vistazo

#	Opción	`shareMethod`	Qué le envías a Fluz	Quién entrega el enlace	Qué ingresa el destinatario
1	Generar un enlace	`GENERATE_URL`	Nada sobre el destinatario	Tú	Sus propios datos
2	Fluz lo envía por email	`EMAIL`	Un email por tarjeta	Fluz	Sus propios datos
3	Fluz lo envía por SMS	`PHONE_NUMBER`	Un número telefónico por tarjeta	Fluz	Sus propios datos
4	Inscripción prellenada	Restringida — contacta a tu representante	Datos de identidad completos del destinatario	Tú o Fluz	Nada — solo reclaman

Las opciones 1–3 son tres valores del mismo campo shareMethod en una sola mutación. Cambiar entre ellos es un ajuste de una línea — no estás integrando tres APIs diferentes.

Opción 1 — Generar un enlace, tú lo entregas

La mayoría de los partners quieren esta. Llamas al API, recibes un arreglo de URLs y haces lo que quieras con ellas: las envías por email desde tu propio sistema, por SMS, las colocas en un portal para clientes o se las das a un cliente downstream que las distribuye a sus propios usuarios finales. Fluz no envía nada a nadie. No tenemos datos de contacto del destinatario para estos enlaces porque nunca nos diste ninguno.

Generate URLs

{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 1,
    "daysUntilExpiration": 30,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Response

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1"
      ]
    }
  }
}

Con GENERATE_URL, tanto recipientListEmail como recipientListPhone deben estar vacíos u omitidos. Enviar una lista de destinatarios junto con GENERATE_URL es un error de validación y no crea registros.

Establece quantity por encima de 1 para acuñar un lote en una sola llamada. Obtienes una URL distinta por unidad, y cada URL puede reclamarse exactamente una vez. Distribuye las URLs exactamente como se devuelven — no las reescribas ni las acortes.

Opción 2 — Fluz envía el enlace por email

Proporcionas un email por tarjeta y Fluz envía el correo. El destinatario hace clic para ir a la misma página alojada que en la Opción 1 y allí ingresa sus propios datos. Úsalo cuando ya tengas los emails de los destinatarios y prefieras no construir tú mismo la entrega.

{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 2,
    "daysUntilExpiration": 30,
    "shareMethod": "EMAIL",
    "recipientListEmail": ["mike.bennett@example.com", "dana.ruiz@example.com"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

La longitud de recipientListEmail debe ser igual a quantity. Una discrepancia devuelve un error de validación y no crea registros — no hay lotes parciales.

Opción 3 — Fluz envía el enlace por SMS

Igual que la Opción 2, pero por SMS. Proporcionas un número telefónico por tarjeta en formato E.164. Fluz envía el SMS; Fluz no envía también un email en este camino.

SMS

{
  "input": {
    "cardLimit": 100,
    "offerId": "7c4a1d92-3fb8-4e05-9a61-2d8ef50b7c33",
    "quantity": 2,
    "daysUntilExpiration": 30,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": ["+12125550101", "+12125550102"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

La longitud de recipientListPhone debe ser igual a quantity, y ambas listas son mutuamente excluyentes — envía la que coincida con tu shareMethod y deja la otra vacía.

Opción 4 — Inscripción prellenada

Algunos partners quieren una experiencia de alto nivel en la que el destinatario no ingresa nada. En ese modelo tú le pasas a Fluz los datos de identidad que la inscripción de la tarjeta necesita, y la única acción del destinatario es abrir el enlace y reclamar la tarjeta. Esta es una opción restringida y no forma parte del generateVCShareLinks estándar. Si tu programa la necesita, habla con tu equipo de cuenta de Fluz — conlleva obligaciones adicionales de manejo de datos y cumplimiento de tu lado, ya que estás proporcionando información personal en nombre de una persona que aún no ha interactuado con Fluz.

Elige esto solo si realmente posees datos de identidad verificados del destinatario. Si te tienta la Opción 4 simplemente para evitar pedir información a los destinatarios, la Opción 1 casi con seguridad es la que quieres.

Lo que hace el destinatario

Idéntico en las Opciones 1–3. El enlace lleva a la misma página alojada sin importar quién lo entregó:

Abrir el enlace

Sin descargar app, sin cuenta de Fluz, sin contraseña.

Verificar por teléfono

Un código de un solo uso confirma a la persona que tiene el enlace.

Ingresar sus datos de tarjeta

El destinatario proporciona los datos que la tarjeta necesita. No aparece un aviso de PIN en esta etapa.

Reclamar, revelar y gastar

La tarjeta se fondea desde tu cuenta de gasto en el momento del reclamo, no cuando se generó el enlace. El destinatario se convierte en usuario autorizado de ese único objeto de tarjeta — nada más en tu cuenta. La tarjeta no se revela automáticamente al reclamar: al revelarla se pide al destinatario ingresar su PIN, o crear uno si aún no lo ha configurado.

Consulta Experiencia del destinatario para el recorrido completo y los estados que ve un destinatario cuando un enlace está vencido, revocado o ya reclamado.

Puntos comunes de confusión

¿Tenemos que precargar la información del destinatario?

No. Esa es una lectura común errónea de la referencia del API. Los campos del destinatario existen para que Fluz pueda entregar en tu nombre — no son entradas para la emisión de la tarjeta. Con GENERATE_URL no envías ningún dato del destinatario.

¿Debe haber una dirección de email en cada solicitud?

No. recipientListEmail es obligatorio solo cuando shareMethod = EMAIL. Con GENERATE_URL y PHONE_NUMBER debe estar vacío.

Pasamos el enlace a nuestro cliente, quien se lo pasa a su usuario final. ¿Funciona?

Sí — ese es exactamente el patrón de GENERATE_URL. La URL es de tipo portador: quien la abra primero y complete la verificación reclama la tarjeta. Trata los enlaces como sensibles y entrégalos por un canal en el que confíes.

¿Puedo generar un enlace de prueba desde el portal?

Hoy no. La generación de enlaces es solo por API. Prueba en el entorno de staging con un token de staging que tenga el alcance CREATE_SHARE_LINK — consulta Entorno de Staging vs. Producción.

¿Puedo cambiar de método después?

Sí. shareMethod se establece por llamada, no por cuenta. Nada te impide generar URLs para un lote y hacer que Fluz envíe por email el siguiente.

Requisitos comunes a todos los métodos

Requisito	Detalle
Auth	Bearer access token con el alcance `CREATE_SHARE_LINK`. Se rechaza la autenticación básica.
Fondos	`userCashBalanceId` — una cuenta de gasto en tu propia cuenta. En la práctica es obligatorio aunque aparezca como opcional en el esquema.
Oferta	`offerId` debe ser una oferta activa cuyo comercio sea compartible.
Vencimiento	`daysUntilExpiration` es 30 por defecto. Esta fecha también es la fecha de congelación de la tarjeta.

Funciones

Métodos de entrega

Elige tu método

Las cuatro opciones de un vistazo

Opción 1 — Generar un enlace, tú lo entregas

Opción 2 — Fluz envía el enlace por email

Opción 3 — Fluz envía el enlace por SMS

Opción 4 — Inscripción prellenada

Lo que hace el destinatario

Puntos comunes de confusión

Requisitos comunes a todos los métodos

Próximos pasos

Descripción general de Open Loop Cards

Experiencia del destinatario

​Elige tu método

​Las cuatro opciones de un vistazo

​Opción 1 — Generar un enlace, tú lo entregas

​Opción 2 — Fluz envía el enlace por email

​Opción 3 — Fluz envía el enlace por SMS

​Opción 4 — Inscripción prellenada

​Lo que hace el destinatario

​Puntos comunes de confusión

​Requisitos comunes a todos los métodos

​Próximos pasos

Descripción general de Open Loop Cards

Experiencia del destinatario

Elige tu método

Las cuatro opciones de un vistazo

Opción 1 — Generar un enlace, tú lo entregas

Opción 2 — Fluz envía el enlace por email

Opción 3 — Fluz envía el enlace por SMS

Opción 4 — Inscripción prellenada

Lo que hace el destinatario

Puntos comunes de confusión

Requisitos comunes a todos los métodos

Próximos pasos