> ## 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
Genera **enlaces alojados de tarjetas virtuales** (Send Cards “open-loop”) desde tu plataforma. Llamas a una API para crear uno o más enlaces y luego entregas esos enlaces a los destinatarios como prefieras: por correo electrónico, 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 Bearer de acceso con el alcance `CREATE_SHARE_LINK`, y una cuenta habilitada para Send Cards (la bandera de campaña `send_virtual_cards_enabled`). La autenticación básica es rechazada. Contacta a tu representante de ventas para habilitar el acceso. Consulta [Autenticación](/concepts/authentication).
**Qué significa “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 se puede gastar en muchos comercios, sujeta a las reglas de tu programa — no una tarjeta de regalo de marca única (closed-loop).
## Cómo funciona
Llama a `generateVCShareLinks` con la oferta, el límite de la tarjeta, la cantidad, la 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 corresponde a una solicitud de compartición (`PENDING`) y una URL alojada.
Con `GENERATE_URL` recibes las URL para distribuirlas tú mismo. Con `EMAIL` o `PHONE_NUMBER`, Fluz envía 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 configura un NIP de la tarjeta — sin descargar app, sin contraseña. El límite de la tarjeta se descuenta de tu cuenta de gasto al 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 u otras tarjetas.
Mira la experiencia del destinatario en acción: [flujo de escritorio](https://test.fluz.app/wp-content/uploads/2026/04/Web-Share-V6.mp4) · [flujo móvil](https://test.fluz.app/wp-content/uploads/2026/04/Mob-Share-F.mp4).
## Disponibilidad y alcance
| Capacidad | 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 | ✅ Compatible |
| 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 de reclamación de 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` | Mutation | Crear uno o más enlaces alojados de tarjetas virtuales |
| `getVCShareLinks` | Query | Listar/inspeccionar enlaces generados previamente |
| `deactivateVCShareLinks` | Mutation | 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`, y tu cuenta debe tener Send Cards habilitado — sin esto, cada 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 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 monetarias enteras. 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 usada para financiar las tarjetas. *Marcado como opcional en el esquema pero requerido en la práctica — si se omite falla la validación.* |
| `daysUntilExpiration` | `Int` | No | Días hasta que el enlace expire. Mínimo 1. Predetermina al valor por defecto del programa (30 días) si se omite. **Esta fecha también se convierte en la fecha de bloqueo/congelación de la tarjeta** — ver [Vencimiento y congelamiento](#expiration--freeze). |
| `recipientListEmail` | `[String]` | Condicional | Requerido y no vacío cuando `shareMethod = EMAIL`. Su 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`. Su 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 correo un enlace a cada destinatario. | `recipientListEmail` requerido; la longitud debe ser igual a `quantity`. |
| `PHONE_NUMBER` | Fluz envía por SMS un enlace a cada destinatario. | `recipientListPhone` requerido; la longitud debe ser igual a `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 de destinatarios 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 propiedad de 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 del lote** y los **ID de visualización** 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]` | Filtra por estado: `PENDING`, `ISSUED`, `USED`, `EXPIRED`. |
| `shareRequestBatchIds` | `[String]` | Devuelve solo enlaces en estos lotes. |
| `shareRequestDisplayIds` | `[String]` | Devuelve solo los enlaces con estos ID de visualización. |
**Flujo recomendado.** En la primera llamada, filtra solo por `shareObjectStatuses`. La respuesta te da los valores `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` | Correo del destinatario, si se entregó por email. |
| `recipientPhone` | `String` | Teléfono del destinatario, si se entregó por SMS. |
| `linkExpirationDate` | `DateTime` | Cuándo vence 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, oferta, cantidad, entrega, financiamiento). |
### 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 puede ser reclamado.
```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 de visualización. |
Obtén los ID de lote desde `getVCShareLinks`.
```json theme={null}
{ "input": { "shareRequestBatchIds": ["ABC123"] } }
```
Devuelve una cadena de confirmación legible, p. ej., `"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 requerido antes de que la tarjeta pueda verse o reclamarse.
Si el destinatario no tiene una dirección de facturación registrada, se le solicita agregar una. *La dirección de facturación es requerida para compras en línea.*
Antes de emitir la tarjeta, el destinatario configura un NIP.
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 se admite) agregar la tarjeta a una billetera móvil.
**¿Ya fue reclamada?** Si el mismo usuario abre un enlace que ya reclamó, ve los datos de su tarjeta. Si un usuario *diferente* abre un enlace que otra persona ya reclamó, se le muestra un estado de acceso denegado después del 2FA.
## Vencimiento y congelamiento
La fecha de vencimiento del enlace cumple una doble función:
* **Vencimiento del enlace** — después de esta fecha, un enlace **no reclamado** ya no se puede reclamar.
* **Congelamiento/bloqueo de la tarjeta** — para una tarjeta **emitida**, esta es la fecha de bloqueo (fin de ese día). Después de esa fecha, la tarjeta se congela y no se puede usar.
* **Vencimiento de la tarjeta** se alinea al fin del mes de la fecha de congelamiento (por ejemplo, una fecha de congelamiento 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 por defecto 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 — varias son negociadas con socios.
| Regla | Predeterminado | Notas |
| --------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ |
| Límite de gasto diario de la cuenta | **\$250,000/día** | Algunos socios tienen un límite personalizado. |
| Buffer en transacciones de restaurantes | **25%** | Un buffer de 25% aplica a todos los programas (para propinas/retenciones en restaurantes). |
| Comercios / categorías restringidas | Específico del programa | Ciertas categorías de comercios están restringidas. |
| Financiamiento | 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 financiamiento, categorías restringidas y soporte) está en la **Guía para Socios — Tarjetas Virtuales con URL alojada**. Pide a tu contacto de Fluz la última versión 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` | La tarjeta emitida ha sido utilizada. |
| `EXPIRED` | El enlace expiró o fue desactivado; ya no se puede reclamar. |
### Errores del enlace mostrados al 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 anticipadamente | "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 faltante/inválido o alcance `CREATE_SHARE_LINK` faltante | Solicitud rechazada (no autorizado). |
| La cuenta no tiene acceso a Send Cards (`send_virtual_cards_enabled`) | Error de permisos que te dirige a tu representante de ventas. |
| 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` faltante/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 envuelven 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 efectivamente requerido 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
La referencia enfocada para `generateVCShareLinks`, si es todo lo que necesitas.
Emite muchas tarjetas a la vez para distribución programática.