purchaseGiftCard para comprar tu tarjeta de regalo. Esta mutación requiere un objeto de entrada PurchaseGiftCardInput.
Mutación de ejemplo
Esta es la forma más rápida de comenzar a comprar una tarjeta de regalo. Puedes personalizar tu consulta desde el objetoUserPurchase. Consulta la Referencia del API.
Campos
Requeridos
idempotencyKey — Un UUID único generado por el cliente para asegurar que una solicitud se procese solo una vez.
offerId o merchantSlug — Usa el offerId o el merchantSlug de la consulta getOfferQuote para obtener la mejor oferta. Usar el merchantSlug comprará automáticamente la mejor tasa de oferta para ese comercio.
amount — El monto de la tarjeta de regalo que deseas comprar.
Selección de tasa
exclusiveRateId — El identificador único para una oferta de tasa exclusiva específica. Cuando se proporciona, esto 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 para ofertas con tipo EXCLUSIVE_RATE_OFFER cuando proporcionas exclusiveRateId en tu solicitud de consulta bajo offers.
minRewardRate — Si deseas especificar la tasa mínima de recompensa a comprar cuando se elige la opción merchantSlug.
Pago
Se requiere al menos una fuente de fondos. También puedes optar por combinar tu saldo de Fluz con otra fuente de fondos.balanceAmount — Si deseas pagar tu tarjeta de regalo con tu saldo de Fluz, define aquí el monto del saldo. Puedes usar la consulta getWallet para verificar tus saldos.
userCashBalanceId — La cuenta de gasto desde la cual se toma balanceAmount. Pásala explícitamente siempre que tu cuenta tenga más de una cuenta de gasto. Si se omite, Fluz toma fondos de la cuenta de gasto marcada isDefault: true. Esto es un modificador de balanceAmount, no una fuente de fondos alternativa — consulta Elegir una cuenta de gasto.
bankAccountId — Si deseas pagar con una cuenta bancaria externa vinculada, define el ID de la cuenta bancaria. Esto no es una cuenta de gasto.
bankCardId — Si deseas pagar con una tarjeta bancaria, define el ID de la tarjeta bancaria.
paypalVaultId — Si deseas pagar con una cuenta de PayPal, define el ID de la cuenta de PayPal.
defaultToBalance — Si deseas usar tu saldo de Fluz como método de pago de respaldo en caso de que tus otros métodos de pago fallen, establece defaultToBalance en true. De forma predeterminada, esto está configurado en true. Si cambias esta configuración a false, el sistema no intentará usar tu saldo de Fluz como método de respaldo.
Detalles de gasto
memo — Si deseas adjuntar una nota a esta transacción, proporciona aquí un memo de texto libre. Máximo 255 caracteres.
transactionCategory — Si deseas 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 vuelve a pasar el mismo nombre.
attachmentId — Si deseas adjuntar un archivo a esta transacción, proporciona el ID devuelto por el endpoint de carga. Consulta Agregar detalles de gastos.
Consulta Agregar detalles de gastos para ver todos los detalles sobre cómo subir archivos adjuntos y trabajar con memos y categorías.
PurchaseGiftCardInput
Elegir una cuenta de gasto
Una cuenta de gasto es una cuenta de saldo en efectivo dentro de Fluz que contiene los fondos de los que se extrae una compra. Tu cuenta puede tener varias — por ejemplo, “Cuenta principal”, “Operaciones” o “Cliente A” — cada una con su propio apodo y su propio saldo. Consulta Cuentas de gasto para el modelo completo.“Cuenta de gasto”, “saldo en efectivo” y
UserCashBalance se refieren al mismo objeto.El producto lo muestra como una cuenta de gasto. El API nombra el tipo UserCashBalance, por lo que el campo en esta mutación es userCashBalanceId — no accountId. Ten en cuenta que bankAccountId no está relacionado: se refiere a una cuenta bancaria vinculada externa, no a una cuenta de gasto.Qué hace cada campo
Cuando financias una compra desde tu saldo de Fluz, dos campos trabajan juntos:
Estos no son mutuamente excluyentes.
userCashBalanceId no tiene efecto a menos que la compra use saldo — ya sea mediante balanceAmount o mediante un respaldo defaultToBalance.
Comportamiento predeterminado cuando se omite userCashBalanceId
Si omites userCashBalanceId, Fluz toma fondos de la cuenta de gasto marcada isDefault: true.
Para mover fondos entre cuentas de gasto — por ejemplo, para desbloquear un pedido que extrae de la cuenta equivocada — consulta Transferir fondos entre cuentas de gasto. Las transferencias internas se liquidan de inmediato.
Paso 1 — Recupera tus IDs de cuenta de gasto
Usa la consultagetUserCashBalances para listar tus cuentas de gasto. Esto requiere el alcance LIST_PAYMENT.
userCashBalanceId de la cuenta desde la que planeas gastar. El ID es estable, por lo que puedes guardarlo en configuración en lugar de buscarlo en cada compra — aunque deberías verificar availableCashBalance antes de ejecuciones de alto volumen.
Consulta Obtener cuentas de gasto para la referencia completa de campos, opciones de filtrado y paginación.
Paso 2 — Pasa la cuenta de gasto en la compra
defaultToBalance: false evita cualquier respaldo implícito, por lo que la compra extrae de la cuenta de gasto que nombraste o falla limpiamente. En un flujo automatizado de pedidos, este suele ser el comportamiento que deseas.
Dividir una compra entre saldo y otra fuente de fondos
userCashBalanceId delimita solo la porción de saldo de una compra. Para pagar una parte desde una cuenta de gasto y el resto desde una tarjeta bancaria vinculada:
La selección de cuenta de gasto no se limita a tarjetas de regalo.
Las tarjetas virtuales también se financian desde una cuenta de gasto — consulta Crear tarjeta virtual. Los depósitos también llegan a una cuenta de gasto específica; consulta Depositar fondos.Respuesta de ejemplo
Una vez que se complete tu compra, recibirás una respuesta similar a esta:Las tasas de cashback están sujetas a cambio.
Hacemos todo lo posible por ofrecer siempre a nuestros clientes las mejores ofertas disponibles. Esto significa que nuestras tasas cambian con regularidad. Siempre confirma la tasa antes de realizar una compra.Comprar más de una tarjeta
Una sola llamada apurchaseGiftCard 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 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.
Dado que cada tarjeta es su propia llamada, ordenar más tarjetas de las que una oferta con inventario puede abastecer se resuelve por llamada:
offerId(oferta fijada): una vez que se agota la oferta con inventario, las llamadas restantes fallan conGC-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 con una tasa de recompensa menor — a menos queminRewardRatebloquee la tasa más baja.
minRewardRate y la respuesta GC-0009, consulta Compra en volumen.
Pedidos a gran escala: concurrencia, tiempos de espera y reintentos
Las compras que extraen de la misma cuenta de Fluz se procesan secuencialmente. Cuando se envían muchas llamadaspurchaseGiftCard al mismo tiempo contra una sola cuenta, se encolan una detrás de otra, y llamadas individuales pueden tardar más en responder — ocasionalmente hasta unos minutos bajo alta carga. Las llamadas que no se encolan suelen responder en segundos.
Para mantener la latencia predecible y evitar fallas falsas al ordenar a gran escala:
- Ritma tus solicitudes concurrentes. En lugar de disparar todo un lote 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 legítimamente en procesamiento y devolverá un resultado válido. Un tiempo de espera corto del lado del cliente (por ejemplo, 30 segundos) puede hacer que renuncies a una compra que finalmente tiene éxito. Configura tu tiempo de espera lo suficientemente alto como para absorber procesamientos ocasionalmente 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 haya aceptado; esta continúa procesándose hasta completarse. Trata un tiempo de espera como un resultado desconocido, no como una falla.
- Resuelve tiempos de espera reintentando con el mismo
idempotencyKey. Vuelve a emitir la solicitud idéntica con elidempotencyKeyidéntico. 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 nuevoidempotencyKeypara una compra que ya intentaste; hacerlo es lo que produce pedidos duplicados.
idempotencyKey, o busca la compra por su ID de compra, antes de reembolsar al usuario final. Una solicitud que agotó el tiempo de espera a menudo ya tuvo éxito del lado de Fluz, y el código de la tarjeta de regalo sigue siendo revelable hasta que se reembolsa la compra.