> ## 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.
# Comprar tarjeta de regalo
Una vez que hayas determinado tu oferta preferida, usa la mutación `purchaseGiftCard` para comprar tu tarjeta de regalo. Esta mutación requiere un objeto de entrada `PurchaseGiftCardInput`.
## Mutación de ejemplo
Aquí tienes la forma más rápida de empezar a comprar una tarjeta de regalo. Puedes personalizar tu consulta desde el objeto `UserPurchase`. Consulta la [Referencia de la API](https://storage.googleapis.com/fluz-public-docs/api-reference.html).
```graphql theme={null}
mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
purchaseGiftCard(input: $input) {
purchaseDisplayId
purchaseAmount
giftCard {
giftCardId
status
termsAndConditions
}
}
}
```
## Campos
Los siguientes campos se usan para ejecutar esta mutación:
`idempotencyKey` — Requerido. Un UUID único generado por el cliente para asegurar que una solicitud se procese solo una vez.
`offerId `**o** `merchantSlug` — Requerido. Usa el `offerId` o `merchantSlug` de la consulta [`getOfferQuote`](/get-best-offer) para obtener la mejor oferta. Usar `merchantSlug` comprará automáticamente la mejor tasa de oferta para ese comercio.
`amount` — Requerido. El monto de la tarjeta de regalo que deseas comprar.
***
Solo uno de los siguientes es requerido. También puedes elegir combinar tu saldo de Fluz con otra fuente de fondos.
`exclusiveRateId` — El identificador único para una oferta de tasa exclusiva específica. Cuando se proporciona, fuerza la compra a usar la tasa exclusiva especificada. Si no se proporciona, el sistema seleccionará automáticamente la mejor tasa disponible. El `exclusiveRateId` se puede encontrar en la respuesta de la consulta [`getMerchants`](/get-catalog) para ofertas con tipo `EXCLUSIVE_RATE_OFFER` cuando proporcionas `exclusiveRateId` en tu solicitud de consulta bajo `offers`.
`balanceAmount` — Si quieres pagar tu tarjeta de regalo con tu saldo de Fluz, define aquí el monto del saldo. Puedes usar la consulta [`getWallet`](/check-account-balance) para verificar tus saldos.
`bankAccountId` — Si quieres pagar con una cuenta bancaria, define el ID de la cuenta bancaria.
`bankCardId` — Si quieres pagar con una tarjeta bancaria, define el ID de la tarjeta bancaria.
`paypalVaultId` — Si quieres pagar con una cuenta de PayPal, define el ID de la cuenta de PayPal.
`defaultToBalance` — Si quieres usar tu saldo de Fluz como método de pago de respaldo en caso de que fallen tus otros métodos de pago, establece `defaultToBalance` en `true`. De forma predeterminada, esto está establecido en `true`. Si cambias esta configuración a `false`, el sistema no intentará usar tu saldo de Fluz como método de pago de respaldo.
`minRewardRate` — Si quieres especificar la tasa mínima de recompensa para comprar si se elige la opción `merchantSlug`.
`userCashBalanceId` — Si quieres especificar el saldo en efectivo (cuenta de gasto) que se utilizará para esa compra.
`memo` — Si quieres adjuntar una nota a esta transacción, proporciona un memo de texto libre aquí. Máximo 255 caracteres.
`transactionCategory` — Si quieres categorizar esta transacción, proporciona un nombre de categoría. Las categorías se crean automáticamente en el primer uso y se reutilizan si se pasa el mismo nombre nuevamente.
`attachmentId` — Si quieres adjuntar un archivo a esta transacción, proporciona el ID devuelto por el endpoint de carga. Consulta [Agregar detalles de gastos](/features/add-expense-details).
### Consulta [Agregar detalles de gastos](/features/add-expense-details) para ver todos los detalles sobre cómo subir adjuntos y trabajar con memos y categorías.
## PurchaseGiftCardInput
```json theme={null}
{
"idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
"offerId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
"amount": 987.65,
"balanceAmount": 123.45,
"bankAccountId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
"bankCardId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
"paypalVaultId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
"exclusiveRateId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
"merchantSlug": "xyz789",
"minRewardRate": 5.6,
"userCashBalanceId": "85de1b3e-4e72-462c-8ed1-a6f4982e22f7"
}
```
## Respuesta de ejemplo
Una vez que tu compra esté completa, recibirás una respuesta similar a esta:
```json theme={null}
{
"data": {
"purchaseGiftCard": {
"purchaseId": "255f8245-02c7-4817-901e-15fe265f6968",
"purchaseDisplayId": "1019688",
"purchaseBankCardId": "255f8245-02c7-4817-901e-15fe265f6968",
"bankAccountId": "255f8245-02c7-4817-901e-15fe265f6968",
"purchaseAmount": 123.45,
"fluzpayAmount": 85.0,
"seatRewardValue": 0.05,
"paypalVaultId": "255f8245-02c7-4817-901e-15fe265f6968",
"createdAt": "2007-12-03T10:15:30Z",
"giftCard": {
"giftCardId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
"purchaserUserId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
"endDate": "2007-12-03T10:15:30Z",
"status": "ACTIVE",
"termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for...",
"createdAt": "2007-12-03T10:15:30Z",
"merchant": {
"merchantId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
"name": "Starbucks",
"slug": "starbucks",
"logoUrl": "https://storage.googleapis.com/.../starbucks-logo.jpg",
"faceplateUrl": "https://storage.googleapis.com/.../starbucks-faceplate.png",
"offers": [
{
"offeringMerchantId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
"offerId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
"type": "GIFT_CARD_OFFER",
"deliveryFormat": "CODES",
"barcodeType": "C128",
"hasStockInfo": false,
"offerRates": [
{
"maxUserRewardValue": 5.0,
"cashbackVoucherRewardValue": 1.0,
"boostRewardValue": 0.5,
"displayBoostReward": true,
"denominations": [25, 50, 100],
"allowedPaymentMethods": ["CREDIT_CARD", "PAYPAL"]
}
],
"denominationsType": "VARIABLE",
"stockInfo": []
}
]
}
}
}
}
}
```
### Las tasas de cashback están sujetas a cambio.
Hacemos nuestro mejor esfuerzo para ofrecer siempre a nuestros clientes las mejores ofertas disponibles. Esto significa que nuestras tasas cambian regularmente. Confirma siempre la tasa antes de realizar una compra.
## Comprar más de una tarjeta
Una sola llamada a `purchaseGiftCard` compra exactamente una tarjeta de regalo, en una oferta, a una tasa. No hay un campo de cantidad, y una llamada nunca se divide ni se combina entre ofertas o tasas. Para comprar varias tarjetas, envía la mutación una vez por tarjeta, cada una con su propio `idempotencyKey` único.
Debido a que cada tarjeta es su propia llamada, ordenar más tarjetas de las que una oferta con inventario tiene disponible se resuelve por llamada:
* `offerId `**(oferta fija):** una vez que se agota la oferta con inventario, las llamadas restantes fallan con `GC-0009`. No hay respaldo automático a otra oferta o tasa.
* `merchantSlug `**(selección automática):** las llamadas restantes seleccionan automáticamente la siguiente mejor oferta disponible — a menudo una oferta variable a una tasa de recompensa más baja — a menos que `minRewardRate` bloquee la tasa inferior.
Para el desglose completo por llamada, el patrón de piso de tasa `minRewardRate`, y la respuesta `GC-0009`, consulta [Compra en volumen](/purchase-in-bulk).
### Pedido a gran escala: concurrencia, tiempos de espera y reintentos
Las compras que usan la misma cuenta de Fluz se procesan secuencialmente. Cuando se envían muchas llamadas `purchaseGiftCard` al mismo tiempo contra una sola cuenta, se ponen en cola una detrás de otra, y las llamadas individuales pueden tardar más en responder — ocasionalmente hasta unos minutos bajo alta carga. Las llamadas que no se ponen en cola normalmente responden en segundos.
Para mantener la latencia predecible y evitar fallas falsas al ordenar a gran escala:
* Ritma tus solicitudes concurrentes. En lugar de disparar un lote completo simultáneamente contra una cuenta, envíalo en olas más pequeñas, o distribuye el volumen entre múltiples cuentas. Esto mantiene la latencia por llamada baja.
* Usa un tiempo de espera generoso en el cliente. Fluz no abandona una compra en curso después de unos segundos — una solicitud aún puede estar procesándose legítimamente y devolverá un resultado válido. Un tiempo de espera corto del lado del cliente (por ejemplo, 30 segundos) puede hacer que des por perdida una compra que finalmente tiene éxito. Configura tu tiempo de espera lo suficientemente alto para absorber procesamientos ocasionales de varios minutos bajo carga. Recomendamos 1 minuto.
* Un tiempo de espera del cliente no es una cancelación. Cerrar tu conexión no cancela una solicitud que Fluz ya aceptó; esta continúa procesándose hasta completarse. Trata un tiempo de espera como un resultado desconocido, no como una falla.
* Resuelve los tiempos de espera reintentando con el mismo `idempotencyKey`. Reemite la solicitud idéntica con el mismo `idempotencyKey`. Debido a que la clave garantiza que la compra se procese como máximo una vez, el reintento devuelve la compra original si ya tuvo éxito — no creará un duplicado ni un segundo cargo. Nunca emitas un nuevo `idempotencyKey` para una compra que ya intentaste; hacerlo es lo que produce pedidos duplicados.
### Si una compra superó el tiempo de espera de tu lado y no estás seguro de su resultado, vuelve a intentarla con el mismo `idempotencyKey`, o busca la compra por su ID de compra, antes de reembolsar al usuario final. Una solicitud con tiempo de espera excedido a menudo ya tuvo éxito del lado de Fluz, y el código de la tarjeta de regalo permanece revelable hasta que se reembolsa la compra.
## Próximos pasos
Ahora es momento de revelar los detalles de tu tarjeta de regalo para su uso. Aprende cómo hacerlo aquí:
[Ver tarjetas de regalo](/view-gift-card)