Neste artigo
Nota fiscal duplicada quase nunca é erro do fisco. Ela nasce em três momentos da integração: uma chamada que estoura o tempo e é repetida, um aviso de venda que chega duas vezes e uma venda que a plataforma processa de novo. Cada um tem uma defesa própria, e uma não cobre a outra.
Por que a duplicata aparece
Porque a rede falha no pior momento. A nota é gerada e a resposta se perde no caminho de volta. Quem chamou não sabe se deu certo e tenta de novo. Sem reconhecer a repetição, o emissor trata o segundo pedido como venda nova.
O próprio padrão nacional da nota de serviço prevê essa dúvida. Cada declaração (DPS) tem um identificador fixo, formado pelo município, pela inscrição do emissor, pela série e pelo número, e há uma consulta para saber se ela já virou nota.
![]()
Documento oficial: manual das APIs do Emissor Nacional. O GET /dps/{id} devolve a chave da nota a quem é prestador, tomador ou intermediário; o HEAD /dps/{id} só responde se a nota existe, para qualquer certificado válido (item 1.4.2 b).
Cenário 1: timeout seguido de retry
Defesa: Idempotency-Key em toda emissão (doc). O seu sistema manda a nota, a conexão cai antes da resposta e o retry automático dispara. Com a mesma chave no cabeçalho, a segunda chamada não cria nada: recebe a resposta da primeira. O cabeçalho está em padronização na IETF.
POST /api/v1/invoices HTTP/1.1
Host: emitenota.ai
Authorization: Bearer emite_live_sua_chave
Idempotency-Key: pedido-8823
Content-Type: application/json
{
"buyerName": "João da Silva",
"buyerDocument": "12345678901",
"buyerEmail": "joao@exemplo.com",
"valorNF": 150.00,
"descricaoServico": "Assinatura mensal, plano Pro",
"codigoServico": "01.05",
"aliquotaISS": 5,
"externalRef": "pedido-8823"
}
Três regras evitam surpresa. A chave deriva do pedido, nunca de um número aleatório gerado a cada tentativa, senão cada retry parece novo. O retry repete o mesmo corpo, com os mesmos campos e valores: a mesma chave com outro corpo volta 409. E a repetição volta com o cabeçalho Idempotent-Replay: true e tem de ser tratada como sucesso.
Quem integra direto com o Emissor Nacional faz o mesmo com a consulta da DPS: antes de reenviar, pergunta se a nota já saiu.
Cenário 2: o aviso de venda chega duas vezes
Defesa: guardar o id do evento e usar o id do pedido como referência da nota (doc). Plataformas de pagamento e lojas reenviam webhook quando não recebem resposta a tempo, e o mesmo acontece no sentido contrário: a emite.ai tenta entregar cada aviso até 8 vezes, com o mesmo deliveryId em todas as tentativas, e não garante a ordem de chegada. Quem processa o mesmo evento duas vezes, emite duas vezes.
Na entrada, grave o id do evento recebido e descarte o repetido. Na saída, mande o id do pedido em externalRef. Se o pedido já tem nota, a resposta é 200 com a nota que já existia:
HTTP/1.1 200 OK
Content-Type: application/json
Idempotent-Replay: true
{
"id": "inv_a1b2c3d4",
"status": "EMITTED",
"retida": false,
"sandbox": false,
"valorNF": 15000,
"buyerName": "João da Silva",
"buyerDocument": "12345678901",
"createdAt": "2026-11-17T13:20:41.000Z",
"externalRef": "pedido-8823",
"message": "Já existe uma nota com este externalRef nesta conta: nenhuma nota nova foi criada.",
"replay": true
}
Cenário 3: a plataforma reprocessa a venda
Defesa: conferir antes de emitir (doc). Reimportação de pedidos, conciliação do fim do mês e venda editada depois do pagamento trazem de volta um pedido que já tem nota, às vezes dias depois e por outra rotina, que gera outra chave de idempotência.
A referência do pedido cobre esse caso porque é a identidade da venda, não da chamada, e não vence: vale para sempre na conta, inclusive depois de a nota ser cancelada. Se o pedido volta com outro valor, outro comprador ou outra empresa emissora, a API recusa com 409 EXTERNAL_REF_CONFLICT e devolve o id da nota existente, em vez de emitir uma segunda. Para conferir antes, use GET /v1/invoices?externalRef=pedido-8823.
Passo a passo para fechar as três portas
- Escolha o id do pedido como identidade da venda e use-o na chave e na referência.
- Mande
Idempotency-Keyem toda emissão e repita o corpo igual no retry. - Grave o id de cada evento recebido e descarte o que já foi processado.
- Envie
externalRefem toda nota e trate o409como "essa venda já tem nota". - No webhook de volta, descarte o
deliveryIdjá visto e decida pelostatus. - Se uma duplicata passou, cancele a segunda pela API, com a justificativa e a própria
Idempotency-Key. Prazos em cancelamento de nota fiscal.
Como a emite.ai resolve
A API da emite.ai aceita Idempotency-Key em toda emissão e externalRef único por conta, e devolve a nota original em vez de criar outra. Nas integrações com plataformas de venda, confere se a mesma venda e o mesmo produto já têm nota antes de criar uma nova, e a planilha pula a linha de venda que já tem nota. No padrão nacional, quando precisa tentar a emissão de novo, a emite.ai consulta se a DPS já virou nota antes de reenviar. O checklist completo está em API de nota fiscal: 12 perguntas.
Conferido em 14/11/2026. Documentos usados:
- Portal da NFS-e: documentação técnica, Manual dos Contribuintes das APIs do Emissor Público Nacional, itens 1.4.1 e 1.4.2
- IETF: The Idempotency-Key HTTP Header Field (rascunho)
- Documentação da API da emite.ai: idempotência, webhooks e listagem de notas
Perguntas frequentes
Idempotency-Key ou externalRef: preciso dos dois?
Sim. A chave protege a mesma chamada repetida; a referência protege o mesmo pedido que volta por outro caminho, até meses depois.
Cancelei a nota. Posso usar a mesma externalRef na nova?
Não. A referência continua presa à nota cancelada. Para emitir de novo, mande uma referência nova, por exemplo o id do pedido com um sufixo.
O 409 quer dizer que a nota falhou?
Não. Nada novo foi criado: a chave veio com outro corpo ou o pedido já tem nota com outro conteúdo. No segundo caso, o id da nota vem em details.
Webhook fora de ordem pode marcar a nota errada no meu sistema?
Pode, se você confiar na ordem. Decida pelo status e pelo createdAt de cada aviso, nunca pela sequência em que chegaram.



