Emissão NF-e Passo a Passo

Da montagem do payload ao envio, consulta, DANFE e cancelamento.

Guia passo a passo para emissão de NF-e (Nota Fiscal Eletrônica — Modelo 55) via API REST JSON. Abrange operações mercantis B2B, atacado, e-commerce, devoluções, acompanhamento assíncrono e geração de DANFE e XML protocolado.

BASE URL

https://api.nfer.me/v1

Fluxo de Emissão em 2 Etapas

A emissão na NFER é estruturada em duas etapas assíncronas para garantir velocidade no checkout e resiliência contra lentidões ou indisponibilidades temporárias da SEFAZ:

1POST /v1/nfe

Criar Rascunho

Calcula impostos, valida regras de negócio e reserva o próximo número sequencial da série. Responde 201 Created em ~50ms com o ID da nota.

2POST /v1/nfe/:id/send

Transmitir à SEFAZ

Assina o XML com o Certificado Digital A1 e transmite o lote ao Web Service da SEFAZ. Responde 202 Accepted imediatamente.

3Webhook / Poll

Obter Resultado

Receba o evento nfe.autorizada via Webhook com chave de 44 dígitos e URLs de DANFE e XML, ou faça polling prudente a cada 3 a 5 segundos.

Vantagem da Emissão em 2 Etapas

Se a conexão de rede cair entre a etapa 1 e 2, seu ERP retém o id retornado e pode chamar POST /v1/nfe/:id/send novamente sem o risco de gerar duplicidade ou queimar um novo número fiscal.

Passo 1: Criar Rascunho (POST /v1/nfe)

Envie os dados do destinatário (cadastrado previamente com customerId ou inline no campo destinatario) e os itens da venda:

POST/v1/nfe

Cria o rascunho com cálculo tributário automático e reserva de número.

curl -s -X POST https://api.nfer.me/v1/nfe \

-H "X-API-Key: $NFER_KEY" \

-H "Content-Type: application/json" \

-d '{

"naturezaOperacao": "VENDA DE MERCADORIA",

"tipoOperacao": "1",

"finalidade": 1,

"serie": 1,

"destinatario": {

"tipoPessoa": "J",

"cpfCnpj": "00000000000191",

"nome": "TECH STORE COMERCIO LTDA",

{

"id": "7b8f9e12-3456-4abc-9def-123456789abc",

"numero": 1042,

"serie": 1,

"modelo": "55",

"status": "rascunho",

"valor_total": 1200.00,

"created_at": "2026-09-20T18:00:00.000Z"

}

Passo 2: Transmitir à SEFAZ (POST /v1/nfe/:id/send)

Com o identificador id retornado na etapa 1, ordene o envio assíncrono para a SEFAZ estadual:

POST/v1/nfe/:id/send

Assina com certificado A1 e transmite à SEFAZ.

curl -s -X POST https://api.nfer.me/v1/nfe/7b8f9e12-3456-4abc-9def-123456789abc/send \

-H "X-API-Key: $NFER_KEY"

{

"message": "Nota colocada na fila de processamento",

"status": "processando"

}

Passo 3: Receber Autorização e Arquivos

Quando a SEFAZ homologa a nota, o status muda para autorizada e os links de DANFE em PDF e XML protocolado são gerados:

Arquivo	Endpoint	Formato
DANFE A4	`GET /v1/nfe/:id/danfe`	PDF oficial pronto para impressão
XML Protocolado	`GET /v1/nfe/:id/xml`	XML com protocolo de autorização (procNFe)

Devolução de Mercadoria (Finalidade 4)

Em operações de troca ou devolução no e-commerce, a SEFAZ exige o referenciamento da chave de acesso da nota original. O NFER possui um endpoint de conveniência que gera a devolução invertendo emitente e destinatário:

POST/v1/nfe/:id/devolucao

Gera rascunho de devolução referenciando a nota original.

curl -s -X POST https://api.nfer.me/v1/nfe/7b8f9e12-3456-4abc-9def-123456789abc/devolucao \

-H "X-API-Key: $NFER_KEY" \

-H "Content-Type: application/json" \

-d '{

"itens": [

{

"nItem": 1,

"quantidade": 1,

"motivo": "Devolução por desistência do comprador"

}

]

Próximos Passos

Configure o recebimento instantâneo em Webhooks NF-e.
Entenda cancelamentos e CC-e em Cancelamento, CC-e e Inutilização.