Saltar al contenido principal
Una sola llamada a purchaseGiftCard compra exactamente una tarjeta de regalo, para una oferta a una tasa. No existe un campo quantity, y una sola llamada nunca se divide entre múltiples ofertas o tasas. Para comprar varias tarjetas, envía la mutación varias 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 a simple vista

​
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 una oferta diferente. Consulta el error de falta de stock a continuación.

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

Cuando pasas merchantSlug (sin offerId), el sistema selecciona la mejor oferta disponible con 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 se agota una denominación, ya no se puede seleccionar, y cualquier llamada posterior fijada a ella (vía offerId) devuelve un error de falta de stock.
  • Las ofertas variables no están limitadas por inventario de la misma manera. Normalmente permanecen disponibles y actúan como respaldo cuando una oferta fija/con stock se agota. Una oferta variable a menudo tiene 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 Supón 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 un cambio 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 más baja.
En todos los casos, cada tarjeta se compra de forma atómica con 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 la tasa de recompensa. Antes de comprar, el sistema verifica la mejor tasa disponible para el comercio, monto y 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 stock y tasa más alta.
🚧 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 de falta de stock

Cuando una oferta ya no se puede cumplir por 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

Supón 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 stock; la 9.ª y 10.ª llamadas fallan con GC-0009. No ocurre un cambio 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 más baja.
🚧

​
Protege tu tasa con minRewardRate

Al comprar con merchantSlug, establece minRewardRate como un piso de la tasa de recompensa. Antes de cada compra, el sistema verifica la mejor tasa disponible para el comercio, monto y 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 stock y tasa más alta. 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 verificar el inventario antes de comprar, consulta Obtener inventario en ofertas con stock.