Idempotencia y Reintentos Seguros

Cómo usar Idempotency-Key para recuperar emisiones, cancelaciones, inutilizaciones y nominaciones sin duplicar efectos tributarios.

Idempotency-Key identifica una intención tributaria. Permite repetir una emisión, cancelación, inutilización o nominación después de perder la respuesta sin crear una operación distinta.

Una clave ya registrada siempre devuelve la operación original, aunque cambies el body o el CDC. Si reutilizás una clave por error, no recibís un error: recibís el documento anterior. Generá una clave nueva para cada intención.

Operaciones soportadas

Operación	Endpoint
Emisión	`POST /api/v1/documento-electronico`
Cancelación	`POST /api/v1/documento-electronico/:cdc/cancelar`
Inutilización	`POST /api/v1/documento-electronico/inutilizar`
Nominación	`POST /api/v1/documento-electronico/:cdc/nominar`

El header es opcional. Incluilo para obtener estas garantías. La clave se identifica por contribuyente y ambiente y se comparte entre estas operaciones: una misma clave conserva la operación original. Usarla para otro tipo de operación produce 422 idempotency-key-reused (por ejemplo, emitir y después cancelar).

En SANDBOX podés usar idempotencia para emitir. Cancelación, inutilización y nominación devuelven 422 sandbox-operation-not-supported; cambiar la clave no habilita esas operaciones.

Antes del primer intento

Generá un UUID v4 por intención.
Persistí la clave junto con la operación, la URL y el body exacto antes del primer POST.
Enviá la clave en Idempotency-Key.
Guardá la respuesta y los identificadores tributarios asociados.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Para recuperar la operación, leé esos valores guardados: no reconstruyas la solicitud desde datos que pudieron cambiar.

Qué ocurre si cambia el reintento

Si una factura de ₲100.000 se registró con abc, enviar otra de ₲200.000 con abc recupera la operación de ₲100.000: no modifica el documento ni consume otro correlativo. En cancelación o nominación, cambiar el CDC tampoco cambia el documento de la operación original; los eventos pendientes se recuperan con sus datos guardados.

Si la respuesta trae un CDC o un número que no esperabas, la clave ya estaba usada: revisá cómo generás las claves.

Sifende sigue verificando la autenticación, el contribuyente, el ambiente y el tipo de operación. Con una clave ya registrada, el body sólo tiene que ser JSON válido con los tipos correctos (si no, 400); no se revalidan campos obligatorios ni formatos. Con una clave nueva o sin clave, la validación es completa.

Cuándo repetir la solicitud

Repetí exactamente la misma solicitud con la misma clave en estos casos:

Timeout, reset o conexión cortada sin respuesta HTTP
409 idempotency-in-progress
503 idempotency-upstream-unknown

En los errores de idempotencia, Retry-After aparece en idempotency-in-progress e idempotency-upstream-unknown. La nominación también puede devolver 503 evento-nominacion-error con Retry-After: 2. Esperá ese intervalo antes del reintento.

Cuándo detenerse

Respuesta	Acción
`409 idempotency-outcome-unknown`	Detené el flujo. El resultado es indeterminado y terminal; no reenvíes ni cambies la clave
`409 idempotency-key-expired`	Detené el flujo. El replay venció, pero la clave sigue reservada
`422 idempotency-key-reused`	La clave ya se usó para otro tipo de operación. Para recuperar esa operación, usá su endpoint. Para una operación nueva, generá otra clave

No generes otra clave para recuperar la misma intención: una clave nueva representa una operación nueva.

Resultado según la operación

Operación	Garantía del reintento
Emisión	Reproduce el mismo `202`, documento, CDC, correlativo y `Location`; no consume otro número
Cancelación	Reutiliza el evento original. `0600` confirma la cancelación; `4003` se acepta como éxito equivalente porque el CDC ya tiene una cancelación registrada
Nominación	Recupera el evento, documento, motivo y receptor originales; no sustituye el receptor con el del reintento
Inutilización	Reutiliza el evento original. `0600` confirma la inutilización; `4066` deja el evento `INDETERMINADA` porque sólo prueba que el rango contiene números ya inutilizados, no que todo el rango coincida con esta intención

En cancelación, un reintento que recibe 4003 deja el documento CANCELADO, conserva el código y mensaje para auditoría y puede responder protocoloAutorizacion: null. Los reintentos siguientes reproducen ese resultado sin volver a enviar el evento.

En inutilización, 4066 produce 409 idempotency-outcome-unknown. No reenvíes con la misma clave ni con otra: el evento queda INDETERMINADA y el rango permanece protegido.

Cuánto dura una clave

Sifende guarda el replay durante 7 días desde la finalización: status, body y headers como Location. Dentro de ese plazo, la misma clave y tipo de operación reciben la respuesta original.

Después de 7 días, el replay deja de estar disponible, pero la clave sigue reservada: el mismo tipo de operación devuelve 409 idempotency-key-expired aunque cambie el contenido. Otro tipo de operación sigue devolviendo 422 idempotency-key-reused.

Un documento archivado no bloquea el replay ni la recuperación de un evento pendiente ya registrado.

Cuando termina la conservación del documento, su clave se libera y una solicitud con esa clave se trata como nueva. Por eso nunca recicles claves.

Fallos sin clave

Un 5xx en un POST sin Idempotency-Key no demuestra que la operación haya fallado sin efectos. No reenvíes a ciegas: investigá primero el estado del recurso. Para el catálogo general y el campo resultadoIndeterminado, ver Manejar Errores.