Dominar a emissão de NF-e e NFC-e em Python é um requisito essencial para desenvolvedores que estão criando sistemas de ERP, PDV ou automatizando rotinas fiscais no backend. Entender as diferenças entre a Nota Fiscal Eletrônica (modelo 55) e a Nota Fiscal de Consumidor (modelo 65) é o primeiro passo. Neste guia, vamos descobrir os requisitos técnicos para emissão, o uso de certificados digitais e como adequar seu software às normas da SEFAZ utilizando a biblioteca PyNFe.
Características da Emissão de NF-e e NFC-e em Python
Entenda as diferenças entre NF-e e NFC-e e aprenda a implementar a emissão, consulta e validação de notas fiscais no seu backend Python usando a biblioteca PyNFe.
Projeto de biblioteca para fazer interface com o webservice de Nota Fiscal eletrônica para Python, disponível sob LGPL.
Biblioteca de interface com os webservices de Nota Fiscal Eletrônica (NF-e) e Nota Fiscal de Consumidor Eletrônico (NFC-e) da SEFAZ e Receita Federal do Brasil, Nota Fiscal de Serviço Eletrônica (NFS-e) para Prefeituras e Manifesto de Documentos Fiscais Eletrônicos (MDF-e).
- Visto de NF-e substituir as notas fiscais séries 1 e 1A.
- Visa NFC-e substituir as notas fiscais modelo 2 e cupom fiscal emitido por ECF.
- NFS-e padrão Abrasf para autorizadores Ginfes e Betha.
- O MDF-e no padrão nacional deverá ser emitido obrigatoriamente no transporte de mercadorias intermunicipais por empresas prestadoras de serviço de transporte ou por outras empresas cujas empresas o transporte seja realizado em veículos próprios, arrendados ou transportadores independentes.
Características
-
NF-e e NFCe:
Dica de Leitura: Se você está trabalhando com o projeto de biblioteca para interface com o webservice de Nota Fiscal eletrônica para Python, é importante também estar por dentro das melhores práticas e dicas para entrevistas técnicas de Python, especialmente se você está desenvolvendo sua carreira na área. Leia nosso artigo sobre Entrevista Técnica Python: Não Trave na Hora do Live Coding para se preparar melhor.
- Atualizado para a versão 4.00
- Modelo de Documento Fiscal 55 e 65
- Configuração para utilização em ambiente de produção e homologação (testes)
- Emissão de notas fiscais normais e em contingência
- Consultar Status do Serviço
- Consultar Cadastro de Contribuintes
- Consultar nota fiscal pela chave de acesso
- Consultar protocolo
- Evento de cancelamento de notas
- Evento de carta de correção
- Evento de inutilização de notas
- Evento de manifestação do destinatário
- Consultar Distribuição DF-e
-
NFS-e:
- Emissão de nota fiscal de serviço eletrônico
- Consultar pelo número da NFS-e
- Consultar por RPS (recibo provisório de serviço)
- Consultar Lote
- Cancelar NFS-e
-
MDF-e:
- Atualizado para a versão 3.00
- Modelo de Documento 58
- Emissão de Manifesto
- Consultar Status do Serviço
- Consulte MDF-e pela chave de acesso
- Consultar MDF-es não encerrados
- Consultar Receita
- Evento de Cancelamento
- Evento de Encerramento de viagem
- Evento de Inclusão de Condutor
- Evento de Inclusão de DF-e
- Evento de Pagamento DF-e
-
CT-e:
- Atualizado para a versão 3.00
- Consultar Distribuição DF-e para CT-e
- Emissão (A fazer)
- Inutilização (A fazer)
- Consultar CT-e pela chave de acesso (A fazer)
- Consultar Status do Serviço (A fazer)
- Eventos relacionados ao CT-e (A fazer)
Dependências
- lxml
- Biblioteca de leitura e gravação de arquivos XML, de alto desempenho e fácil de implementar.
- sinalxml
- Assinatura e validação do XML
- pyopenssl
- Biblioteca para referência do certificado digital
- pedidos
- Biblioteca para a comunicação com os webservices da SEFAZ
- suds-jurko (*apenas para NFS-e)
- Biblioteca para a comunicação com os webservices via wsdl
- pyxb (*apenas para NFS-e)
- Biblioteca para geração de ligações a partir do XML Schema(xsd)
Principais Operações Fiscais com PyNFe
Embora o exemplo acima mostre como consultar o status da SEFAZ, o poder do PyNFe vai muito além. Com base na documentação oficial, a biblioteca oferece suporte completo ao ciclo de vida das notas fiscais. Você pode implementar rapidamente no seu sistema os seguintes fluxos:
- Emissão e Impressão: Além de gerar e assinar o XML da nota, a biblioteca possui suporte nativo para a Impressão da NF-e (DANFE) e NFC-e, facilitando a vida no ponto de venda (PDV).
- Tratamento de Quedas de Conexão: O sistema suporta a Emissão de NF-e em Contingência, garantindo que o seu cliente não pare de faturar se a SEFAZ ficar offline.
- Correções e Cancelamentos: Integração rápida para gerar Cartas de Correção (CC-e) e realizar a Inutilização de Numeração ou Manifestação do Destinatário.
🔫 Leitor de Código de Barras e QR Code Sem Fio
🔐 Leitor de Smartcard USB (Para Certificado Digital A3)
⚡ Hacks para Devs e Automação Fiscal:
- Auto-Entrada de Estoque: Configure um fluxo no n8n para ler os XMLs das NFes recebidas por e-mail, fazer o parse e alimentar o banco de dados (ex: Supabase) automaticamente.
- Offline-First: Em PDVs de NFCe, armazene as notas em IndexedDB para emitir em contingência quando a internet cair, sincronizando o lote depois via Service Workers.
- Frontend Reativo: Substitua o “polling” na SEFAZ por Webhooks + WebSockets. O usuário não precisa atualizar a página; a tela pisca em verde assim que a SEFAZ autoriza o envio.
Ampliando para Logística (MDF-e e CT-e)
Se o seu software em Python atende transportadoras, o PyNFe já está atualizado para a versão 3.00 do MDF-e (Manifesto Eletrônico) e CT-e. Através dele, é possível automatizar desde a emissão do Manifesto até o encerramento da viagem e a inclusão de novos condutores de forma programática.
- Instalação
pip install pynfe
Instalar versão de desenvolvimento:
pip install https://github.com/TadaSoftware/PyNFe/archive/refs/heads/main.zip
Opcional para NFS-e:
pip install --user -r https://github.com/TadaSoftware/PyNFe/blob/main/requirements-nfse.txt
- Status da consulta
from pynfe.processamento.comunicacao import ComunicacaoSefaz
certificado = "/home/user/certificado.pfx"
senha = 'senha'
uf = 'pr'
homologacao = True
con = ComunicacaoSefaz(uf, certificado, senha, homologacao)
xml = con.status_servico('nfe')
print(xml.text)
Mais exemplos no Wiki
Testes
python -m unittest
Instalação: pip install ruff Checar lint: ruff check . Formatar:ruff format .
Documentação
Suporte
Se você tiver qualquer problema ou sugestão, abra um problema aqui ou comece uma discussão sobre um assunto aqui .
Quem utiliza PyNFe
Lista de empresas/projetos que utilizam a lib PyNFe
- Link da lista aqui .
- Sinta-se livre para incluir o nome da empresa/projeto na lista.
Continue aprendendo:
Agora que você já sabe tudo sobre o projeto de biblioteca para interface com o webservice de Nota Fiscal eletrônica para Python, que tal avançar seus conhecimentos em programação com o artigo sobre TypeScript Lidera Ranking do GitHub: A Era da IA e a revolução?
Perguntas Frequentes (FAQ): NF-e vs NFC-e
Qual a diferença básica entre NF-e e NFC-e?
A NF-e (Nota Fiscal Eletrônica – Modelo 55) é usada principalmente para operações de compra e venda entre empresas (B2B), devoluções, exportações e transferências. Já a NFC-e (Nota Fiscal de Consumidor Eletrônica – Modelo 65) é voltada para a venda direta ao consumidor final (B2C) no varejo físico, substituindo o antigo cupom fiscal e o ECF.
Qual certificado digital devo usar no meu servidor de emissão?
Para sistemas automatizados (ERPs e APIs na nuvem), o Certificado A1 é o mais recomendado. Ele é um arquivo digital (geralmente .pfx) que pode ser instalado diretamente no servidor, permitindo assinaturas simultâneas e automáticas sem a necessidade de dispositivos físicos (tokens ou smartcards), ao contrário do modelo A3.
O que acontece se a internet cair durante uma venda com NFC-e?
Diferente da NF-e, a NFC-e permite a emissão em Contingência Offline. O software gera o documento, imprime o DANFE para o cliente e, assim que a conexão for restabelecida (geralmente em um prazo de 24h), o XML deve ser transmitido para a SEFAZ para autorização definitiva.
