Idempotencia en la recepción de órdenes

Contexto

POST /orders recibe externalReference. La misma orden puede ser recibida más de una vez, incluyendo recepciones concurrentes.

Decisión

La primera recepción crea la orden y una recepción repetida retorna la orden existente. La garantía de unicidad es la restricción UNIQUE sobre external_reference en PostgreSQL, que actúa como autoridad final. En inserts concurrentes, la restricción decide; el proceso que pierde recupera, después de la violación de unicidad y su rollback, la orden persistida por el ganador y retorna la existente. Cualquier pre-check de aplicación es sólo una optimización secundaria y no una garantía de consistencia.

Consecuencias

PostgreSQL queda como autoridad final de unicidad. Una recepción duplicada devuelve la orden ya persistida; externalReference es la clave de idempotencia de negocio y no orderId. El caso concurrente depende de detectar una violación de unicidad y recuperar la fila ganadora. La implementación queda acoplada a que externalReference represente realmente la identidad de negocio adecuada para una orden.

Alternativas descartadas

Sólo hacer check-before-insert en aplicación se descarta porque mantiene una condición de carrera. Redis o locks distribuidos agregan complejidad innecesaria para la garantía requerida. HTTP Idempotency-Key no es necesario mientras externalReference sea la clave de negocio que define la duplicación.