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 objetoUserPurchase. Consulta la Referencia de la API.
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 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 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 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.
Consulta Agregar detalles de gastos para ver todos los detalles sobre cómo subir adjuntos y trabajar con memos y categorías.
PurchaseGiftCardInput
Respuesta de ejemplo
Una vez que tu compra esté completa, recibirás una respuesta similar a esta: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 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 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 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 a una tasa de recompensa más baja — a menos queminRewardRatebloquee la tasa inferior.
minRewardRate, y la respuesta GC-0009, consulta Compra en volumen.
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 llamadaspurchaseGiftCard 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 mismoidempotencyKey. 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.