Generar enlaces para compartir

Genera enlaces alojados de tarjeta virtual (“Send Cards” de bucle abierto) desde tu plataforma. Llamas a una API para crear uno o más enlaces y luego entregas esos enlaces a los destinatarios por correo electrónico, SMS o mediante tu propio flujo de distribución. Cuando un destinatario abre el enlace, llega a una página de activación alojada por Fluz, se verifica y reclama una tarjeta virtual de una sola carga financiada desde tu cuenta.

Requisitos previos: un token de acceso Bearer con el alcance CREATE_SHARE_LINK, y una cuenta con el envío de tarjetas virtuales alojadas habilitado. Si tu cuenta no está habilitada, la API devuelve un error de permisos que te dirige a tu representante de Fluz.

Qué significa “alojado” / “bucle abierto”. Un enlace alojado apunta a una página de activación alojada por Fluz. Bucle abierto significa que el destinatario reclama una tarjeta virtual de red que puede usarse en comercios elegibles, sujeta a las reglas de tu programa.

¿Buscas la narrativa completa de la función — recorrido del destinatario, reglas del programa y la referencia completa de estados/errores? Consulta la visión general de Send Cards. Esta página es la referencia de API enfocada para las tres operaciones de enlaces para compartir.

Cómo funciona

Tu plataforma llama a generateVCShareLinks con la oferta, el límite de la tarjeta, la cantidad, la fuente de fondos y el método de entrega.
Fluz crea una solicitud de compartido y una URL alojada por cada enlace solicitado.
La entrega depende de shareMethod:
- GENERATE_URL: Fluz devuelve las URLs alojadas en la respuesta de la API y tú las distribuyes por tu cuenta.
- EMAIL: Fluz envía por correo electrónico a cada destinatario su enlace.
- PHONE_NUMBER: Fluz envía por SMS a cada destinatario su enlace.
El destinatario abre el enlace alojado, inicia sesión, completa la verificación y reclama la tarjeta.
Fluz emite una tarjeta virtual de una sola carga al destinatario, financiada desde la cuenta del remitente.

Autenticación

Todas las operaciones de enlaces para compartir de Send Cards usan la API GraphQL de Fluz.

POST https://<your-fluz-api-host>/api/v1/graphql
Authorization: Bearer <access_token>
Content-Type: application/json

Tu token de acceso debe incluir el alcance CREATE_SHARE_LINK.

{
  "scopes": ["CREATE_SHARE_LINK"]
}

Tu cuenta también debe tener habilitado el envío de tarjetas virtuales alojadas. Si tu cuenta no está habilitada, la API devuelve un error de permisos que te indica contactar a tu representante de Fluz.

Operaciones

Operación	Tipo	Propósito
`generateVCShareLinks`	Mutation	Crear uno o más enlaces de tarjeta virtual alojados.
`getVCShareLinks`	Query	Listar e inspeccionar enlaces generados previamente.
`deactivateVCShareLinks`	Mutation	Desactivar enlaces generados.

generateVCShareLinks

Crea quantity enlaces para compartir alojados.

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. Debe ser un número entero y cumplir el mínimo del programa.
`offerId`	`String!`	Sí	UUID v4 de la oferta de tarjeta virtual. La oferta debe estar activa y su comercio debe ser compartible.
`quantity`	`Int!`	Sí	Número de enlaces a generar. Fluz crea una URL alojada distinta por unidad.
`shareMethod`	`ShareMethodType!`	Sí	Método de entrega: `GENERATE_URL`, `EMAIL` o `PHONE_NUMBER`.
`userCashBalanceId`	`UUID`	Sí	Cuenta de gasto utilizada para financiar las tarjetas. Este campo es obligatorio aunque el esquema GraphQL pueda mostrarlo como opcional.
`daysUntilExpiration`	`Int`	No	Número de días que el enlace es válido. El mínimo es 1. Si se omite, se usa el valor predeterminado del programa. La fecha de vencimiento resultante también se convierte en la fecha de bloqueo/congelación de la tarjeta después de la emisión.
`recipientListEmail`	`[String]`	Condicional	Obligatorio cuando `shareMethod` es `EMAIL`. La longitud debe ser igual a `quantity`. Debe omitirse o estar vacío para otros métodos de entrega.
`recipientListPhone`	`[String]`	Condicional	Obligatorio cuando `shareMethod` es `PHONE_NUMBER`. La longitud debe ser igual a `quantity`. Debe omitirse o estar vacío para otros métodos de entrega.

Métodos de entrega

`shareMethod`	Comportamiento	Regla de lista de destinatarios
`GENERATE_URL`	Devuelve URLs alojadas para que las distribuyas tú.	No envíes `recipientListEmail` ni `recipientListPhone`.
`EMAIL`	Envía un correo electrónico por destinatario.	Envía `recipientListEmail`; la longitud debe ser igual a `quantity`.
`PHONE_NUMBER`	Envía un SMS por destinatario.	Envía `recipientListPhone`; la longitud debe ser igual a `quantity`.

Reglas de validación

cardLimit debe ser un número entero y cumplir el mínimo del programa.
offerId debe ser un UUID v4 válido para una oferta activa y compartible.
quantity debe ser un número entero.
Al usar EMAIL o PHONE_NUMBER, la longitud de la lista de destinatarios debe ser igual a quantity.
userCashBalanceId debe ser una cuenta de gasto válida propiedad de la cuenta del remitente.
No incluyas múltiples fuentes de fondos.
Las solicitudes inválidas o mal formadas fallan la validación y no crean enlaces para compartir.

Ejemplo: generar URLs para tu propia entrega

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

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

Ejemplo: enviar enlaces por correo electrónico a destinatarios

{
  "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"
  }
}

Ejemplo: enviar enlaces por SMS a destinatarios

{
  "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"
      ]
    }
  }
}

Cada valor en shareLinks es una URL alojada para una solicitud de compartido.

https://fluz.app/virtual-prepaid-card/{share_request_id}

La API devuelve la URL de destino alojada. Si Fluz también crea un enlace corto internamente, esa URL corta no es devuelta por esta API.

getVCShareLinks

Usa getVCShareLinks para listar enlaces generados, recuperar IDs de lote y de exhibición, inspeccionar objetivos de entrega y verificar el estado.

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` o `EXPIRED`.
`shareRequestBatchIds`	`[String]`	Devuelve solo enlaces en estos lotes.
`shareRequestDisplayIds`	`[String]`	Devuelve solo enlaces con estos IDs de exhibición.

Para la primera consulta, filtra por shareObjectStatuses. La respuesta incluye shareRequestBatchId y shareRequestDisplayId, que puedes usar para búsquedas posteriores o desactivación.

Ejemplos

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

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

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

Campos de respuesta

Campo	Tipo	Descripción
`senderAppId`	`String`	Aplicación que generó el enlace.
`shareRequestBatchId`	`String`	ID de lote compartido por enlaces creados en la misma solicitud de generación.
`shareRequestDisplayId`	`String`	ID legible para humanos de la solicitud de compartido individual.
`shareObjectStatus`	`ShareObjectStatus`	Estado actual de la solicitud de compartido.
`recipientEmail`	`String`	Correo electrónico del destinatario, cuando se entrega por correo electrónico.
`recipientPhone`	`String`	Número de teléfono del destinatario, cuando se entrega por SMS.
`linkExpirationDate`	`DateTime`	Fecha de vencimiento del enlace y fecha de bloqueo/congelación de la tarjeta.
`virtualCardId`	`String`	ID de la tarjeta virtual emitida después de que se reclama el enlace.
`linkUrl`	`String`	URL alojada para la solicitud de compartido.
`shareRequestDetails`	`ShareRequestDetails`	Configuraciones originales de generación.

deactivateVCShareLinks

Usa deactivateVCShareLinks para vencer enlaces generados, por ejemplo si un lote se envió por error o si es necesario revocar un enlace no reclamado.

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

Campos de entrada

Campo	Tipo	Descripción
`shareRequestBatchIds`	`[String]`	Desactivar todos los enlaces en estos lotes.
`shareRequestDisplayIds`	`[String]`	Desactivar solo los enlaces con estos IDs de exhibición.

Ejemplo

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

Respuesta

Devuelve una cadena de confirmación, por ejemplo:

3 share requests successfully deactivated!

Desactivar un enlace evita que un enlace no reclamado sea reclamado. Si una tarjeta ya ha sido emitida, usa los controles apropiados del ciclo de vida de la tarjeta para administrar esa tarjeta.

Experiencia de activación del destinatario

Cuando un destinatario abre un enlace alojado, se le dirige a una página de activación alojada por Fluz.

El destinatario abre el enlace de tarjeta virtual alojado.
El destinatario inicia sesión o crea una cuenta a través del flujo de autenticación de Fluz.
Los usuarios existentes completan 2FA antes de ver o reclamar la tarjeta.
Si el destinatario no tiene una dirección de facturación registrada, se le solicita agregar una. Se requiere una dirección de facturación para compras en línea.
Si la tarjeta aún no ha sido emitida, el destinatario establece un NIP.
Fluz emite la tarjeta virtual al destinatario.
Una vez emitida, el destinatario puede ver los detalles y la actividad de la tarjeta.

Si el mismo usuario abre un enlace que ya reclamó, puede ver los detalles de su tarjeta. Si un usuario diferente abre un enlace ya reclamado por otra persona, se le muestra un estado de acceso denegado después de la autenticación.

Vencimiento y congelamiento de la tarjeta

daysUntilExpiration determina la ventana de validez del enlace alojado. La fecha de vencimiento resultante se utiliza para dos comportamientos relacionados:

Antes de reclamar: después de la fecha de vencimiento, el enlace ya no se puede reclamar.
Después de reclamar: la fecha de vencimiento se convierte en la fecha de bloqueo/congelación de la tarjeta. Después de esa fecha, la tarjeta emitida se congela y ya no se puede gastar.

Si se omite daysUntilExpiration, se usa el valor predeterminado del programa.

Reglas del programa

Las reglas del programa pueden variar por socio. Confirma los valores finales para tu programa con tu representante de Fluz.

Regla	Predeterminado / comportamiento
Fuente de fondos	Cuenta de gasto del remitente.
Límite diario de gasto de la cuenta	$250,000/día a menos que tu programa tenga un límite personalizado.
Margen para transacciones en restaurantes	Se aplica un margen del 25% a las transacciones en restaurantes.
Comercios/categorías restringidos	Pueden aplicarse restricciones específicas del programa.
Soporte al destinatario	1-888-360-6660 o humans@fluz.app.

Referencia de estados

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

Errores comunes

Causa	Resultado
Falta el token Bearer o es inválido	La solicitud es rechazada.
Falta el alcance `CREATE_SHARE_LINK`	La solicitud es rechazada.
La cuenta no tiene habilitado el envío de tarjeta alojada	Error de permisos.
La longitud de la lista de destinatarios no es igual a `quantity`	Error de validación; no se crean enlaces.
Oferta inactiva o no compartible	Error de validación; no se crean enlaces.
`userCashBalanceId` faltante o inválido	Error de validación; no se crean enlaces.
Se proporcionaron múltiples fuentes de fondos	Error de validación; no se crean enlaces.

Notas y limitaciones

Esta API es solo para tarjetas virtuales alojadas. No se admiten enlaces de tarjetas de regalo alojadas.
La API devuelve URLs de destino alojadas, no URLs cortas.
userCashBalanceId es obligatorio en la práctica.
El tipo de objeto y el tipo de tarjeta están fijos para esta fase y no deben incluirse en solicitudes públicas de la API.

Antes de enviar:

Si tu fuente de fondos no tiene suficientes fondos en el momento en que el destinatario reclama la tarjeta, la emisión fallará. Asegúrate de tener saldo suficiente.
Los números de teléfono en recipientListPhone deben ser una cadena sin espacios y deben incluir el código de país al principio — p. ej., +18883606660, donde +1 es el código de país.

Próximos pasos

Visión general de Send Cards

La narrativa completa de la función — recorrido del destinatario, reglas del programa y referencia completa de errores.

Crear una orden masiva

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

​Cómo funciona

​Autenticación

​Operaciones

​generateVCShareLinks

​Campos de entrada

​Métodos de entrega

​Reglas de validación

​Ejemplo: generar URLs para tu propia entrega

​Ejemplo: enviar enlaces por correo electrónico a destinatarios

​Ejemplo: enviar enlaces por SMS a destinatarios

​Respuesta

​getVCShareLinks

​Campos de entrada

​Ejemplos

​Campos de respuesta

​deactivateVCShareLinks

​Campos de entrada

​Ejemplo

​Respuesta

​Experiencia de activación del destinatario

​Vencimiento y congelamiento de la tarjeta

​Reglas del programa

​Referencia de estados

​Errores comunes

​Notas y limitaciones

​Próximos pasos

Visión general de Send Cards

Crear una orden masiva

Cómo funciona

Autenticación

Operaciones

generateVCShareLinks

Campos de entrada

Métodos de entrega

Reglas de validación

Ejemplo: generar URLs para tu propia entrega

Ejemplo: enviar enlaces por correo electrónico a destinatarios

Ejemplo: enviar enlaces por SMS a destinatarios

Respuesta

getVCShareLinks

Campos de entrada

Ejemplos

Campos de respuesta

deactivateVCShareLinks

Campos de entrada

Ejemplo

Respuesta

Experiencia de activación del destinatario

Vencimiento y congelamiento de la tarjeta

Reglas del programa

Referencia de estados

Errores comunes

Notas y limitaciones

Próximos pasos