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

# Ver tarjetas de regalo

getGiftCards, revealGiftCardByGiftCardId

Después de comprar una tarjeta de regalo, debes hacer una llamada a la API para revelar los detalles de la tarjeta. Sigue estos pasos para recuperar la información necesaria:

1. **Recuperar la lista de órdenes de tarjetas de regalo** — Puedes omitir este paso si acabas de comprar una tarjeta de regalo y ya tienes el `giftCardId`.
2. **Revelar los detalles de la tarjeta de regalo** — Usa la mutación `revealGiftCardByGiftCardId` para revelar los detalles de canje de la tarjeta de regalo.

## Paso 1: Recuperar la lista de órdenes de tarjetas de regalo

> 📘 Conciliación de tarjetas de regalo con tus órdenes
>
> `getGiftCards` devuelve `purchaseId` (el mismo UUID devuelto por `purchaseGiftCard` y `getUserPurchases`), `purchaseDisplayId` (el ID corto de la transacción de Fluz, p. ej. `1047283`), y el valor de la orden mediante `purchaseValue` / `currentValue` / `currency`. Úsalos para mapear cada `giftCardId` a su orden y monto de origen sin tener que revelar cada tarjeta.

Para obtener una lista de las tarjetas de regalo ordenadas en tu cuenta, usa la consulta `getGiftCards`. Esta llamada devuelve una lista de tarjetas de regalo con detalles básicos, incluido el `giftCardId`. Necesitarás este ID para revelar los detalles de una tarjeta de regalo.

### Consulta de ejemplo

```graphql theme={null}
query GetGiftCards {
  getGiftCards(
    paginate: { limit: 20, offset: 0 }
  ) {
    giftCardId
    purchaseId
    purchaseDisplayId
    purchaserUserId
    endDate
    status
    purchaseValue
    currentValue
    currency
    createdAt
    deliveryFormat
    termsAndConditions
    merchant {
      merchantId
      name
      slug
    }
  }
}
```

### Argumentos de la consulta

Se usan los siguientes argumentos para ejecutar esta consulta:

* `status` — Si quieres filtrar las tarjetas de regalo por estado.
* `userCashBalanceId` — Si quieres filtrar tarjetas de regalo por el saldo en efectivo (cuenta de gasto).
* `paginate` — Campos de paginación
  * `paginate.limit` — Cantidad máxima de tarjetas de regalo por página
  * `paginate.offset` — La cantidad de registros que se debe omitir

### Respuesta de ejemplo

```json theme={null}
{
  "data": {
    "getGiftCards": [
      {
        "giftCardId": "7c57c381-4b19-49e4-bbb0-404a45166ee4",
        "purchaseId": "785f57ff-f756-4f5c-afca-b896881e3e87",
        "purchaseDisplayId": "1047283",
        "purchaserUserId": "7c57c381-4b19-49e4-bbb0-404a45166ee4",
        "endDate": "2007-12-03T10:15:30Z",
        "status": "ACTIVE",
        "purchaseValue": 25,
        "currentValue": 25,
        "currency": "USD",
        "createdAt": "2007-12-03T10:15:30Z",
        "deliveryFormat": "PIN_WITH_URL",
        "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for...",
        "merchant": {
          "merchantId": "123",
          "name": "Merchant",
          "slug": "merchant"
        }
      }
    ]
  }
}
```

### Campos de la respuesta

`purchaseId` — El UUID de la compra que creó esta tarjeta de regalo. Úsalo para conciliar una tarjeta de regalo con el `purchaseId` que almacenaste al llamar a `purchaseGiftCard` / desde `getUserPurchases`. Devuelve `null` si no se encuentra una compra asociada.

`purchaseDisplayId` — El ID corto y legible de la transacción de Fluz para la compra (p. ej. `1047283`). Este es el ID que el soporte de Fluz referencia para revisiones manuales y en exportaciones. Devuelve `null` si no se encuentra una compra asociada.

`purchaseValue` — El valor (denominación / valor nominal) al que se compró la tarjeta de regalo, en la moneda de la tarjeta. Úsalo para conciliar montos de órdenes.

`currentValue` — El saldo restante en la tarjeta de regalo, en la moneda de la tarjeta. Para tarjetas de un solo uso, normalmente es igual a `purchaseValue`.

`currency` — El código de moneda ISO del valor de la tarjeta de regalo (p. ej. `USD`).

`deliveryFormat` — El formato de entrega de la oferta bajo la cual se compró esta tarjeta de regalo. Uno de `URL`, `CODES`, `PIN_AS_CODE`, `PIN_WITH_URL` o `CODE_WITH_PREFIX`.

`termsAndConditions` — El texto de términos y condiciones de la oferta bajo la cual se compró esta tarjeta de regalo (lenguaje legal, restricciones, políticas de expiración). Esto corresponde a los TyC vigentes al momento de la oferta, que pueden diferir de los TyC de la oferta actualmente activa del comercio — misma lógica que `deliveryFormat`.

> 📘 Prefiere `deliveryFormat` de `getGiftCards` sobre `getMerchants`
>
> La oferta activa de un comercio puede cambiar con el tiempo. El formato bajo el cual se compró la tarjeta de regalo puede diferir de la oferta activa actual del comercio, así que siempre usa el `deliveryFormat` devuelto por `getGiftCards` al decidir cómo mostrar los detalles de canje de `revealGiftCardByGiftCardId`.

## Paso 2: Revelar detalles de la tarjeta de regalo

Una vez que hayas recuperado la lista completa de órdenes de tarjetas de regalo, puedes revelar los detalles de cada tarjeta de regalo, incluido el código de la tarjeta y otra información, usando la mutación `revealGiftCardByGiftCardId`.

### Entrada

La mutación `revealGiftCardByGiftCardId` solo requiere un argumento de entrada `giftCardId` para devolver tus detalles de canje de la tarjeta de regalo como respuesta.

### Mutación de ejemplo

```graphql theme={null}
mutation RevealGiftCardByGiftCardId {
  revealGiftCardByGiftCardId(
    giftCardId: "86dd5fcf-fea3-4531-aa5d-1d196957f7d7"
  ) {
    code
    pin
    url
    termsAndConditions
  }
}
```

### Respuesta de ejemplo

```json theme={null}
{
  "data": {
    "revealGiftCardByGiftCardId": {
      "code": "9877890000000000",
      "pin": "2014",
      "url": null,
      "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
    }
  }
}
```

> 📘 No todas las tarjetas de regalo de los comercios tienen códigos, PIN y URL
>
> Dependiendo del comercio y del socio, los detalles de la tarjeta de regalo pueden variar. Algunos comercios usan un código alfanumérico y no proporcionan un PIN con su tarjeta de regalo. Algunos comercios o socios solo proporcionan una URL en lugar de un código y PIN.
>
> Fluz siempre transmitirá toda la información que recibimos de los comercios en cada orden de tarjeta de regalo.

## Estrategia de sondeo recomendada

Si los detalles de la tarjeta de regalo no se devuelven inmediatamente, puedes sondear el endpoint de Reveal Gift Card usando una estrategia de backoff exponencial. Recomendación inicial:

* **Demora inicial:** 300 ms
* **Estrategia de backoff:** Exponencial (p. ej. 300 ms → 600 ms → 1200 ms → 2400 ms → …)
* **Demora máxima:** 180000 ms (3 minutos)
* Deja de sondear una vez que los detalles de la tarjeta de regalo se devuelvan correctamente

Este enfoque equilibra la capacidad de respuesta con la carga del sistema y ayuda a prevenir tiempos de espera innecesarios o solicitudes excesivas.