Endpoints NF-e

Referência completa e detalhada dos endpoints REST da NFER para NF-e (Nota Fiscal Eletrônica — Modelo 55) e DC-e. A API permite emitir notas fiscais, gerar arquivos XML e DANFE PDF (A4), gerenciar devoluções de e-commerce, cancelamentos e cartas de correção (CC-e) com sincronização direta na SEFAZ. Para emissão de Cupom Fiscal Eletrônico (Modelo 65), consulte a seção dedicada de Endpoints NFC-e.

Ciclo de Vida da NF-e (Como Emitir)

A emissão na NFER é projetada para ser rápida, resiliente e imune a lentidões da SEFAZ. O fluxo é dividido em 3 etapas simples:

Tabela Geral de Endpoints

1. Criar Rascunho de NF-e (POST /v1/nfe)

Você pode passar o destinatário de duas formas: diretamente no corpo da requisição (customer) ou usando o ID de um cliente previamente cadastrado (customerId).

Tabela de Parâmetros Principais (POST /v1/nfe)

2. Transmitir para a SEFAZ (POST /v1/nfe/:id/send)

Dispara a assinatura digital com certificado A1 e o envio do lote para os servidores da SEFAZ estadual.

Resposta imediata da fila:

3. Consultar Status e Dados (GET /v1/nfe/:id)

Retorna todos os dados da nota fiscal, incluindo chave de acesso de 44 dígitos, protocolo de autorização, valores calculados e mensagens de erro da SEFAZ caso tenha sido rejeitada.

4. Corrigir e Reenviar Nota com Erro (PUT /v1/nfe/:id)

Se a SEFAZ rejeitar a nota (ex: cStat 321 ou 539), nunca gere um novo rascunho. Atualize os dados da mesma nota usando PUT /v1/nfe/:id e chame /send novamente. Isso garante que o mesmo número sequencial seja utilizado, sem furos de numeração.

5. Download de XML e DANFE PDF

Após a autorização na SEFAZ, o NFER armazena o XML protocolado e gera o DANFE em PDF de alta qualidade para impressão.

DANFE Simplificado Tipo 2 em Bobina Térmica — NT 2026.003 v1.00 (tpImp = 6)

Instituído pelo Ajuste SINIEF 13/2026 e regulamentado pela Nota Técnica NT 2026.003 v1.00, o DANFE Simplificado Tipo 2 permite imprimir a NF-e (modelo 55) em bobina contínua de impressora térmica (largura de 80mm ou 58mm).

Para quem é e por que usar: Varejistas, atacadistas com balcão de vendas, distribuidores, materiais de construção e autopeças. Em vez de operar com dois modelos fiscais e certificados separados (NFC-e para consumidor e NF-e para empresas), o estabelecimento unifica 100% das emissões na NF-e modelo 55, imprimindo o cupom térmico no balcão com agilidade para pessoas físicas ou jurídicas (com direito a crédito tributário de ICMS, IBS e CBS).

Impressão Térmica Direta ESC/POS (PDVs, Totens e Balcão)

Para quem é e para que serve: Desenvolvido para desenvolvedores de Frente de Caixa (PDV), terminais de autoatendimento e sistemas de balcão. O ESC/POS é o protocolo binário nativo de impressoras térmicas não-fiscais (Epson, Elgin, Bematech, Daruma, etc.). Em vez de abrir a tela de PDF do navegador (Ctrl+P), seu sistema envia os bytes diretamente para a porta USB/Rede (/dev/usb/lp0 ou socket TCP), imprimindo em milissegundos com corte de guilhotina automático.

6. Nota de Devolução e Troca (E-commerce e Varejo) — NT 2025.002 (Regra VC02-14)

Quando um cliente pede troca ou devolução de um pedido cujo prazo de cancelamento (24h) já expirou, a legislação fiscal brasileira exige a emissão de uma Nota Fiscal de Devolução de Entrada (finalidade 4). Desde 01/09/2026, a SEFAZ exige estritamente a amarração de documento fiscal referenciado por item no grupo <DFeReferenciado> (regra VC02-14 da NT 2025.002), além de pagamento forma: "90" (Sem Pagamento, valor 0.00).

7. Cancelamento de NF-e (POST /v1/nfe/:id/cancel)

O cancelamento só pode ser solicitado se a mercadoria ainda não saiu para entrega e dentro do prazo legal da SEFAZ estadual (geralmente 24 horas). A justificativa deve conter no mínimo 15 caracteres.

8. Carta de Correção Eletrônica — CC-e (POST /v1/nfe/:id/correction-letter ou /v1/nfe/:id/cce)

A Carta de Correção Eletrônica (CC-e) é usada para sanar erros simples em notas fiscais já autorizadas sem anular o documento original. O evento deve ser transmitido em até 720 horas (30 dias) após a autorização da NF-e.

9. Inutilização de Numeração (POST /v1/nfe/inutilizar)

Se houve uma quebra na sequência de numeração fiscal (ex: pulou do número 105 para o 110 por falha interna do ERP ou interrupção de rede), você deve justificar a inutilização desses números perante a SEFAZ até o 10º dia do mês seguinte para evitar autuações fiscais.

Modelos suportados: NF-e (modelo: "55"), NFC-e (modelo: "65") e CT-e (modelo: "57", também disponível via POST /v1/cte/inutilizar). Documentos de serviço (NFS-e Nacional / ADN) e Declaração de Conteúdo (DC-e) não possuem evento fiscal de inutilização na legislação brasileira.

10. Emissão em Lote (POST /v1/nfe/batch)

Permite enviar até 50 notas de uma única vez para processamento paralelo de alta velocidade. Ideal para fechamento de vendas diárias ou expedições de e-commerce.

11. NFC-e — Cupom Fiscal Eletrônico (Modelo 65)

Para ponto de venda (PDV) e frente de caixa. O destinatário é opcional (venda anônima no balcão). Para emissões com CPF na nota, envie o objeto customer (com CPF e nome) inline no payload, ou referencie um customerId existente. Requer o CSC (nfceIdCsc e nfceTokenCsc) configurado no cadastro da empresa.

Tabela de Parâmetros Principais (POST /v1/nfce)

Impressão Térmica Direta (ESC/POS) e PDF Sob Demanda

Para PDVs e terminais de caixa, a NFER gera comandos nativos de bobina térmica ESC/POS (suporte a Epson, Elgin, Bematech, Daruma e maquininhas Smart POS Android) com QR Code desenhado em hardware e corte de papel automático:

• Retorno imediato no JSON / Webhook: Ao autorizar, o GET /v1/nfce/:id e o evento de webhook nfe.autorizada já entregam a chave escpos (Base64) e escpos_url, permitindo cuspir os dados para o spooler sem fazer requisições extras.
• Endpoint Dedicado: GET /v1/nfce/:id/escpos?largura=80 (ou largura=58, cut=false, format=raw|base64|json). O formato raw retorna application/octet-stream pronto para envio via raw TCP socket (porta 9100) ou porta serial/USB.
• PDF Sob Demanda: O PDF do DANFE não bloqueia o worker na emissão da NFC-e ou NFS-e. Ele é gerado e armazenado em cache no storage sob demanda apenas se alguém acessar o link /danfe/:chave, mantendo a autorização ultrarrápida (sub-segundo).

12. SEFAZ — Status & Consulta de Cadastro (Sintegra)

Endpoints diretos de comunicação com os autorizadores estaduais da SEFAZ. Permite verificar a disponibilidade em tempo real da SEFAZ estadual e validar a situação cadastral de clientes (IE oficial, Razão Social e endereço fiscal) via protocolo mTLS com o Certificado Digital A1 da sua empresa.