> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Descripción general
> Genere enlaces alojados de tarjetas virtuales ("open-loop" Send Cards) desde su plataforma. Llama a una sola API para crear uno o más enlaces y luego entrega esos enlaces a los destinatarios como prefieras: por email, por 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 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](/concepts/authentication).
**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
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.
Cada enlace se asigna a una solicitud de compartición (`PENDING`) y a una URL alojada.
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 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](https://test.fluz.app/wp-content/uploads/2026/04/Web-Share-V6.mp4) · [flujo en móvil](https://test.fluz.app/wp-content/uploads/2026/04/Mob-Share-F.mp4).
## 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:///api/v1/graphql` con un encabezado `Authorization: Bearer `. 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.
```graphql theme={null}
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](#expiration--freeze). |
| `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
```json Generate URLs theme={null}
{
"input": {
"cardLimit": 25,
"offerId": "11111111-2222-3333-4444-555555555555",
"daysUntilExpiration": 30,
"quantity": 3,
"shareMethod": "GENERATE_URL",
"userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
}
```
```json Email theme={null}
{
"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"
}
}
```
```json SMS theme={null}
{
"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
```json theme={null}
{
"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.
```graphql theme={null}
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
```json By status theme={null}
{ "input": { "shareObjectStatuses": ["PENDING", "ISSUED"] } }
```
```json By batch theme={null}
{ "input": { "shareRequestBatchIds": ["ABC123", "XYZ789"] } }
```
```json By display ID theme={null}
{ "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.
```graphql theme={null}
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`.
```json theme={null}
{ "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}`):
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í).
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.
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.*
Antes de emitir la tarjeta, el destinatario configura un PIN.
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.
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](mailto: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
Emite muchas tarjetas a la vez para distribución programática.