> ## 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.

# Compra masiva de tarjetas de regalo

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

![](https://files.readme.io/bf6ad80159ab3e0beecb76d51f498a4093b793bf7368288abe62e5c81b2b36c5-diagram.svg)

### `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:

```json theme={null}
{
  "code": "GC-0009",
  "message": "This offer is currently out of stock. Please select a different amount or try again later."
}
```

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](/get-inventory).