Nota Fiscal Eletrônica: Tudo que um Programador Precisa Saber Para Integrar NF-e

A Nota Fiscal Eletrônica (NF-e) é um dos padrões técnicos mais importantes do ecossistema de negócios brasileiro. Todo sistema de gestão, e-commerce ou ERP desenvolvido no Brasil precisa emitir, processar ou consumir NF-e em algum momento. Este guia cobre o que todo desenvolvedor precisa saber.

O que é a NF-e tecnicamente

A NF-e é um arquivo XML com estrutura definida pelo Manual de Orientação do Contribuinte (MOC) publicado pela SEFAZ nacional e pelos estados. O arquivo segue o padrão XML Schema (XSD) disponível publicamente em nfe.fazenda.gov.br.

O ciclo de vida de uma NF-e:

1. Geração do XML pelo emissor (empresa)
2. Assinatura digital com certificado A1 ou A3 (ICP-Brasil)
3. Transmissão para a SEFAZ via WebService SOAP
4. Autorização pela SEFAZ (retorna a chave de acesso de 44 dígitos)
5. Impressão do DANFE (documento auxiliar)
6. Armazenamento do XML por 5 anos

Estrutura básica do XML da NF-e

A NF-e tem uma hierarquia clara:

NFe
└── infNFe
    ├── ide (identificação da nota)
    ├── emit (emitente)
    ├── dest (destinatário)
    ├── det[] (itens/produtos)
    │   ├── prod (dados do produto)
    │   └── imposto (ICMS, PIS, COFINS, IPI)
    ├── total (totais da nota)
    ├── transp (transporte)
    ├── cobr (cobrança/duplicatas)
    └── infAdic (informações adicionais)

Ambientes: Homologação vs Produção

Todo desenvolvimento começa no ambiente de homologação (tpAmb=2), onde as notas são aceitas mas não têm valor fiscal. Só depois de testes completos você migra para produção (tpAmb=1).

A URL dos WebServices muda conforme o estado e o ambiente. Para consulta da situação de uma nota em produção:
https://nfe.fazenda.gov.br/NFeConsultaProtocolo4/NFeConsultaProtocolo4.asmx

Bibliotecas em PHP para NF-e

nfephp-org/sped-nfe (recomendada)

A mais completa e mantida ativamente:

composer require nfephp-org/sped-nfe

// Configuração básica
use NFePHPNFeMake;
use NFePHPNFeTools;

$config = [
    'atualizacao' => '2026-01-01T00:00:00',
    'tpAmb' => 2, // 1=prod, 2=homologação
    'razaosocial' => 'Empresa Teste Ltda',
    'cnpj' => '12345678000195',
    'siglaUF' => 'SP',
    'schemes' => 'PL_009_V4',
    'versao' => '4.00',
    'tokenIBPT' => '',
];

$tools = new Tools(json_encode($config), Certificate::readPfx(
    file_get_contents('/path/to/cert.pfx'),
    'senha_certificado'
));

Bibliotecas em Python

PyNFe

pip install PyNFe

from pynfe.processamento.serializacao import SerializacaoXML
from pynfe.entidades import Emitente, Destinatario, NotaFiscal

# Criar a nota fiscal
nf = NotaFiscal()
nf.uf = 'SP'
nf.natureza_operacao = 'Venda de mercadorias'
# ... configurar emitente, destinatário, produtos, impostos

Webservices SEFAZ: operações principais

Certificado Digital: o que integrar

Toda NF-e precisa ser assinada com certificado digital ICP-Brasil. Para sistemas web:

• Certificado A1 (arquivo .pfx): armazenado no servidor. Mais fácil de integrar automaticamente, mas menos seguro. Recomendado para emissão automatizada em servidor.
• Certificado A3 (token/smartcard): mais seguro mas exige hardware físico do usuário. Complicado para sistemas web.

Para leitura do certificado A1 em PHP:

$pfx = file_get_contents('/secure/path/certificado.pfx');
$senha = 'senha_certificado'; // armazene em variável de ambiente!
openssl_pkcs12_read($pfx, $certs, $senha);

NFS-e: nota de serviço (mais complexa)

Diferentemente da NF-e de produtos (padrão nacional), a NFS-e (serviços municipais) é fragmentada: cada prefeitura tem seu próprio WebService, layout e regras. Existem algumas iniciativas de padronização (ABRASF), mas a cobertura ainda é incompleta.

Para integrar NFS-e, recomenda-se usar uma plataforma intermediária como:

• eNotas: API única que cobre 3.500+ municípios
• feegow: focado em saúde e serviços
• Nuvem Fiscal: API moderna cobrindo NF-e, NFS-e e MDF-e

Boas práticas de implementação

• Nunca hardcode a senha do certificado — use variáveis de ambiente
• Implemente retry com backoff exponencial para chamadas aos WebServices SEFAZ
• Armazene sempre o XML autorizado e o protocolo de autorização
• Monitore o prazo de validade do certificado digital (geralmente 1 ou 3 anos)
• Teste exaustivamente em homologação antes de ir para produção
• Implemente a contingência offline (NF-e em Contingência DPEC ou EPEC) para quando a SEFAZ estiver fora

A integração com NF-e é um dos trabalhos mais específicos do ecossistema brasileiro de desenvolvimento. Mas uma vez implementado corretamente, é uma fonte de valor enorme para qualquer sistema de gestão.