> ## 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.

# 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.

<Info>
  **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.
</Info>

<Note>
  **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.
</Note>

<Tip>
  ¿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](/features/send-cards). Esta página es la referencia de API enfocada para las tres operaciones de enlaces para compartir.
</Tip>

## Cómo funciona

1. 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.
2. Fluz crea una solicitud de compartido y una URL alojada por cada enlace solicitado.
3. 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.
4. El destinatario abre el enlace alojado, inicia sesión, completa la verificación y reclama la tarjeta.
5. 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.

```http theme={null}
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`.

```json theme={null}
{
  "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.

```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. 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

```graphql theme={null}
mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}
```

```json theme={null}
{
  "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

```json 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"
  }
}
```

### Ejemplo: enviar enlaces por SMS a destinatarios

```json 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"
      ]
    }
  }
}
```

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

```text theme={null}
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.

```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` 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

```json theme={null}
{
  "input": {
    "shareObjectStatuses": ["PENDING", "ISSUED"]
  }
}
```

```json theme={null}
{
  "input": {
    "shareRequestBatchIds": ["ABC123", "XYZ789"]
  }
}
```

```json theme={null}
{
  "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.

```graphql theme={null}
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

```json theme={null}
{
  "input": {
    "shareRequestBatchIds": ["ABC123"]
  }
}
```

### Respuesta

Devuelve una cadena de confirmación, por ejemplo:

```text theme={null}
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.

1. El destinatario abre el enlace de tarjeta virtual alojado.
2. El destinatario inicia sesión o crea una cuenta a través del flujo de autenticación de Fluz.
3. Los usuarios existentes completan 2FA antes de ver o reclamar la tarjeta.
4. 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.
5. Si la tarjeta aún no ha sido emitida, el destinatario establece un NIP.
6. Fluz emite la tarjeta virtual al destinatario.
7. 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](mailto: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.

<Warning>
  **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.
</Warning>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Visión general de Send Cards" icon="send" href="/features/send-cards">
    La narrativa completa de la función — recorrido del destinatario, reglas del programa y referencia completa de errores.
  </Card>

  <Card title="Crear una orden masiva" icon="layers" href="/features/create-bulk-order">
    Emite muchas tarjetas a la vez para distribución programática.
  </Card>
</CardGroup>