Consulta NF-e Modelo 55 emitidas contra o seu CNPJ via Web Service
NFeDistribuicaoDFedo Ambiente Nacional (SEFAZ Federal).
- Carrega seu certificado digital A1 (
.pfxou.p12) e extrai o CNPJ automaticamente - Conecta ao WebService NFeDistribuicaoDFe da SEFAZ com autenticação mútua TLS
- Consulta NF-e Modelo 55 destinadas ao seu CNPJ a partir do último NSU registrado
- Salva localmente o NSU e as notas para não perder o controle sequencial
- Exibe as notas em uma tabela com: chave de acesso, emitente, valor, data, situação
- Respeita o cooldown de 60 minutos do SEFAZ com timer regressivo
- Permite exportar as notas em JSON
- Windows 10 ou 11
- Certificado digital A1 (arquivo
.pfxou.p12) com senha - Acesso à internet para o WebService da SEFAZ
- Acesse https://www.python.org/downloads/
- Clique em "Download Python 3.x.x" (versão mais recente)
- Execute o instalador baixado
⚠️ IMPORTANTE: marque a opção "Add Python to PATH" antes de clicar em Install Now- Conclua a instalação normalmente
O Tkinter (interface gráfica) já vem incluído no instalador oficial — não precisa instalar separado.
- Clique com o botão direito no arquivo
nfe_consulta.zip - Selecione "Extrair tudo..." e escolha uma pasta (ex:
C:\nfe_consulta)
- Abra o Prompt de Comando (
cmd) ou o PowerShell`- Pressione
Win + R, digitecmde pressione Enter
- Pressione
- Navegue até a pasta do projeto:
cd C:\nfe_consulta - Instale as dependências:
Aguarde o download e instalação (requer internet).
pip install -r requirements.txt
Ainda no Prompt de Comando, dentro da pasta do projeto:
python main.pyA janela do sistema abrirá automaticamente.
Crie um arquivo chamado iniciar.bat dentro da pasta do projeto com o conteúdo:
@echo off
python main.py
pauseDepois basta dar duplo clique no iniciar.bat para abrir o sistema.
- Clique em 📁 e selecione o arquivo
.pfxou.p12do seu certificado - Digite a senha do certificado e clique em CARREGAR CERTIFICADO
- O CNPJ é extraído automaticamente do certificado
- Verifique o CNPJ e selecione o ambiente (Produção ou Homologação)
- Clique em ⟳ CONSULTAR NF-e
- Aguarde o resultado na tabela; dê duplo clique numa nota para ver os detalhes
| Situação | Comportamento |
|---|---|
| Primeira consulta | NSU = 0 (retorna últimos 90 dias) |
| Consultas subsequentes | Usa o último NSU salvo (sequência obrigatória) |
| Rejeição 656 | Consumo indevido — aguarde 60 minutos |
| Sem documentos novos | cStat 137 — normal, nada novo desde o último NSU |
nfe_consulta/
├── main.py # Ponto de entrada
├── requirements.txt
├── src/
│ ├── app.py # Interface gráfica (Tkinter)
│ ├── certificado.py # Leitura do .pfx e extração de CNPJ
│ ├── sefaz_client.py # Cliente SOAP NFeDistribuicaoDFe
│ ├── parser.py # Parser XML (resNFe, procNFe, procEventoNFe)
│ └── storage.py # Persistência NSU e notas (JSON local)
├── data/
│ ├── nsu_estado.json # NSU por CNPJ (criado automaticamente)
│ └── notas/ # Notas por CNPJ (criado automaticamente)
└── logs/ # (reservado para logs futuros)
O NSU (Número Sequencial Único) é crítico:
- O SEFAZ exige que as consultas sejam feitas em ordem crescente e sem pular valores
- O sistema salva automaticamente o último NSU após cada consulta em
data/nsu_estado.json - Se outra aplicação (ERP, portal da SEFAZ) tiver feito consultas, use "Forçar NSU" no painel lateral para sincronizar o ponto de partida
- O arquivo
.pfxnão é copiado — apenas lido em memória - Os arquivos PEM temporários usados para a conexão TLS são deletados imediatamente após cada consulta
- A senha do certificado não é salva em nenhum arquivo
| Erro | Solução |
|---|---|
ImportError: cryptography |
pip install cryptography |
No module named tkinter |
sudo apt install python3-tk |
| Certificado inválido | Verifique se é A1 e se a senha está correta |
| Rejeição 656 | Aguarde 60 min — outra aplicação usou o serviço |
| HTTP 500 | Instabilidade do servidor SEFAZ — tente mais tarde |