Produto

Nota fiscal duplicada na integração: entenda por que acontece e como evitar

Timeout com retry, webhook repetido e venda reprocessada: os 3 caminhos da nota duplicada e a defesa de cada um, com Idempotency-Key e externalRef.

Lucas Rannye6 min de leitura
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.

Manual dos Contribuintes do Sistema Nacional NFS-e: item 1.4.1, o identificador da DPS, e item 1.4.2 a, a consulta GET /dps/id

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

  1. Escolha o id do pedido como identidade da venda e use-o na chave e na referência.
  2. Mande Idempotency-Key em toda emissão e repita o corpo igual no retry.
  3. Grave o id de cada evento recebido e descarte o que já foi processado.
  4. Envie externalRef em toda nota e trate o 409 como "essa venda já tem nota".
  5. No webhook de volta, descarte o deliveryId já visto e decida pelo status.
  6. 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:

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.

Lucas RannyeFundador da emite.ai

A próxima nota é com a gente.

Comece agora