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.
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
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.
Para usar idempotencia debes enviar:
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:
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000- Genera un
Idempotency-Key - Envía la solicitud a QRwey!
- Si ocurre un timeout o error de red:
- Reintenta con el mismo Idempotency-Key
- QRwey! garantiza que la operación no se duplique
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
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-Keyal reintentar la misma operación.
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
- Genera el
Idempotency-Keyen 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-Keypara depuración
| Error | Consecuencia |
|---|---|
| Generar un nuevo key en cada retry | QRs duplicados |
| Reintentar sin idempotencia | Inconsistencias |
| Usar el mismo key para operaciones distintas | Comportamiento inesperado |
Antes de ir a producción:
- Generas
Idempotency-Keyen backend - Reusas el mismo key en reintentos
- Manejas
409 Conflict - No generas QRs duplicados
- Logs incluyen el
Idempotency-Key
- Manejo de fallos: Manejo de errores
- Flujo completo: Quickstart
- Detalle del endpoint: Referencia del API