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 /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/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