# Idempotência na emissão fiscal > Idempotência na emissão fiscal é a garantia de que enviar a mesma solicitação de emissão mais de uma vez produz um único documento fiscal. Se uma requisição for repetida por falha de rede, timeout ou retry automático, a API reconhece a duplicidade e devolve o resultado original, evitando notas duplicadas, cobranças em dobro e cancelamentos desnecessários. **Também conhecido como:** Emissão idempotente, Chave de idempotência, Controle de duplicidade na emissão, Idempotency **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** I ## 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. ## Perguntas frequentes ### Idempotência evita rejeições da SEFAZ? Não. Ela evita apenas a criação de documentos duplicados. Se os dados da nota estiverem errados, a rejeição acontece normalmente e a resposta repetida mostrará a mesma rejeição. Corrigir os dados exige uma nova operação. ### Posso usar o número da nota como chave de idempotência? Não é o ideal. A numeração costuma ser definida durante a emissão e pode mudar entre tentativas. É mais seguro usar um identificador da operação de negócio, como o código do pedido, gerado antes do primeiro envio. ### Requisições de consulta também precisam de idempotência? Consultas de status ou download de XML já são naturalmente idempotentes, pois não alteram nada. A preocupação principal está em operações que criam ou modificam algo, como emissão, cancelamento e envio de eventos. ## Termos relacionados - [Retry na integração fiscal](https://conota.dev/glossario/retry-na-integracao-fiscal.md) - [Timeout na emissão fiscal](https://conota.dev/glossario/timeout-na-emissao-fiscal.md) - [Backoff exponencial](https://conota.dev/glossario/backoff-exponencial.md) - [Numeração de documentos fiscais](https://conota.dev/glossario/numeracao-de-documentos-fiscais.md) - [Reprocessamento de emissão fiscal](https://conota.dev/glossario/reprocessamento-de-emissao-fiscal.md) - [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md) --- Fonte: [Idempotência na emissão fiscal](https://conota.dev/glossario/idempotencia-na-emissao-fiscal/) · Atualizado em 2026-10-22