NFER
Visão GeralQuick StartAutenticaçãoAmbientesConfiguração InicialExemplos de RequisiçãoGlossário FiscalChecklist de Go-LiveFAQModelo de DadosCiclo de Vida & FluxoContingência AutomáticaLimites & Rate LimitEvitando DuplicidadeErros e RetransmissãoSplit Fiscal HíbridoNovoConceitosEmissão Passo a PassoConceitosEmissão Passo a PassoConceitosEmissão Passo a PassoCódigos de ServiçoConceitosEmissão Passo a PassoNovoRegimes, CST e CFOPEventos FiscaisVisão Geral & CronogramaNovos Campos na APITabela cClassTribDevoluções & AnulaçõesChecklist de MigraçãoVisão Geral & NSUCorporate+NF-e Recebidas & MD-eCorporate+NFS-e Tomadas (ADN)Corporate+CT-e Fretes & DesacordoCorporate+White-Label & Org APIEmpresaCertificado A1 & CSCHabilitação SEFAZCadastrosNumeraçãoPlanos

Evitando Duplicidade na Emissão

Ausência de Idempotency-Key externa, rascunho com UUID e chave única sequencial.

Em emissões fiscais, a duplicidade de notas é uma falha grave perante o fisco que pode gerar cobrança indevida de tributos ou rejeições como o cStat 204: Rejeição: Duplicidade de NF-e. Esta página explica o mecanismo nativo da arquitetura do NFER para evitar duplicidades acidentais.

Não há cabeçalho Idempotency-Key

A API externa do NFER não utiliza o cabeçalho HTTP Idempotency-Key para emissão de notas. A prevenção de duplicidade é garantida pela arquitetura de emissão em duas etapas com retenção de UUID e pela restrição de unicidade sequencial no banco de dados.

O Mecanismo em 2 Etapas

Para blindar seu ERP ou e-commerce contra retransmissões duplas (por exemplo, cliques repetidos do operador ou quedas de conexão), adote o seguinte padrão:

1

Criação do Rascunho com UUID Imutável

A chamada inicial (POST /v1/nfe) gera um identificador único id (UUID v4) e reserva o próximo número sequencial da série sob a restrição única:

UNIQUE (company_id, serie, numero, environment)

A resposta HTTP 201 Created entrega o id da nota recém-criada.

2

Persistência do ID no Banco do seu ERP

Regra Crítica: Assim que receber a resposta do NFER, grave imediatamente o id da nota no registro do pedido no banco de dados do seu sistema.

Dessa forma, sua aplicação sabe exatamente qual rascunho fiscal corresponde àquele pedido comercial.

3

Transmissão Segura por ID

Para autorizar a nota perante a SEFAZ, chame POST /v1/nfe/:id/send passando o id gravado.

Caso ocorra timeout de rede ou queda de conexão durante essa chamada, você pode repetir o comando POST /v1/nfe/:id/send quantas vezes forem necessárias. A API operará sobre o mesmo documento já existente, sem consumir novo número nem gerar nota duplicada.

O que Fazer se a Criação Sofrer Timeout?

Se a primeira chamada (POST /v1/nfe) cair por timeout antes de seu servidor receber o corpo da resposta HTTP, não reenvie a criação imediatamente.

  • Consulte a listagem recente de notas via GET /v1/nfe?limit=5.
  • Verifique se a nota para aquele destinatário e valor já foi gravada.
  • Se foi gravada, capture seu id e proceda com o envio.
  • Se não constar na lista, reenvie a criação com segurança.

Próximos Passos

AnteriorLimites & Rate LimitPróximoErros e Retransmissão