Idempotencia y reintentos

Emitir dos veces la misma venta es un problema fiscal. Por eso todos los POST exigen la cabecera Idempotency-Key: si repites una solicitud con la misma clave, sudte devuelve el resultado de la primera en lugar de ejecutarla otra vez.

POST /v1/documents
Idempotency-Key: venta-2026-000123

Cómo funciona

Situación	Resultado
Primera vez que se usa la clave	Se procesa la solicitud y se guarda su respuesta.
Misma clave y mismo cuerpo	Se devuelve la respuesta guardada; no se emite otro documento.
Misma clave con otro cuerpo	`409` `idempotencia-conflicto`.
Misma clave mientras la primera sigue en curso	`409`; espera y reintenta.

Las claves son por cuenta y por ambiente y se conservan 30 días. Pueden tener hasta 255 caracteres.

Cómo elegir la clave

Usa un identificador estable de la operación de negocio, no uno aleatorio por intento: el número de la venta en tu POS, el id de la factura en tu ERP o un UUID que generes al crear la venta y guardes junto a ella. Así, si tu proceso se cae a mitad del envío y lo reanudas, reutilizas la misma clave y no duplicas el documento.

Envía también ese identificador en external_id para encontrar el documento después con GET /v1/documents?external_id=….

Reintentar sin miedo

Errores de red o 5xx: reintenta con la misma clave y espera exponencial (1 s, 2 s, 4 s…).
202 Accepted: no reintentes el POST; el documento ya existe y sudte sigue trabajando. Espera el webhook o consulta GET /v1/documents/{id}.
Documento pendiente (signed, sending, error, contingency): POST /v1/documents/{id}/retry consulta primero el estado en el MH y, si no lo tiene, retransmite exactamente el mismo JSON firmado.
Documento rechazado: corrige y llama a POST /v1/documents/{id}/retry con el cuerpo corregido. sudte rearma el documento conservando el código de generación y el número de control, como exige la Normativa (dentro de 24 horas del rechazo).

sudte nunca vuelve a firmar un código de generación con contenido distinto al que ya se transmitió.