Registrar y Enviar

El flujo estándar de enlace alojado delega todo al destinatario: generas un enlace y Fluz no crea la tarjeta virtual hasta que el destinatario lo abre, se verifica y la reclama. Este flujo invierte eso para destinatarios que ya identificaste. Tú registras la identidad del destinatario y su dirección de facturación con registerUser, luego generas un enlace de envío con generateVCShareLinks usando shareMethod: EXISTING_USER. Fluz crea la tarjeta virtual de forma inmediata, al momento de la generación — no al reclamar — y la vincula a ese único destinatario. El enlace aún se entrega y reclama de la forma habitual; solo la creación de la tarjeta se adelanta. El financiamiento aún se realiza al momento de la reclamación, igual que en el flujo estándar — desde userCashBalanceId, recurriendo a tu saldo de prepago o recompensas si están habilitados y la cuenta de gasto se queda corta.

Cuándo usar esto en lugar de un enlace de envío simple

Ya sabes exactamente quién es el destinatario (por ID de usuario) y quieres que la tarjeta esté creada y lista antes de notificarle, en lugar de esperar a que la reclame.
Quieres una garantía estricta de que solo el destinatario previsto podrá ver el enlace — no “la primera persona que haga clic”.
Estás enviando a un lote de destinatarios conocidos y quieres un mapeo determinista 1:1 entre destinatario y tarjeta.

Antes de comenzar

Necesitarás un token de acceso Bearer. La autenticación básica no es aceptada para ninguna de las operaciones.

Operación	Alcance	También se requiere
`registerUser`	—	Permiso de registro habilitado en tu aplicación
`generateVCShareLinks`	`CREATE_SHARE_LINK`	Una oferta de tarjeta virtual activa, una cuenta de gasto desde la cual fondear (opcionalmente con saldo de prepago/recompensas como respaldo)

El registro de usuarios no está habilitado por defecto. registerUser es una mutación restringida — tu aplicación debe ser aprobada explícitamente por Fluz antes de poder crear usuarios. Contacta a tu representante de ventas de Fluz o a tu gerente de cuenta para habilitarlo. Las llamadas desde una aplicación no aprobada fallan con AUTH-0022.Si el destinatario ya tiene una cuenta de Fluz, puedes omitir el registro e ir directamente a generateVCShareLinks con sus recipientUserIds existentes.

Consulta Autenticación para cómo generar un token con alcance.

El flujo

Registrar al destinatario

Llama a registerUser con el perfil del destinatario, su dirección de facturación y su aceptación del acuerdo de tarjetahabiente.

mutation RegisterUser(
  $firstName: String!
  $lastName: String!
  $phoneNumber: String!
  $regionCode: String!
  $emailAddress: String!
  $dateOfBirth: String!
  $billingAddress: VirtualCardBillingAddressInput!
  $acceptCardholderAgreement: Boolean!
) {
  registerUser(
    firstName: $firstName
    lastName: $lastName
    phoneNumber: $phoneNumber
    regionCode: $regionCode
    emailAddress: $emailAddress
    dateOfBirth: $dateOfBirth
    billingAddress: $billingAddress
    acceptCardholderAgreement: $acceptCardholderAgreement
  ) {
    success
    userId
    accountId
    billingAddressId
    error {
      code
      message
    }
  }
}

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "phoneNumber": "5555555555",
  "regionCode": "US",
  "emailAddress": "ada.lovelace@example.com",
  "dateOfBirth": "1990-01-31",
  "billingAddress": {
    "streetAddressLine1": "456 Market St",
    "streetAddressLine2": "Suite 200",
    "country": "United States",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105"
  },
  "acceptCardholderAgreement": true
}

acceptCardholderAgreement debe ser true — de lo contrario, el registro se rechaza. Las fallas de registro regresan como HTTP 200 con success: false, no en el arreglo errors de GraphQL; siempre verifica success.Conserva el userId devuelto — lo pasarás a generateVCShareLinks en el siguiente paso. accountId y billingAddressId también se devuelven pero no son necesarios para este flujo.

Este paso no crea una tarjeta ni un acuerdo de tarjetahabiente. Solo crea el registro del usuario, guarda la dirección de facturación y registra que se aceptó el acuerdo. Tanto la tarjeta virtual como la vinculación del destinatario a ella se crean en el siguiente paso.

AUTH-0026 y AUTH-0027 no son fallas. Significan que la persona ya tiene una cuenta de Fluz — común, ya que las cuentas de Fluz no están limitadas a tu aplicación. Omite el registro y usa directamente su ID de usuario existente.

Referencia completa de parámetros: registerUser.

Generar el enlace de envío

Llama a generateVCShareLinks con shareMethod: EXISTING_USER y recipientUserIds establecido con el/los ID(s) de usuario del registro (o cualquier otro ID de usuario conocido de Fluz). La longitud de recipientUserIds debe ser igual a quantity.

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

{
  "input": {
    "cardLimit": 100,
    "offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
    "daysUntilExpiration": 30,
    "quantity": 1,
    "shareMethod": "EXISTING_USER",
    "recipientUserIds": ["f1320ac4-52dc-4c67-9e80-24e506b18450"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Para múltiples destinatarios, pasa un ID de usuario por tarjeta — el orden corresponde 1:1 con los enlaces generados:

{
  "input": {
    "cardLimit": 100,
    "offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
    "quantity": 3,
    "shareMethod": "EXISTING_USER",
    "recipientUserIds": [
      "f1320ac4-52dc-4c67-9e80-24e506b18450",
      "3f8a1c2d-4e5f-4a67-9a10-2b3c4d5e6f70",
      "9b2d0e11-77aa-4c3b-8f9e-1a2b3c4d5e6f"
    ],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Deja recipientListEmail y recipientListPhone sin establecer — los destinatarios se identifican por recipientUserIds para este shareMethod, y Fluz ya tiene los datos de contacto archivados para cada usuario registrado.Opcionalmente configura usePrepaymentBalance y/o useRewardsBalance en true para que Fluz pueda tomar de tu saldo de prepago o recompensas como respaldo si userCashBalanceId no cubre el monto total al momento de la reclamación:

With fallback funding

{
  "input": {
    "cardLimit": 100,
    "offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
    "quantity": 1,
    "shareMethod": "EXISTING_USER",
    "recipientUserIds": ["f1320ac4-52dc-4c67-9e80-24e506b18450"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "usePrepaymentBalance": true,
    "useRewardsBalance": true
  }
}

Consulta fuentes de fondos para más detalles.

Fluz crea la tarjeta y asigna el enlace

A diferencia del flujo estándar, la tarjeta virtual se crea ahora, al momento de la generación, en lugar de aplazarse hasta la reclamación. El destinatario se asigna a esa tarjeta y a su enlace tan pronto como la llamada regresa. El financiamiento aún se realiza al momento de la reclamación, igual que en el flujo estándar — principalmente desde userCashBalanceId, usando tu saldo de prepago o recompensas como respaldo si configuraste usePrepaymentBalance / useRewardsBalance y la cuenta de gasto se queda corta.Cada enlace devuelto está bloqueado para su destinatario asignado: solo la cuenta de Fluz de ese destinatario puede abrirlo y reclamarlo. Si un usuario diferente abre la URL, se le muestra un estado de acceso denegado después de iniciar sesión, igual que con cualquier otro enlace ya vinculado.

Se entrega el enlace

El enlace se envía al destinatario de la misma manera que cualquier enlace alojado — vía SMS o correo electrónico, usando los datos de contacto que Fluz tiene archivados para ese usuario. A partir de ahí, el destinatario inicia sesión, completa el 2FA y llega a su tarjeta. Como la tarjeta ya existe, no hay solicitud de dirección de facturación ni espera de emisión de tarjeta al momento de la reclamación — la tarjeta se fondea en ese punto, igual que en el flujo estándar.

En qué difiere del flujo estándar

	Estándar (`GENERATE_URL` / `EMAIL` / `PHONE_NUMBER`)	Este flujo (`EXISTING_USER`)
Destinatario identificado por	Correo/teléfono en `recipientListEmail` / `recipientListPhone`	`userId` de Fluz conocido en `recipientUserIds`
Tarjeta creada	Al reclamar, cuando el destinatario completa la incorporación	En el momento de la llamada a `generateVCShareLinks`
Tarjeta fondeada	Al momento de la reclamación	Al momento de la reclamación (igual que el estándar)
Quién puede reclamar el enlace	Quien lo abra primero, si no ha sido reclamado	Solo el destinatario asignado — aplicado desde el momento en que se crea el enlace
Onboarding del destinatario al reclamar	Inicio de sesión, 2FA, dirección de facturación (si es necesaria)	Inicio de sesión, 2FA — sin solicitud de dirección de facturación, ya que se recopiló en el registro
Revelar la tarjeta	Solicita PIN (o creación de PIN, si aún no se ha configurado)	Solicita PIN (o creación de PIN, si aún no se ha configurado)

Consulta Enviar Tarjetas Open Loop para el flujo estándar y Experiencia del Destinatario para la guía completa de reclamación.

Notas y limitaciones

recipientUserIds debe hacer referencia a usuarios de Fluz existentes. Si el destinatario aún no está registrado, primero regístralo con registerUser (este flujo), o usa el flujo estándar de enlace alojado y permite que Fluz lo incorpore al momento de la reclamación.
La longitud de recipientUserIds debe ser igual a quantity. Una discrepancia devuelve un error de validación y no crea registros.
La creación de la tarjeta se adelanta al momento de la generación — el financiamiento no. El objeto de la tarjeta virtual y la vinculación del destinatario se crean cuando llamas a generateVCShareLinks, pero los fondos aún se toman al momento de la reclamación, igual que en el flujo estándar: primero desde userCashBalanceId, luego de tu saldo de prepago o recompensas como respaldo si usePrepaymentBalance / useRewardsBalance están configurados y la cuenta de gasto es insuficiente.
El registro es por aplicación y por entorno. El permiso otorgado para staging no se transfiere a producción. Consulta Implementación en Producción.
Nunca registres personas reales en staging. Consulta Staging vs. Live.

Próximos pasos

Enviar Tarjetas Open Loop

El flujo estándar — genera enlaces y permite que Fluz emita la tarjeta al momento de la reclamación.

Experiencia del Destinatario

Lo que ve el destinatario cuando abre y reclama un enlace alojado.

Registrar Clientes

Referencia completa de registerUser, incluyendo manejo de errores y patrones de respaldo.

​Antes de comenzar

​El flujo

​En qué difiere del flujo estándar

​Notas y limitaciones

​Próximos pasos

Enviar Tarjetas Open Loop

Experiencia del Destinatario

Registrar Clientes

Antes de comenzar

El flujo

En qué difiere del flujo estándar

Notas y limitaciones

Próximos pasos