Idempotencia en una integración: cómo definir la clave de una operación

Escribe qué efecto estás protegiendo

Nombra la acción: crear un pedido, emitir un documento o solicitar un cargo. Relaciónala con una solicitud de negocio estable y su versión aprobada. Un mismo expediente puede necesitar varias acciones; cada una necesita su ámbito. En un ejemplo hipotético, crear el pedido y enviar su confirmación son dos efectos separados. Si comparten una clave sin distinguir acción, el registro de uno podría bloquear indebidamente al otro.

Genera y guarda antes de enviar

Asigna la clave cuando aceptas la intención, consérvala de forma duradera y reutilízala en los intentos posteriores. Puede ser aleatoria con suficiente entropía, siempre que guardes su relación con el negocio. Evita incluir datos personales. Guarda también una representación controlada de los parámetros para detectar cambios: una clave repetida con cantidad distinta no debe ejecutarse silenciosamente como si fuera la misma solicitud.

Lee el contrato de la API concreta

Verifica qué métodos admiten la clave, su longitud, ámbito, conservación y comportamiento ante concurrencia. Stripe diferencia expresamente API v1 y API v2; no traslades las reglas de una a la otra. Tampoco presupongas que cualquier cabecera llamada Idempotency-Key tiene la misma semántica. Si el destino no ofrece protección, un registro local puede coordinar tus trabajadores, pero no elimina por sí solo la incertidumbre entre una escritura remota y su confirmación local.

Redacta un contrato que entienda operaciones

Deja una ficha breve con ámbito de la clave, momento de asignación, parámetros que fija, respuesta a una repetición y salida tras perder la protección del proveedor. Añade quién puede invalidar o sustituir una intención. En un ejemplo hipotético, una clave para crear un documento no debería reutilizarse para rectificarlo: la rectificación tiene su propio efecto y autorización.

Si una solicitud permanece pendiente mientras cambian los datos maestros, evita reconstruir sus parámetros desde los valores actuales sin revisar. Mantén la versión aprobada o solicita una nueva decisión antes de enviar. Esa separación permite explicar por qué dos intentos son equivalentes incluso si la ficha del cliente cambió entre ellos. La prueba debe comparar el contenido efectivo enviado, además de la cadena utilizada como clave.

Define las colisiones como errores observables

Dos trabajadores que reciben la misma intención deben compartir la operación persistida, no inventar dos claves. Prueba envío duplicado simultáneo, pérdida de respuesta y reutilización accidental con contenido cambiado. Añade una operación nueva del mismo cliente para verificar que sí puede pasar. El criterio de aceptación es el número de efectos en el destino y su relación con las intenciones autorizadas; contar respuestas correctas no demuestra ausencia de duplicados. Documenta la salida manual cuando el destino no permite consultar el resultado.

Fuentes y documentación

• Stripe: solicitudes idempotentes — El contrato cambia entre API v1 y v2; revisa conservación de claves, parámetros y resultados.
• PostgreSQL: restricciones — Restricciones de unicidad, nulidad y referencias como controles de integridad.