Idempotência na emissão de NFS-e: repetir a chamada sem duplicar a nota

O seu sistema chama a API para emitir uma nota e a resposta não chega: timeout, queda de rede, servidor reiniciado no meio. A nota foi emitida ou não? Se você chamar de novo e ela já tinha saído, o cliente recebe duas notas e alguém vai ter que cancelar uma. Se não chamar, pode ficar sem nota nenhuma. Idempotência é o que tira essa dúvida da sua mão.

A chave da tentativa

Na API de emissão da Sudrel, cada tentativa pode levar o cabeçalho Idempotency-Key, um identificador que o seu sistema gera (um UUID, por exemplo) e guarda junto com o pedido. A regra, por 24 horas:

• Mesma chave e mesmo corpo: a mesma resposta, sem nota nova.
• Mesma chave e corpo diferente: erro 409. É quase sempre um bug, a mesma chave reaproveitada para outra nota, e a API prefere recusar a adivinhar.

Com isso, a regra do seu lado fica simples: na dúvida, repita a chamada com a mesma chave.

A referência, para além das 24 horas

O campo referencia é o identificador do pedido ou da venda no seu sistema. Ele protege contra a duplicata que acontece fora da janela da chave: o job que roda de novo no dia seguinte, a fila reprocessada depois de uma queda. Uma segunda nota com a mesma referência recebe erro 409 referencia_duplicada, com o id da nota que já existe, para o seu sistema seguir com ela. E é pela referência que você encontra a nota depois, sem precisar guardar o id da Sudrel.

E a duplicata do outro lado

Existe uma segunda fonte de nota dobrada, e ela não depende do seu código: a comunicação entre a plataforma e o Sistema Nacional também cai. Quando isso acontece, a Sudrel não reenvia às cegas. Ela consulta a DPS primeiro: se a nota já tinha sido autorizada do outro lado, ela é recuperada; se não chegou, é reenviada. Enquanto isso, a nota aparece como transmitindo, e a orientação é não reenviar.

Lote também

O lote pela API aceita até 5.000 notas numa chamada, e a mesma lógica vale item a item: com referencia em cada um, reenviar o lote inteiro depois de uma falha não duplica as notas que já tinham dado certo.

Perguntas frequentes

O Idempotency-Key é obrigatório?

Não, mas sem ele uma repetição da chamada pode virar uma segunda nota. Para emissão, use sempre.

Que valor usar na chave?

Qualquer identificador único da tentativa, gerado pelo seu sistema e guardado antes de chamar. Um UUID resolve. O importante é que a repetição use a mesma chave, e uma nota nova use uma chave nova.

Depois de 24 horas, posso repetir a chave?

A chave deixa de valer, mas a referencia continua protegendo: por isso as duas existem juntas.

Os detalhes de cada cabeçalho estão na documentação da API, e o resumo da integração, na página de emissão de NFS-e por API.