# Idempotencia & Reintentos

En sistemas distribuidos, **los reintentos son inevitables**.
Timeouts, errores de red o fallos temporales pueden provocar que una misma solicitud
se envíe más de una vez.

QRwey! utiliza el header **`Idempotency-Key`** para garantizar que ciertas operaciones
se ejecuten **una sola vez**, incluso si se reintentan.

## ¿Qué es idempotencia?

Una operación idempotente es aquella que:

> Puede ejecutarse múltiples veces con el mismo resultado final.


En QRwey!, esto es crítico para evitar:

- QRs duplicados
- Intenciones de autofactura repetidas
- Inconsistencias fiscales


## ¿Dónde aplica la idempotencia en QRwey!?

La idempotencia **aplica únicamente** a operaciones de **escritura**, en particular:

- **Generación de códigos QR**
  - `POST /api/v1/qrs`


Las operaciones de lectura (`GET`) **no requieren** idempotencia.

## Header `Idempotency-Key`

Para usar idempotencia debes enviar:


```http
Idempotency-Key: <uuid>
```

Características importantes:

- Debe ser **único por operación lógica**
- Debe ser el **mismo valor** si reintentas la solicitud
- Se recomienda un **UUID v4**


Ejemplo:


```http
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

## Flujo recomendado con reintentos

1. Genera un `Idempotency-Key`
2. Envía la solicitud a QRwey!
3. Si ocurre un timeout o error de red:
  - Reintenta **con el mismo Idempotency-Key**
4. QRwey! garantiza que la operación no se duplique


## Ejemplo práctico


```bash
curl -X POST "https://api-dev.qrwey.com/api/v1/qrs"   -H "X-API-Key: TU_API_KEY"   -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000"   -H "Content-Type: application/json"   -d '{ ... }'
```

Si esta solicitud se envía dos o más veces con el mismo `Idempotency-Key`:

- La **primera** crea la transacción
- Las siguientes **no crean duplicados**
- QRwey! responde de forma consistente


## ¿Qué pasa si cambias el Idempotency-Key?

Si envías la **misma solicitud** pero con un `Idempotency-Key` distinto:

- QRwey! la tratará como una **nueva operación**
- Se creará un **nuevo QR**
- Esto puede generar duplicados


> ⚠️ Nunca cambies el `Idempotency-Key` al reintentar la misma operación.


## Errores relacionados

### 409 Conflict

Este error puede indicar:

- La operación ya fue procesada
- El QR ya fue generado o consumido
- La solicitud entra en conflicto con el estado actual


Acciones recomendadas:

- No reintentar indefinidamente
- Usar el resultado existente si aplica
- Registrar el evento para auditoría


## Buenas prácticas

- Genera el `Idempotency-Key` en tu backend
- Asócialo a la venta o transacción interna
- Reutilízalo solo para la misma operación
- No lo reutilices para operaciones distintas
- Registra el `Idempotency-Key` para depuración


## Errores comunes

| Error | Consecuencia |
|  --- | --- |
| Generar un nuevo key en cada retry | QRs duplicados |
| Reintentar sin idempotencia | Inconsistencias |
| Usar el mismo key para operaciones distintas | Comportamiento inesperado |


## Checklist para producción

Antes de ir a producción:

- [ ] Generas `Idempotency-Key` en backend
- [ ] Reusas el mismo key en reintentos
- [ ] Manejas `409 Conflict`
- [ ] No generas QRs duplicados
- [ ] Logs incluyen el `Idempotency-Key`


## ¿Qué sigue?

- Manejo de fallos: [Manejo de errores](/guides/error-handling)
- Flujo completo: [Quickstart](/guides/quickstart)
- Detalle del endpoint: [Referencia del API](/apis/qrwey)