> ## 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.
# Enviar una tarjeta a alguien
> Genera un enlace alojado de tarjeta virtual, observa cómo el destinatario la reclama y gestiona el ciclo de vida del enlace, de extremo a extremo en el sandbox.
Este inicio rápido recorre el ciclo de vida completo de Enviar tarjetas. Crearás una aplicación de staging, acuñarás un token Bearer con alcance, elegirás un programa de tarjeta, recuperarás una cuenta de gasto con fondos, generarás enlaces alojados de tarjetas virtuales, experimentarás el flujo de activación del destinatario, verificarás la emisión y luego desactivarás un enlace no utilizado.
Al final habrás completado con éxito cada operación pública de Enviar tarjetas:
* `generateVCShareLinks`
* `getVCShareLinks`
* `deactivateVCShareLinks`
—todo en el sandbox, donde no se mueven fondos reales de clientes.
**Requisitos previos**
* Una **cuenta de Fluz**: crearás credenciales de API de staging y acuñarás un token de acceso con alcance en los Pasos 1–2 a continuación.
* Las solicitudes van al endpoint GraphQL del **sandbox**. Los enlaces alojados para destinatarios usan la experiencia estándar de activación de Fluz, pero todas las operaciones de API usan tu entorno de staging.
* Tu cuenta debe tener **Enviar tarjetas habilitado** (`send_virtual_cards_enabled`) o cada operación de Enviar tarjetas devolverá un error de permisos.
* Este inicio rápido usa una **Cuenta de gasto** con fondos como la fuente de fondos. Las tarjetas se financian **cuando se reclaman**, no cuando se generan los enlaces.
## Antes de comenzar
Excepto para acuñar tu token (Paso 2), cada solicitud en esta guía se envía a la API GraphQL de Fluz utilizando tu token de acceso Bearer.
```bash Endpoint & headers theme={null}
POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql
Authorization: Bearer
Content-Type: application/json
```
```bash Example request (cURL) theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"query":"query { getVirtualCardOffers { offerId programName rewardValue } }"
}'
```
Cada operación GraphQL a continuación utiliza este endpoint y tu token Bearer. La única excepción es el Paso 2, que intercambia tus credenciales de aplicación por un token de acceso a través del servicio OAuth.
## El flujo completo
Crea una cuenta de Fluz, luego abre la Consola de Desarrollador y crea una aplicación **Staging**.
Cuando se cree tu aplicación, recibirás:
* `clientId`
* `clientSecret`
Copia ambos valores en un lugar seguro. Tu `clientSecret` solo se muestra una vez.
Si aún no has creado una aplicación de staging, consulta [Prepara tus cuentas](/get-started/prepare-accounts).
Envía tus credenciales de aplicación al servicio OAuth para generar un token de acceso de usuario de corta duración.
Este token autoriza cada operación de Enviar tarjetas que sigue.
```bash Mint access token (cURL) theme={null}
curl -X POST https://oauth-service.fluzapp.com/graphql \
-H "Content-Type: application/json" \
-d '{
"query":"mutation ($clientId:String!,$clientSecret:String!,$scopes:[Scope!]!){generateUserAccessToken(clientId:$clientId,clientSecret:$clientSecret,scopes:$scopes){accessToken expiresIn scopes}}",
"variables":{
"clientId":"",
"clientSecret":"",
"scopes":[
"CREATE_SHARE_LINK",
"LIST_PAYMENT"
]
}
}'
```
```json Response theme={null}
{
"data": {
"generateUserAccessToken": {
"accessToken": "eyJhbGciOi...",
"expiresIn": 3600,
"scopes": [
"CREATE_SHARE_LINK",
"LIST_PAYMENT"
]
}
}
}
```
Guarda el `accessToken` devuelto.
Lo usarás como:
```http theme={null}
Authorization: Bearer
```
para cada solicitud restante.
`CREATE_SHARE_LINK` autoriza cada operación de Enviar tarjetas.
Este inicio rápido también solicita `LIST_PAYMENT` para que puedas recuperar la Cuenta de gasto que financia tus tarjetas alojadas.
**Nunca expongas tu** `clientSecret` **dentro de un navegador o aplicación móvil.**
Genera tokens Bearer del lado del servidor y reenvía solo el token de acceso a tu cliente.
Las tarjetas virtuales alojadas se financian desde una de tus **Cuentas de gasto**.
A diferencia de las tarjetas virtuales regulares, **no se reservan fondos cuando se genera el enlace.**
En su lugar, la Cuenta de gasto seleccionada se carga solo cuando el destinatario reclama la tarjeta con éxito.
Recupera tus Cuentas de gasto disponibles.
```graphql Query theme={null}
query GetSpendAccounts {
getSpendAccounts {
userCashBalanceId
nickname
availableBalance
currency
}
}
```
```json Response theme={null}
{
"data": {
"getSpendAccounts": [
{
"userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"nickname": "Primary Spend Account",
"availableBalance": 5000,
"currency": "USD"
}
]
}
}
```
Guarda el `userCashBalanceId`.
Proporcionarás este valor al generar tus enlaces de tarjeta alojada.
La Cuenta de gasto seleccionada debe pertenecer a tu cuenta y debe contener fondos suficientes **cuando el destinatario reclame la tarjeta**. Si no hay suficiente saldo disponible en el momento de la reclamación, la emisión de la tarjeta falla.
Cada tarjeta alojada se emite contra una **oferta** de tarjeta virtual.
La oferta determina el programa emisor, las recompensas disponibles y los límites que se aplican a cada tarjeta generada.
Recupera las ofertas disponibles para tu cuenta.
```graphql Query theme={null}
query GetVirtualCardOffers {
getVirtualCardOffers {
offerId
programName
rewardValue
programLimits {
dailyLimit
weeklyLimit
monthlyLimit
}
}
}
```
```json Response theme={null}
{
"data": {
"getVirtualCardOffers": [
{
"offerId": "11111111-2222-3333-4444-555555555555",
"programName": "Virtual Card",
"rewardValue": "1.5%",
"programLimits": {
"dailyLimit": 500,
"weeklyLimit": 2000,
"monthlyLimit": 5000
}
}
]
}
}
```
Guarda el `offerId` del programa contra el cual deseas emitir.
**La oferta seleccionada debe estar:**
* activa
* habilitada para compartir
Si la generación falla porque la oferta no es elegible para Enviar tarjetas, confirma con tu representante de Fluz qué ofertas están habilitadas para uso compartido alojado.
Ya estás listo para crear enlaces alojados de Enviar tarjeta.
Cada enlace generado representa **una futura tarjeta virtual**.
En esta etapa:
* No se ha emitido ninguna tarjeta.
* No se han retirado fondos.
* Cada enlace comienza en el estado `PENDING`.
La Cuenta de gasto seleccionada se carga **solo cuando un destinatario reclama un enlace**.
Para este inicio rápido generaremos **dos** enlaces:
* **Enlace A**: lo reclamarás como destinatario.
* **Enlace B**: lo dejarás sin reclamar para poder revocarlo más tarde.
```graphql Mutation theme={null}
mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
generateVCShareLinks(input: $input) {
shareLinks
}
}
```
```json Variables theme={null}
{
"input": {
"cardLimit": 25,
"offerId": "",
"quantity": 2,
"daysUntilExpiration": 14,
"shareMethod": "GENERATE_URL",
"userCashBalanceId": ""
}
}
```
```json Response theme={null}
{
"data": {
"generateVCShareLinks": {
"shareLinks": [
"https://fluz.app/virtual-prepaid-card/3f8ac...c1",
"https://fluz.app/virtual-prepaid-card/9b2dd...77"
]
}
}
}
```
La respuesta devuelve una URL de activación alojada por cada tarjeta generada.
Guarda ambas URLs.
Nos referiremos a ellas como:
* **Enlace A**
* **Enlace B**
a lo largo del resto de este inicio rápido.
### Comprender la configuración de generación
El monto cargado en cada tarjeta alojada cuando se reclama.
Cada tarjeta generada recibe su propio límite independiente.
El programa de tarjeta virtual alojada contra el cual emitir.
La oferta debe estar activa y habilitada para Enviar tarjetas.
La cantidad de enlaces alojados a generar.
Se crea una solicitud de uso compartido y una URL alojada por cada cantidad solicitada.
Controla cómo los destinatarios reciben sus enlaces.
* `GENERATE_URL` devuelve URLs alojadas para que las distribuyas.
* `EMAIL` envía correos electrónicos a los destinatarios automáticamente.
* `PHONE_NUMBER` envía a los destinatarios un SMS.
La Cuenta de gasto que financia cada tarjeta generada.
Aunque este campo parece opcional en el esquema GraphQL, en la práctica es obligatorio.
Cuánto tiempo tienen los destinatarios para reclamar el enlace alojado.
Si se omite, se usa el valor predeterminado del programa.
La fecha de vencimiento resultante también se convierte en la fecha de bloqueo de la tarjeta emitida.
En lugar de distribuir tú mismo las URLs alojadas, Fluz puede enviar a cada destinatario su propio enlace de activación.
### Correo electrónico
```json theme={null}
{
"input": {
"cardLimit": 25,
"offerId": "",
"quantity": 2,
"shareMethod": "EMAIL",
"recipientListEmail": [
"alice@example.com",
"bob@example.com"
],
"userCashBalanceId": ""
}
}
```
### SMS
```json theme={null}
{
"input": {
"cardLimit": 25,
"offerId": "",
"quantity": 2,
"shareMethod": "PHONE_NUMBER",
"recipientListPhone": [
"+18883606660",
"+18885551234"
],
"userCashBalanceId": ""
}
}
```
La longitud de la lista de destinatarios **debe ser exactamente igual** a `quantity`.
Si no coinciden, la validación falla y **no se crean enlaces**.
Los números de teléfono deben:
* incluir el código de país
* no contener espacios
* proporcionarse como cadenas
Ejemplo:
```text theme={null}
+18883606660
```
**Generar enlaces alojados no reserva fondos.**
Si la Cuenta de gasto seleccionada no contiene saldo disponible suficiente cuando el destinatario reclama la tarjeta, la emisión de la tarjeta falla.
**La respuesta de generación intencionalmente solo devuelve las URLs alojadas.**
**No** devuelve:
* `shareRequestBatchId`
* `shareRequestDisplayId`
Los recuperarás en el siguiente paso.
Aunque ya tienes las URLs alojadas, por lo general también querrás los registros subyacentes de solicitud de uso compartido.
Estos contienen:
* estado del ciclo de vida
* identificadores de lote
* IDs de visualización
* IDs de tarjetas virtuales emitidas
* información de vencimiento
Inmediatamente después de la generación, recupera tus solicitudes de uso compartido pendientes.
```graphql Query theme={null}
query GetVCShareLinks($input: GetVCShareLinksInput!) {
getVCShareLinks(input: $input) {
shareRequestBatchId
shareRequestDisplayId
shareObjectStatus
linkExpirationDate
virtualCardId
linkUrl
}
}
```
```json Variables theme={null}
{
"input": {
"shareObjectStatuses": [
"PENDING"
]
}
}
```
```json Response theme={null}
{
"data": {
"getVCShareLinks": [
{
"shareRequestBatchId": "BATCH123",
"shareRequestDisplayId": "SR-000001",
"shareObjectStatus": "PENDING",
"virtualCardId": null,
"linkExpirationDate": "2026-08-01T00:00:00Z",
"linkUrl": "https://fluz.app/virtual-prepaid-card/3f8ac...c1"
},
{
"shareRequestBatchId": "BATCH123",
"shareRequestDisplayId": "SR-000002",
"shareObjectStatus": "PENDING",
"virtualCardId": null,
"linkExpirationDate": "2026-08-01T00:00:00Z",
"linkUrl": "https://fluz.app/virtual-prepaid-card/9b2dd...77"
}
]
}
}
```
Haz coincidir cada `linkUrl` devuelto con las URLs devueltas durante la generación.
Guarda:
* el `shareRequestBatchId` compartido
* ambos valores de `shareRequestDisplayId`
Los usarás más tarde al desactivar el enlace no utilizado.
En este punto, ambos enlaces deberían tener:
```text theme={null}
Status: PENDING
Virtual Card ID: null
```
lo que confirma que:
* los enlaces se crearon con éxito
* ningún destinatario los ha reclamado aún
* no se han emitido tarjetas virtuales
Abre el **Enlace A** en tu navegador.
Esta es exactamente la experiencia que ve tu destinatario.
El flujo alojado guía a los destinatarios a través de la activación de la tarjeta sin requerir ninguna integración de API.
Durante la activación el destinatario:
1. Abre la página de activación alojada.
2. Inicia sesión o crea una cuenta de Fluz.
3. Completa la verificación de identidad.
4. Completa la autenticación de dos factores.
5. Agrega una dirección de facturación si aún no hay una registrada.
6. Crea un PIN de la tarjeta.
7. Recibe su tarjeta virtual alojada.
Solo después del paso final, Fluz:
* emite la tarjeta virtual
* la financia desde tu Cuenta de gasto
* la asigna al destinatario
El destinatario se convierte en el titular autorizado de **solo esa tarjeta**.
Ellos **no** obtienen acceso a:
* tu cuenta de Fluz
* tus Cuentas de gasto
* tus saldos
* cualquier otra tarjeta generada
Una vez emitida, el destinatario puede:
* ver la tarjeta
* gastar en línea
* agregarla a Apple Pay o Google Wallet (donde sea compatible)
* ver transacciones futuras
**Deja el Enlace B sin tocar.**
Lo usaremos para demostrar la revocación del enlace en la siguiente sección.
Después de que el destinatario reclame el **Enlace A**, recupera nuevamente las solicitudes de uso compartido.
Esta vez verás que el enlace reclamado pasa de `PENDING` a `ISSUED`.
```graphql Query theme={null}
query GetVCShareLinks($input: GetVCShareLinksInput!) {
getVCShareLinks(input: $input) {
shareRequestDisplayId
shareObjectStatus
virtualCardId
linkUrl
}
}
```
```json Variables theme={null}
{
"input": {
"shareRequestBatchIds": [
"BATCH123"
]
}
}
```
```json Response theme={null}
{
"data": {
"getVCShareLinks": [
{
"shareRequestDisplayId": "SR-000001",
"shareObjectStatus": "ISSUED",
"virtualCardId": "c8dbe6d8-2f2f-4c90-8d7e-15ef5b06e387",
"linkUrl": "https://fluz.app/virtual-prepaid-card/3f8ac...c1"
},
{
"shareRequestDisplayId": "SR-000002",
"shareObjectStatus": "PENDING",
"virtualCardId": null,
"linkUrl": "https://fluz.app/virtual-prepaid-card/9b2dd...77"
}
]
}
}
```
Tus dos enlaces ahora deberían estar en diferentes estados de ciclo de vida.
| Enlace | Estado esperado | Significado |
| ------------ | --------------- | -------------------------------------------------------------------------------- |
| **Enlace A** | `ISSUED` | El destinatario reclamó la tarjeta con éxito y se ha creado una tarjeta virtual. |
| **Enlace B** | `PENDING` | El enlace aún no ha sido reclamado. |
La aparición de un `virtualCardId` confirma que la emisión de la tarjeta se ha completado con éxito.
Cada Enviar tarjeta alojada progresa a través de uno de cuatro estados del ciclo de vida.
| Estado | Significado |
| --------- | -------------------------------------------------------------------------------- |
| `PENDING` | El enlace alojado se ha generado pero aún no ha sido reclamado. |
| `ISSUED` | El destinatario reclamó el enlace con éxito y recibió una tarjeta virtual. |
| `USED` | La tarjeta emitida ha completado al menos una transacción. |
| `EXPIRED` | El enlace alojado expiró de forma natural o se desactivó antes de ser reclamado. |
Solo los enlaces en estado `PENDING` se pueden desactivar.
Una vez que una tarjeta alcanza `ISSUED`, desactivar el enlace original **no** revoca la tarjeta.
Supón que el segundo destinatario nunca necesitó su tarjeta, o que se generó un lote por accidente.
Puedes revocar cualquier enlace alojado **no reclamado** usando cualquiera de:
* `shareRequestBatchIds`
* `shareRequestDisplayIds`
Para este inicio rápido desactivaremos solo el **Enlace B** usando su ID de visualización.
```graphql Mutation theme={null}
mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
deactivateVCShareLinks(input: $input)
}
```
```json Variables theme={null}
{
"input": {
"shareRequestDisplayIds": [
"SR-000002"
]
}
}
```
```json Response theme={null}
{
"data": {
"deactivateVCShareLinks": "1 share requests successfully deactivated!"
}
}
```
La desactivación impide de inmediato que el enlace alojado sea reclamado alguna vez.
Si un destinatario abre el enlace más tarde, recibirá una experiencia de expirado o revocado en lugar del flujo de activación.
La desactivación solo afecta a enlaces **no reclamados**.
Si un destinatario ya reclamó una tarjeta (`ISSUED` o `USED`), el enlace alojado ya no se puede usar para revocarla.
Para detener el gasto en una tarjeta emitida, usa los controles apropiados del ciclo de vida de la tarjeta virtual, como [Bloquear tarjeta virtual](/features/lock-virtual-card).
Recupera las solicitudes de uso compartido una última vez.
```graphql Query theme={null}
query GetVCShareLinks($input: GetVCShareLinksInput!) {
getVCShareLinks(input: $input) {
shareRequestDisplayId
shareObjectStatus
virtualCardId
}
}
```
```json Variables theme={null}
{
"input": {
"shareRequestBatchIds": [
"BATCH123"
]
}
}
```
```json Response theme={null}
{
"data": {
"getVCShareLinks": [
{
"shareRequestDisplayId": "SR-000001",
"shareObjectStatus": "ISSUED",
"virtualCardId": "c8dbe6d8-2f2f-4c90-8d7e-15ef5b06e387"
},
{
"shareRequestDisplayId": "SR-000002",
"shareObjectStatus": "EXPIRED",
"virtualCardId": null
}
]
}
}
```
Ya has ejercitado el ciclo de vida completo de Enviar tarjetas.
| Enlace | Estado final | Resultado |
| ------------ | ------------ | ------------------------------------------------------ |
| **Enlace A** | `ISSUED` | Reclamado y emitido con éxito a un destinatario. |
| **Enlace B** | `EXPIRED` | Revocado con éxito antes de que pudiera ser reclamado. |
En este punto has utilizado con éxito las tres operaciones públicas de Enviar tarjetas:
* ✅ `generateVCShareLinks`
* ✅ `getVCShareLinks`
* ✅ `deactivateVCShareLinks`
## Listo 🎉
Has completado el ciclo de vida completo de Enviar tarjetas alojadas: desde la generación hasta la activación por parte del destinatario, el seguimiento del ciclo de vida y la revocación del enlace.
En el camino:
* Generaste enlaces alojados de tarjetas virtuales.
* Seleccionaste la Cuenta de gasto que financia las tarjetas de los destinatarios.
* Recuperaste y seguiste registros de solicitudes de uso compartido.
* Reclamaste una tarjeta alojada como destinatario.
* Verificaste la transición de `PENDING` a `ISSUED`.
* Revocaste un enlace alojado no utilizado.
* Confirmaste el estado final `EXPIRED`.
Desde aquí puedes explorar flujos de trabajo más avanzados de Enviar tarjetas.
Experiencia del destinatario, reglas del programa, estados del ciclo de vida y referencia completa de errores.
La referencia detallada de la API para cada operación de Enviar tarjetas.
Recupera y gestiona las Cuentas de gasto utilizadas para financiar tarjetas alojadas.
Bloquea y gestiona tarjetas después de que se hayan emitido a los destinatarios.
**¿Quieres saber más?**
Contáctanos en [support@fluz.app](mailto:support@fluz.app) para hablar con nuestros expertos o solicitar una demostración.