Idempotencia

Cómo evitar una nota duplicada

Dos protecciones, que se complementan:

	Idempotency-Key (encabezado)	referencia (campo del cuerpo)
Qué es	Identificador de TU intento de llamada	Identificador de la nota en TU sistema (ej.: número de pedido)
Dónde aplica	POST /v1/nfse, POST /v1/lotes, POST /v1/webhooks y POST /v1/companies	POST /v1/nfse y cada elemento de POST /v1/lotes
Obligatorio	No, pero recomendado	No, pero recomendado
Alcance	Cuenta y entorno (vale para todas las claves de API de la cuenta en ese entorno)	Empresa y entorno
Validez	24 horas de uso exclusivo; la respuesta se guarda 30 días	Para siempre
Repetida	Devuelve la respuesta guardada de la primera vez	409 referencia_duplicada, con el nfse_id de la nota que ya existe
Tamaño	Texto libre (un UUID sirve)	Hasta 60 caracteres

Usa las dos. La Idempotency-Key resuelve el reintento inmediato (timeout, caída de red). La referencia impide siempre la nota duplicada, aunque tu sistema pierda la clave.

Qué pasa en cada caso

Situación	Resultado
Misma Idempotency-Key, mismo cuerpo	La MISMA respuesta de la primera vez (estado y cuerpo), sin crear nada. Vale para 201, 202 y para los 422 nfse_rejeitada y falha_transmissao.
Misma Idempotency-Key, cuerpo distinto	409 idempotencia_conflito. No se crea nada.
La primera llamada con la clave todavía está en curso	La segunda espera unos 3 segundos. Si la primera no terminó, 409 conflito: espera y repite.
La primera llamada terminó en error sin crear nada (412, 422 validacao, 409 referencia_duplicada, 403, 404, 500)	No queda nada guardado: repetir con la misma clave ejecuta de nuevo.
Pasaron 24 horas, mismo cuerpo	La MISMA respuesta de la primera vez, como antes. La misma solicitud nunca se convierte en dos notas mientras exista el registro (30 días).
Pasaron 24 horas, cuerpo diferente	La clave está libre: es una solicitud nueva y se ejecuta.
Pasaron 30 días	El registro de la clave se borró: la clave vale como nueva. La referencia sigue protegiendo.

El cuerpo se compara como JSON, con las claves en orden: los espacios y el orden de los campos no cuentan. En POST /v1/lotes con hoja de cálculo, el "cuerpo" es el archivo (hash) más los campos del formulario.

La respuesta repetida es la foto de la primera. Si la primera llamada devolvió 202 transmitindo y la nota se autorizó después, repetir la llamada devuelve el mismo 202. Para el estado actual, usa GET /v1/nfse/{id}.

Reintento correcto

seu sistema                                   Sudrel
    |  POST /v1/nfse                              |
    |  Idempotency-Key: 7f1c...  referencia: PED-1001
    |-------------------------------------------->|
    |            (timeout: a resposta se perdeu)  |  a nota foi criada
    |                                             |
    |  POST /v1/nfse  (MESMA chave, MESMO corpo)  |
    |-------------------------------------------->|
    |<--------------------------------------------|  mesma resposta, mesma nota

Nunca generes una Idempotency-Key nueva para repetir la misma nota. Clave nueva es solicitud nueva. Si la referencia también es nueva, sale otra nota.

En un lote, envía referencia en cada elemento: la fila cuya referencia ya se convirtió en nota aparece como ja_existente y no genera otra nota. Ver Emisión por lotes.