Idempotência na emissão fiscal

Por que a idempotência é importante na emissão de notas fiscais?

Na comunicação entre sistemas, nem toda resposta chega ao destino. O ERP pode enviar o pedido de emissão, a nota ser criada e a conexão cair antes que a confirmação volte. Sem saber o que aconteceu, o sistema tende a tentar de novo.

Sem idempotência, essa nova tentativa pode gerar uma segunda nota para a mesma venda. O resultado é retrabalho: cancelar o documento extra, explicar a divergência ao cliente, ajustar a escrituração e, em alguns casos, lidar com prazos de cancelamento já vencidos. Com idempotência, repetir o pedido é seguro, porque a API entende que se trata da mesma operação.

Como funciona a idempotência em uma API fiscal?

O mecanismo mais comum é a chave de idempotência: um identificador único que o sistema do cliente gera para cada operação e envia junto com a requisição, geralmente em um header ou no próprio payload. Pode ser, por exemplo, o código do pedido ou um identificador aleatório criado no momento da venda.

Quando a API recebe a requisição, verifica se aquela chave já foi usada. Se for nova, processa a emissão normalmente e guarda a chave associada ao resultado. Se já existir, não cria outro documento: devolve o status, o identificador e, quando disponíveis, o XML e o PDF da emissão original.

A forma exata de enviar a chave, o tempo em que ela fica registrada e o comportamento em cada caso dependem da documentação da API utilizada.

A SEFAZ e as prefeituras já não impedem notas duplicadas?

Em parte. Os autorizadores rejeitam um documento com o mesmo número, série e emitente de outro já autorizado. Mas essa proteção só funciona se a nova tentativa usar exatamente a mesma numeração.

Se o sistema reservar um número novo a cada tentativa, as duas notas são válidas aos olhos do autorizador, pois têm numerações diferentes. É por isso que a idempotência precisa existir na camada de integração: ela identifica a operação de negócio, e não apenas o número do documento.

Qual a diferença entre idempotência e retry?

Retry é a ação de tentar novamente uma requisição que falhou ou não respondeu a tempo. Idempotência é a propriedade que torna essa repetição segura.

Os dois conceitos andam juntos. Um retry sem idempotência pode multiplicar documentos; idempotência sem retry não resolve falhas temporárias. Na prática, integrações robustas combinam retries com intervalos crescentes entre tentativas, como o backoff exponencial, e sempre reenviam a mesma chave de idempotência.

Como escolher uma boa chave de idempotência?

A chave deve representar uma única operação de negócio e ser gerada antes do primeiro envio, para que todas as tentativas usem o mesmo valor. Identificadores de pedido, de venda ou de ordem de serviço costumam funcionar bem, desde que não se repitam entre empresas ou ambientes diferentes.

Um erro comum é gerar uma chave nova a cada tentativa, o que anula a proteção. Outro é reaproveitar a mesma chave para uma operação diferente, como uma segunda venda ao mesmo cliente. Muitas APIs rejeitam o uso de uma chave já existente com dados diferentes, justamente para sinalizar esse tipo de engano.

Exemplos de Idempotência na emissão fiscal

• Um e-commerce envia o pedido de emissão de NF-e, recebe um timeout e repete a chamada com a mesma chave de idempotência. A API identifica a repetição e devolve a nota já criada, sem gerar uma segunda.
• Um ponto de venda perde a conexão logo após enviar uma NFC-e. Ao reconectar, reenvia a solicitação com o mesmo identificador da venda e recebe o status da emissão original.
• Um software de gestão de serviços usa o código da ordem de serviço como chave ao emitir NFS-e, garantindo que cliques repetidos no botão de emitir não criem notas em duplicidade.
• Uma transportadora reprocessa um lote de CT-e após uma instabilidade e, como cada documento tem sua chave de idempotência, apenas os que não haviam sido criados são efetivamente emitidos.