En flujos de KYC y otras operaciones delicadas, una Clave de idempotencia en la API Garantiza que al repetir la misma solicitud se conserve el efecto deseado, en lugar de crear un nuevo registro, generar una segunda consulta o cobrar dos veces. La lógica es sencilla: el cliente genera una clave única antes del primer intento y reutiliza esa misma clave cuando necesita repetir la operación debido a un tiempo de espera agotado, una caída de la conexión o una respuesta perdida.
El problema no es el reintento en sí. El problema es repetir una acción con un efecto secundario sin saber si el primer intento fue exitoso. En un Integración de APIEsto puede implicar la creación de dos clientes, dos pedidos, dos validaciones o dos cargos para una misma intención del usuario. La idempotencia crea una memoria operativa entre el cliente y el servidor: «esta acción ya se ha recibido; no la ejecutes de nuevo innecesariamente».
Resumen
- La clave de idempotencia permite repetir operaciones sin multiplicar sus efectos.
- La misma clave solo debe reutilizarse al volver a intentar la misma operación y con la misma carga útil.
- El servidor necesita almacenar la clave, la huella digital, el estado y la respuesta durante un período definido.
- Es necesario probar los tiempos de espera, la competencia, los conflictos y la caducidad antes de la producción.
¿Por qué la clave de idempotencia en las API protege las operaciones con efectos secundarios?
Una solicitud GET no debería generar un efecto nuevo cada vez que se repite. Sin embargo, una solicitud POST que crea un recurso o inicia un cargo sí puede hacerlo. RFC 9110 Define PUT, DELETE y los métodos seguros como idempotentes y explica que las solicitudes idempotentes pueden repetirse tras ciertos fallos de comunicación sin alterar el efecto deseado. Para POST y PATCH, esta seguridad debe integrarse en la aplicación cuando la operación no es inherentemente idempotente.
En mi opinión, este tipo de mecanismo funciona bien cuando pasa desapercibido para quienes usan el producto. En ZapSign, he defendido una idea recurrente: la tecnología compleja debe simplificarse, sin trasladar esa complejidad al usuario. Si una persona pulsa "pagar", "validar" o "crear" una sola vez, el sistema debería tratar esa acción como una sola operación, aunque la infraestructura necesite repetir las llamadas internamente.
Esta misma preocupación aparece en un API de firma digitalLa integración no puede confundir un fallo de comunicación con la autorización para repetir una acción delicada. La resiliencia no consiste en repetirlo todo, sino en saber qué se puede repetir, bajo qué condiciones y con qué pruebas.
¿Cómo generar y reutilizar una clave de idempotencia?
La clave debe crearse antes del primer intento y permanecer con el usuario durante toda la operación. Genere una clave nueva para cada operación. En caso de reintento, conserve la clave anterior. RFC 9562 Describe UUIDv4 como un identificador generado a partir de números aleatorios o pseudoaleatorios y permite 122 bits para campos aleatorios, lo que lo convierte en una opción práctica para claves con alta variabilidad.
- Genere una clave única en el cliente antes de la primera llamada.
- Envíe la clave junto con la operación, ya que podría producir efectos secundarios.
- Conserva la clave en el servidor cuando la solicitud entre en procesamiento.
- Asocie la clave con una huella digital de la carga útil y el estado de ejecución.
- Si es necesario volver a intentarlo, utilice la misma clave, pero con el mismo contenido.
- Una vez finalizado, devuelva la respuesta ya registrada en lugar de volver a ejecutar todo el proceso.
la arquitectura de API de firma electrónica Esto ayuda a visualizar la diferencia entre solicitar una acción y consultar su estado. La idempotencia no debe convertirse en un atajo para el sondeo. Si desea saber si un recurso se ha creado, firmado, validado o pagado, utilice el punto final de consulta correspondiente. No convierta las solicitudes POST o PATCH repetidas en un método de lectura.
Una misma llave no puede significar dos intenciones diferentes.
Una clave sin validación de la carga útil ofrece una protección incompleta. Si el cliente envía la misma clave de idempotencia con un valor, CPF (identificación fiscal brasileña), producto o destinatario diferente, el servidor debe reconocer que no se trata del mismo intento. Una estrategia común consiste en calcular una huella digital utilizando los campos relevantes de la solicitud y comparar este valor entre los intentos. Si la clave y la huella digital coinciden, se reutiliza el resultado. Si difieren, se rechaza la nueva solicitud.
Este principio se alinea con lo que defendemos en validación de identidadLa confianza no se basa en una sola señal aislada. Una clave idéntica demuestra que el identificador se reutilizó, pero no prueba por sí sola que la intención se mantuviera. La información contenida en el mensaje también debe tenerse en cuenta al tomar la decisión.
| Situación | Chave | carga útil | Respuesta esperada |
|---|---|---|---|
| Primer intento | Nova | Nuevo | Proceso normalmente |
| Reintentar después de un tiempo de espera agotado. | Mismo | Igual | Regresar al resultado anterior o al procesamiento de la pista. |
| Reutilización inadecuada | Mismo | Diferente | Rechazar debido a un conflicto sin realizar una nueva operación. |
| Nueva operación legítima | Nova | Nuevo o igual | Proceso como nueva intención |
Almacenar claves y respuestas forma parte de la norma, no es un detalle de la infraestructura.
Una implementación idempotente necesita almacenar más que solo la cadena de clave. El registro debe contener, como mínimo, el identificador del cliente, el punto final, la huella digital de la carga útil, el estado de la operación, la respuesta reutilizable y la fecha de caducidad. Sin este contexto, dos operaciones de clientes diferentes pueden entrar en conflicto lógico, o una clave puede reaparecer después de que el servidor haya perdido la memoria de la primera ejecución.
Prefiero considerarlo como gobernanza operativa. Cuando lanzamos ZapSign ID, la premisa pública era transformar preguntas complejas sobre identidad en respuestas objetivas mediante una API. Para mantener esta simplicidad en el usuario final, la infraestructura subyacente debe ser predecible. Aquí es donde los mecanismos de control dejan de ser detalles técnicos y comienzan a proteger los costos, la experiencia y la confianza.
El TTL, o Tiempo de Vida de un Registro, debe reflejar la realidad de esa operación. Si es demasiado corto, permite que un reintento tardío se convierta en una nueva ejecución. Si es demasiado largo, aumenta innecesariamente el almacenamiento y la retención. En viajes con presencia en vivo y KYCEn lo que respecta a los cargos por consulta o creación de recursos, la política debe documentarse y revisarse en función de la latencia, el comportamiento del cliente y el período real de reintento.
Consulte también estos artículos relacionados:
- Comprenda cómo la API de ZapSign conecta sistemas, documentos, webhooks y automatizaciones.
- Descubre cómo una API de firma digital organiza la autenticación, los errores y la observabilidad.
- Comprenda cómo el proceso modular de KYC ajusta las verificaciones en función del riesgo, el costo y la experiencia.
¿Cómo gestionar los problemas de concurrencia 409 y 422 sin crear nuevas duplicaciones?
Existe una diferencia significativa entre reintentar una llamada una vez finalizada la primera y reintentarla mientras aún se está procesando. En este último caso, devolver inmediatamente el resultado anterior puede ser imposible, ya que aún no existe. El servidor necesita bloquear la ejecución concurrente de la misma intención e indicar que esa clave ya está en curso. En muchos diagramas, un conflicto 409 comunica precisamente este estado temporal.
Sin embargo, cuando la clave se reutiliza con una carga útil diferente, el problema cambia: no solo hay concurrencia, sino también inconsistencia. Un error 422 puede indicar que el contenido no corresponde a la operación originalmente asociada con esa clave. El cliente no debe modificar la carga útil e insistir en ello. Debe corregir la intención, generar una nueva clave cuando se trate realmente de una nueva operación y conservar el registro de lo sucedido.
Este enfoque es similar a la lógica de gobernanza de APILos distintos estados requieren respuestas diferentes. «Ya estoy procesando», «cambiaste la operación» y «se produjo un fallo temporal» no son el mismo problema. Cuando todo se convierte en un error genérico, reintentar deja de ser una estrategia de resiliencia y se convierte en un generador de riesgos.
La prueba decisiva se produce cuando la respuesta desaparece.
El escenario más valioso no es la llamada que funciona, sino aquella en la que el servidor completa la operación, pero el cliente agota el tiempo de espera antes de recibir una respuesta. En este punto, los sistemas sin idempotencia suelen duplicar los efectos. La prueba debe simular la pérdida de respuesta, la interrupción de la conexión, el reintento automático, dos llamadas simultáneas, la reutilización con una carga útil diferente, la caducidad de la clave y la persistencia de la respuesta de error.
En una transacción de pago, un segundo intento no puede generar un segundo cargo. En una API de identidad, no debería activarse una segunda consulta con cargo cuando el objetivo era simplemente recuperar el resultado de la primera. En la creación de recursos, no puede generar dos registros. Esta lógica también se aplica a... identificación del firmante y otros procesos en los que una acción técnica genera consecuencias legales, financieras u operativas.
| Prueba | Qué validar | Un defecto que revela |
|---|---|---|
| Tiempo de espera agotado después del procesamiento | Reintentar produce el mismo efecto. | Duplicidad silenciosa |
| Dos llamadas simultáneas | Solo uno ejecuta | Carrera competitiva |
| Misma clave, diferente carga útil. | La transacción ha sido rechazada. | Reutilización inadecuada |
| Clave caducada | La política es predecible. | TTL mal calibrado |
Una buena idempotencia reduce los costes, pero también mejora la gobernanza.
Evitar la facturación duplicada es el efecto más visible. La mayor ventaja se observa cuando los registros, las métricas y las alertas muestran cuántas llamadas se repitieron, cuántas duplicaciones se evitaron, cuántas respuestas se reutilizaron, qué claves entraron en conflicto y dónde se concentran los tiempos de espera. Estos datos ayudan a diferenciar los problemas relacionados con el cliente, la red, el procesamiento y las reglas de negocio.
La seguridad también debe ser proporcional. ZapSign ya funciona con esta lógica al permitir diferentes... niveles de validación y fortaleciendo la cadena de confianza como Autoridad certificadaEn las API, se aplica el mismo razonamiento: añadir control no implica crear fricciones indiscriminadas, sino garantizar que las operaciones delicadas produzcan exactamente el efecto autorizado, ni más ni menos.
Es necesario revisar la clave de idempotencia en una API como parte de la política operativa.
Implementar la clave y olvidarse de ella no es suficiente. Revise los TTL, el volumen de recuperación, la tasa de conflictos, la latencia, las respuestas reutilizadas, los errores 409 y 422, y los casos en los que el cliente generó una nueva clave demasiado pronto.
Una clave de idempotencia en una API funciona mejor cuando va más allá de ser solo un encabezado y comienza a integrar observabilidad, gobernanza y diseño de producto. Para flujos que también necesitan confirmar quién está en el otro extremo antes de ejecutar acciones sensibles, la ID de ZapSign Puedes adaptarte a esta arquitectura.
Perguntas frecuentes (FAQ)
Es un identificador único creado para representar una operación específica. Cuando el cliente necesita repetir la llamada debido a un tiempo de espera agotado o un fallo de comunicación, reutiliza la misma clave. El servidor reconoce que la intención ya se ha recibido y evita ejecutar el efecto secundario de nuevo, pudiendo devolver la respuesta registrada en la primera ejecución.
Reutilice la clave únicamente al repetir la misma operación, con la misma carga útil y la misma intención. Si el usuario inició un nuevo cargo, una nueva consulta o la creación de un nuevo recurso, genere otra clave. Reutilizar una clave antigua para una acción diferente genera una mezcla de operaciones y la API debe gestionarla como un conflicto.
Normalmente, no. GET es un método seguro e idempotente por naturaleza en cuanto a su efecto previsto, por lo que repetir una consulta no debería crear un nuevo recurso ni un nuevo cargo. La clave de idempotencia tiene más sentido en operaciones como POST y PATCH cuando existe un efecto secundario y la aplicación necesita que los reintentos sean predecibles.
La API debería rechazar la solicitud en lugar de ejecutar una nueva operación. Para ello, el servidor puede asociar una huella digital, derivada de los campos relevantes de la carga útil, con la clave. Si la clave es la misma, pero la huella digital cambia, existe una intención inconsistente. El cliente debería corregir la solicitud o generar una nueva clave para una operación legítima.
No existe un TTL universal para todas las API. El intervalo debe reflejar el tipo de operación, la latencia, el comportamiento esperado del cliente y el período durante el cual aún pueden producirse reintentos. Lo importante es documentar la política, supervisar los reintentos tardíos y evitar que la clave caduque antes de que la operación ya no necesite protección contra la duplicación.
Getúlio Santos es el director ejecutivo de ZapSign, abogado, entusiasta de la tecnología y emprendedor.
