Idempotencia y external_id

external_id e Idempotency-Key resuelven problemas distintos:

external_id conecta el recurso fiscal con una operación estable de tu sistema.
Idempotency-Key identifica una intención concreta de mutación y hace seguro repetirla.

Usa ambos.

Diseñar external_id

Un buen identificador:

es único por integración y contribuyente;
no contiene datos sensibles;
no cambia cuando cambia una pantalla o estado;
no se recicla al cancelar o corregir;
puede buscarse desde soporte y reconciliación.

Ejemplos de origen válidos pueden ser un UUID de la operación o una clave compuesta inmutable controlada por tu sistema. Un número consecutivo editable no es suficiente.

Delimitación de idempotencia

CierreListo delimita una clave por la integración, el contribuyente, la operación y la propia clave. El contrato publicado define los componentes exactos.

Repetición	Resultado esperado
Misma clave y mismo cuerpo	Devuelve la intención original sin crear otra.
Misma clave y cuerpo diferente	Rechaza por conflicto de idempotencia.
Clave nueva y mismo `external_id`	Rechaza o devuelve el recurso existente según el contrato.
Timeout antes de conocer el resultado	Consulta antes de crear una intención nueva.

Almacena antes de enviar

Persiste atómicamente en tu sistema:

external_id;
Idempotency-Key;
hash o versión del cuerpo;
estado local “enviando”;
fecha del intento.

Después de la respuesta agrega los identificadores de CierreListo y request_id.

Reintento después de editar

Si cambia el significado fiscal, no reutilices la clave anterior. Antes:

determina si la intención anterior existe;
corrige mediante el flujo fiscal aplicable;
crea una nueva intención con identidad trazable;
conserva la relación entre original y corrección.

Reconciliación

Un proceso periódico debe buscar operaciones locales sin resultado terminal y consultarlas por identificador estable. La reconciliación es obligatoria incluso si usas webhooks.

Continuar con el ciclo asíncrono →