Idempotência

Como evitar nota duplicada

Duas proteções, que se completam:

	Idempotency-Key (cabeçalho)	referencia (campo do corpo)
O que é	Identificador da SUA tentativa de chamada	Identificador da nota no SEU sistema (ex.: número do pedido)
Onde vale	POST /v1/nfse, POST /v1/lotes, POST /v1/webhooks e POST /v1/companies	POST /v1/nfse e cada item de POST /v1/lotes
Obrigatório	Não, mas recomendado	Não, mas recomendado
Escopo	Conta e ambiente (vale para todas as chaves de API da conta naquele ambiente)	Empresa e ambiente
Validade	24 horas de uso exclusivo; a resposta fica guardada por 30 dias	Para sempre
Repetida	Devolve a resposta gravada da primeira vez	409 referencia_duplicada, com o nfse_id da nota que já existe
Tamanho	Texto livre (um UUID serve)	Até 60 caracteres

Use as duas. A Idempotency-Key resolve a retentativa imediata (timeout, queda de rede). A referencia impede a nota dobrada sempre, mesmo que o seu sistema perca a chave.

O que acontece em cada caso

Situação	Resultado
Mesma Idempotency-Key, mesmo corpo	A MESMA resposta da primeira vez (status e corpo), sem criar nada. Vale para 201, 202 e para os 422 nfse_rejeitada e falha_transmissao.
Mesma Idempotency-Key, corpo diferente	409 idempotencia_conflito. Nada é criado.
A primeira chamada com a chave ainda está em andamento	A segunda espera cerca de 3 segundos. Se a primeira não terminou, 409 conflito: espere e repita.
A primeira chamada terminou em erro sem criar nada (412, 422 validacao, 409 referencia_duplicada, 403, 404, 500)	Nada fica gravado: repetir com a mesma chave executa de novo.
Passaram 24 horas, mesmo corpo	A MESMA resposta da primeira vez, como antes. A mesma requisição nunca vira duas notas, enquanto o registro existir (30 dias).
Passaram 24 horas, corpo diferente	A chave está livre: é um pedido novo e é executado.
Passaram 30 dias	O registro da chave foi apagado: a chave vale como nova. A referencia continua protegendo.

O corpo é comparado como JSON, com as chaves em ordem: espaço e ordem dos campos não contam. Em POST /v1/lotes com planilha, o "corpo" é o arquivo (hash) mais os campos do formulário.

A resposta repetida é a foto da primeira. Se a primeira chamada voltou 202 transmitindo e a nota autorizou depois, repetir a chamada devolve o mesmo 202. Para o status de agora, use GET /v1/nfse/{id}.

Retentativa certa

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 gere uma Idempotency-Key nova para repetir a mesma nota. Chave nova é pedido novo. Se a referencia também for nova, sai outra nota.

Em lote, mande referencia em cada item: a linha cuja referência já virou nota aparece como ja_existente e não vira outra nota. Veja Emissão em lote.