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

# Solicitudes de idempotencia

Una llamada u operación de API es idempotente si produce el mismo resultado sin importar cuántas veces se ejecute. Esto garantiza que las llamadas repetidas no causen efectos secundarios no deseados, protegiendo contra solicitudes duplicadas accidentales.

La API de Fluz admite solicitudes de idempotencia para proteger contra la duplicación accidental de operaciones. Al usar una clave de idempotencia única generada por el cliente, la API garantiza que la misma solicitud no se procese varias veces dentro de una ventana de 10 minutos si se proporciona la misma clave de idempotencia.

## Cómo funciona

Cuando se proporciona una clave de idempotencia con una solicitud:

* El servidor almacena en caché el cuerpo de la respuesta inicial y su código de estado.
* Si se recibe una solicitud duplicada con la misma clave de idempotencia y código de respuesta, la API devolverá el resultado en caché en lugar de volver a ejecutar la operación, especialmente si ocurre un error dentro de la operación. Este mecanismo ayuda a prevenir el procesamiento duplicado no intencional al devolver resultados consistentes incluso en escenarios de error.

## Generación de claves de idempotencia únicas

Los clientes son responsables de crear y actualizar sus claves de idempotencia. Para garantizar la unicidad:

* Recomendamos encarecidamente usar UUID V4, que se pueden generar con bibliotecas como estas: [https://github.com/uuidjs/uuid](https://github.com/uuidjs/uuid)
* Como práctica recomendada, las claves de idempotencia deben expirar después de cierto tiempo para evitar su reutilización y garantizar la unicidad de las solicitudes. Fluz hace expirar cada clave de idempotencia única después de 10 minutos.

### Los clientes necesitarán:

1. Una operación para generar y almacenar una nueva clave de idempotencia
2. Una operación para eliminar una clave antigua según la política de expiración del cliente

## Operaciones requeridas

No todas las operaciones de la API requieren claves de idempotencia. Fluz requiere idempotencia para ciertas operaciones críticas a fin de garantizar la consistencia de los datos en las siguientes operaciones:

* `purchaseGiftCard` ([Ver aquí](/purchase-gift-card))
* `depositCashBalance` ([Ver aquí](/features/deposit-from-external-accounts))

Para estas operaciones, se requiere una variable de entrada `idempotencyKey`.

## Ejemplo de entrada

```json theme={null}
{  
  "idempotencyKey": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "offerId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "amount": 123.45,  
  "balanceAmount": 987.65,  
  "bankAccountId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "bankCardId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "paypalVaultId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "exclusiveRateId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "merchantSlug": "xyz789"  
}
```

<Note>
  Fluz requiere una clave de idempotencia para esta operación.
</Note>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Comprar tarjeta de regalo" icon="gift" href="/purchase-gift-card">
    Mira la clave de idempotencia en acción en la mutación de movimiento de dinero más común.
  </Card>

  <Card title="Formato de direcciones" icon="map-pin" href="/concepts/address-formatting-requirements">
    La otra causa común de solicitudes rechazadas: cómo formatear direcciones para que se validen a la primera.
  </Card>
</CardGroup>

<StickyContactSalesBanner />