Idempotencia en eventos de inventario: evitar registrar dos veces la misma operación

Qué significa idempotente, sin matemáticas

Imagina que un operador confirma una recepción desde su PDA y la señal Wi‑Fi falla justo al enviar. La aplicación no sabe si el servidor lo recibió, así que vuelve a enviar. Si el servidor suma otra vez las 40 cajas, el inventario queda con 80. Idempotencia es la propiedad que evita eso: repetir la misma operación no cambia el resultado más allá de la primera aplicación.

La especificación de HTTP (RFC 9110) define idempotencia a nivel de método: PUT y DELETE son idempotentes, POST no. Pero esa propiedad habla de lo que pidió el cliente; aun así, el servidor puede registrar cada petición por separado. Para eventos de inventario, que normalmente llegan por POST, la protección debe diseñarla quien construye la integración.

Qué hace buena a una clave de idempotencia

La clave identifica la operación de negocio, no el mensaje técnico. Tres propiedades importan: la genera quien origina la operación, se conserva igual en todos los reintentos y no se repite entre operaciones distintas. Una propuesta del IETF sobre Idempotency-Key (borrador expirado, no estándar) ilustra justamente esa idea: un valor único generado por el cliente y reutilizado en los reintentos. Como la propuesta no es un estándar vigente, verifica qué mecanismo soporta realmente tu destino.

El estándar EPCIS permite un identificador de evento único a nivel global; el vocabulario CBV 2.0 especifica el uso de URIs con UUID o con un hash del evento para ese fin, lo que muestra que la comunidad ya resolvió esta pregunta para eventos compartidos.

Alcance y tiempo de vida de la clave

Decide dentro de qué universo debe ser única la clave: un dispositivo, una tienda, todo el sistema. Cuanto más pequeño el alcance, más fácil de generar y más riesgoso si dos orígenes coinciden. También define cuánto tiempo el receptor recuerda las claves. Si olvida demasiado pronto, un reenvío tardío (por ejemplo, un dispositivo que estuvo sin conexión todo un turno) pasaría como operación nueva. Si recuerda demasiado, la tabla de claves crece sin control.

No hay un número universal. Se fija por el peor caso razonable de retraso de tu operación: la PDA que sincroniza al final del día, la colección de eventos que se reenvía tras un fin de semana. Escríbelo como supuesto y revísalo con datos de operación.

Cómo debe responder el receptor a un reenvío

Cuando llega una clave ya conocida, el receptor no debe crear otro registro ni responder con un error que haga que el emisor reintente sin fin. Lo conveniente es devolver el mismo resultado que dio la primera vez. Hay una excepción importante: si llega la misma clave con contenido distinto (otro artículo o cantidad), es una anomalía; debe rechazarse y registrarse, no sobrescribirse en silencio.

Un caso especial en EPCIS es la declaración de error. Según la norma, se registra un evento idéntico al original salvo por el elemento ErrorDeclaration y la hora de registro; por eso comparte el mismo eventID del original, la única situación en que un mismo eventID no nulo aparece en dos eventos. Los eventos que corrigen el error son otros eventos, con su propio eventID, que la declaración puede enlazar mediante correctiveEventIDs. Un evento corregido no reutiliza el identificador del original.

Conviene separar dos mecanismos que a veces se confunden. La idempotencia de la API responde a una pregunta técnica: ¿este mensaje es un reintento de uno que ya recibí? Si llega la misma clave con contenido distinto, se rechaza. La corrección de dominio responde a otra: ¿un hecho que ya registré era erróneo? Se resuelve con eventos nuevos en el flujo de negocio: una declaración de error y, si procede, eventos correctivos, cada uno enviado con su propia clave de operación y, si el contrato lo exige, su propio identificador de evento. La declaración de error no es un reintento ni un “mismo mensaje con otro contenido”, así que no debería rechazarse por la regla de la clave; en el contrato documenta que el receptor la admite como excepción cuando el tipo de evento lo indica, y que la clave de la operación de corrección es distinta de la del envío original.

Ejemplo hipotético: reenvío tras una caída de Wi‑Fi

Ejemplo ilustrativo. Una PDA confirma la recepción de la orden “OC-500” y genera la clave de operación al abrir la sesión. Envía; el servidor registra 40 cajas y responde, pero la respuesta no llega por una caída de Wi‑Fi. La PDA reintenta con la misma clave. El servidor reconoce la clave, no vuelve a sumar y devuelve el mismo resultado: 40 cajas aplicadas.

Variante problemática: la PDA vuelve a abrir la recepción desde cero y genera otra clave. El servidor no puede saber que es la misma operación y suma otras 40. La solución no es técnica sola: el flujo debe reanudar la sesión pendiente en vez de crear una nueva, y el WMS debe además comprobar que no se reciban más cajas que las esperadas por la orden.

Límites: la idempotencia no sustituye otras defensas

• No detecta duplicados de negocio disfrazados de operaciones distintas, como dos conteos del mismo anaquel con claves diferentes; para eso hay reglas de sesión y validación.
• No corrige errores de captura: un evento duplicado idempotentemente sigue siendo un evento equivocado.
• No ayuda si el mismo evento llega por dos canales diferentes (por ejemplo, API y archivo) con claves distintas.
• Requiere almacenamiento fiable de las claves; si se pierden en una restauración, el efecto se pierde.

Por eso conviene combinarla con validaciones contra órdenes abiertas, con conciliaciones periódicas y con registros que permitan investigar.

Preguntas frecuentes

¿Puedo usar el número de documento como clave? Solo si cada intento de operar sobre ese documento es realmente la misma operación. Una recepción parcial seguida de otra sobre la misma orden son dos operaciones; necesitan claves distintas o una secuencia dentro del documento.

¿Y si el origen no puede generar claves? Entonces el receptor puede calcular una huella con los campos que definen la operación, aunque es menos confiable porque dos operaciones legítimas idénticas se confundirían. Documenta ese riesgo.

Siguiente paso

Elige una operación crítica, como la recepción, y escribe su clave, alcance y tiempo de retención. Luego prueba tres casos: reenvío idéntico, reenvío con contenido distinto y reenvío después del tiempo de retención. Si necesitas revisar el flujo de captura, puedes escribir a ARKCOM en garkcom.com/contact.