Skip to main content
Una sola llamada a purchaseGiftCard compra exactamente una tarjeta de regalo, para una oferta a una tasa. No existe el campo quantity, y una sola llamada nunca se divide entre múltiples ofertas o tasas. Para comprar varias tarjetas, envía la mutación múltiples veces — una por tarjeta, cada una con su propia idempotencyKey única. Cómo cada llamada elige su oferta y tasa depende de si pasas offerId o merchantSlug.

​
Flujo de compra de un vistazo

​
offerId — fija una oferta y tasa específicas

Cuando pasas offerId, la compra queda bloqueada a esa oferta exacta y su tasa. Si esa oferta ya no se puede cumplir (por ejemplo, una oferta con control de inventario que se agotó), la llamada falla — no sustituirá silenciosamente otra oferta. Consulta el error por falta de stock más abajo.

​
merchantSlug — selección automática de la mejor oferta disponible

Cuando pasas merchantSlug (sin offerId), el sistema selecciona la mejor oferta disponible en stock para ese comercio en el momento de cada llamada. Debido a que la selección ocurre por llamada, compras repetidas para el mismo comercio pueden resolverse en ofertas diferentes a medida que cambia la disponibilidad.

​
Ofertas fijas vs. variables e inventario

  • Las ofertas de denominación fija tienen control de inventario por denominación. Una vez que una denominación se agota, deja de estar seleccionable, y cualquier llamada adicional fijada a ella (vía offerId) devuelve un error de falta de stock.
  • Las ofertas variables no tienen limitación de inventario de la misma manera. Por lo general permanecen disponibles y actúan como respaldo cuando una oferta fija/con inventario se agota. Una oferta variable a menudo conlleva una tasa de recompensa diferente (frecuentemente menor) que la oferta fija a la que reemplaza.
📘 Qué sucede cuando compras más tarjetas de las que hay en stock Supongamos que la mejor oferta de un comercio es una oferta fija con control de inventario con solo 8 unidades restantes, y quieres 10 tarjetas (es decir, 10 llamadas separadas a purchaseGiftCard):
  • Usando offerId (fijado a la oferta fija): las primeras 8 llamadas tienen éxito; la 9.ª y 10.ª llamadas fallan con un error de falta de stock. No ocurre ningún respaldo automático a otra oferta o tasa.
  • Usando merchantSlug (selección automática): las primeras 8 llamadas compran en la oferta fija; cuando se agota, las llamadas restantes seleccionan automáticamente la siguiente mejor oferta disponible — que puede ser una oferta variable con una tasa de recompensa menor.
En todos los casos, cada tarjeta se compra de forma atómica en la oferta y tasa resueltas para esa llamada individual — no hay pedidos combinados ni parcialmente cumplidos.

​
Protege tu tasa con minRewardRate

Cuando compras con merchantSlug, usa minRewardRate para establecer un piso de tasa de recompensa. Antes de comprar, el sistema verifica la mejor tasa disponible para el comercio, el monto y el método de pago; si esa tasa está por debajo de tu minRewardRate (o no se puede cotizar ninguna tasa), la llamada falla en lugar de comprar a la tasa inferior. Esta es la forma recomendada de evitar comprar sin querer las tarjetas restantes en una oferta variable de menor tasa después de que se agote una oferta con inventario de mayor tasa.
🚧 minRewardRate solo aplica a compras con merchantSlug. Si proporcionas offerId, se ignora minRewardRate (la oferta — y su tasa — ya están fijas). El piso se evalúa por llamada, así que inclúyelo en cada llamada cuando compres múltiples tarjetas.

​
Error por falta de stock

Cuando una oferta ya no se puede cumplir debido al inventario, la mutación devuelve:
Vuelve a cotizar con getOfferQuote / getMerchants para encontrar la mejor oferta disponible actual antes de reintentar.
📘

​
Qué sucede cuando compras más tarjetas de las que hay en stock Supongamos que la mejor oferta de un comercio es una oferta fija con control de inventario con solo 8 unidades restantes y quieres 10 tarjetas (10 llamadas separadas a purchaseGiftCard):

  • Usando offerId (fijado a la oferta fija): las primeras 8 llamadas tienen éxito a la tasa con inventario; la 9.ª y 10.ª llamadas fallan con GC-0009. No ocurre ningún respaldo automático a otra oferta o tasa.
  • Usando merchantSlug (selección automática): las primeras 8 llamadas compran en la oferta fija a la tasa más alta; cuando se agota, las llamadas restantes seleccionan automáticamente la siguiente mejor oferta disponible — que puede ser una oferta variable con una tasa de recompensa menor.
🚧

​
Protege tu tasa con minRewardRate Al comprar con merchantSlug, establece minRewardRate como un piso de tasa de recompensa. Antes de cada compra, el sistema verifica la mejor tasa disponible para el comercio, el monto y el método de pago; si esa tasa está por debajo de tu minRewardRate (o no se puede cotizar ninguna tasa), la llamada falla en lugar de comprar a la tasa inferior. Esta es la forma recomendada de evitar comprar sin querer las tarjetas restantes en una oferta variable de menor tasa después de que se agote una oferta con inventario de mayor tasa.

minRewardRate se ignora cuando proporcionas offerId (la tasa ya está fija), y se evalúa por llamada — inclúyelo en cada llamada cuando compres múltiples tarjetas.
Para comprobar el inventario antes de comprar, consulta Obtener inventario en ofertas con stock.