GUIA
Como baixar XML de NF-e em lote pela SEFAZ
O caminho oficial existe, é gratuito e não passa pelo portal. Ele também tem três regras que derrubam quase toda tentativa feita na mão — vale conhecê-las antes de escrever o primeiro script.
O portal da SEFAZ não baixa XML em lote
Quem tenta baixar XML de NF-e em lote pela primeira vez costuma começar pelo portal da NF-e e travar ali. A consulta pública funciona por chave de acesso: são 44 dígitos, um captcha e um documento por vez. Mesmo entrando com certificado digital na consulta completa, o que se vê é uma lista para clicar item a item. Não existe exportação do período inteiro.
Isso não é falha do portal. Ele foi feito para consulta pontual — para conferir se aquela nota específica é válida. O canal desenhado para volume é outro, e a maioria das pessoas nunca ouviu falar dele porque ele não tem tela.
O canal que baixa em lote é o de Distribuição de DFe
A SEFAZ mantém um webservice chamado NFeDistribuicaoDFe. Ele entrega, para o CNPJ que se autentica com o próprio certificado digital, os documentos fiscais eletrônicos em que essa empresa aparece como destinatária: as NF-e emitidas contra ela, os eventos ligados a essas notas (cancelamento, carta de correção) e também os CT-e distribuídos pelo mesmo canal.
O funcionamento é de fila, não de busca. Cada documento recebe um número sequencial, o NSU. Você pergunta o que veio depois de determinado NSU e a SEFAZ devolve o próximo lote; repetindo isso até a fila responder que acabou, você tem o acervo. É esse laço, e não uma tela, que qualquer sistema fiscal sério usa por baixo.
As três regras que travam quem tenta na mão
Antes de montar um script próprio, vale saber o que a SEFAZ classifica como consumo indevido — porque a punição é bloqueio, e ele chega rápido:
- O NSU nunca pode pular para frente arbitrariamente. O avanço é sempre a partir do último valor realmente lido. Chutar um número à frente para “pular” documentos é justamente o padrão classificado como consumo indevido.
- Fila vazia significa esperar. Quando a resposta diz que nenhum documento foi localizado, a consulta seguinte precisa respeitar um intervalo. Insistir imediatamente é o erro mais comum de quem escreve o primeiro laço.
- Consumo indevido bloqueia o CNPJ por mais de uma hora. Não é um aviso: durante o bloqueio nenhuma consulta daquele certificado passa, e as notas que chegarem no meio-tempo só serão lidas depois.
Essas três regras são a razão de o download em lote caseiro quase sempre morrer no segundo mês. A XSafe trata cada uma delas explicitamente: guarda o último NSU por empresa, aplica recuo progressivo quando a fila responde vazia e serializa as consultas para que duas nunca saiam ao mesmo tempo para o mesmo CNPJ.
Resumo e documento completo não são a mesma coisa
A fila entrega dois formatos diferentes de NF-e: o resumo (resNFe), com os dados essenciais da nota, e o documento completo (procNFe), que é o XML assinado com o protocolo de autorização. Em parte dos casos, a liberação do XML completo ao destinatário depende de ele ter manifestado ciência ou confirmação da operação.
A XSafe guarda os dois e diz qual é qual no índice — “NF-e completa” e “Resumo de NF-e” são rótulos distintos na tela e no CSV exportado. O que ela não faz é manifestar em seu nome: a XSafe apenas lê da SEFAZ e nunca envia evento pela sua empresa. Se a sua operação depende de manifestação, ela continua sendo feita onde já é feita hoje, no emissor ou no portal.
O limite de 90 dias, dito antes de você assinar
A fila de distribuição não é um arquivo permanente: ela retém cerca de 90 dias de documentos e descarta o que passa disso. Quem se cadastra hoje pega o que ainda está lá e, daí em diante, tudo o que chegar. O que já saiu não volta — nem pela XSafe, nem por nenhum outro serviço que use o canal oficial.
Vale desconfiar de quem promete recuperar qualquer nota de qualquer época por esse caminho. E vale reparar no efeito prático: quanto mais cedo a captura contínua começa, menor o pedaço de histórico que fica de fora para sempre.
Baixar XML em lote sem escrever uma linha de código
É o que a XSafe faz. Você cadastra o certificado A1 uma vez; a partir daí a consulta ao webservice roda a cada 15 minutos, todo dia, com o seu computador desligado. Cada documento novo entra cifrado e indexado por chave de acesso, CNPJ do emitente, valor e data de emissão.
Para tirar o lote de dentro: exportação do período em ZIP com os XMLs, índice em CSV para conciliação e o pacote mensal por e-mail ao contador. Se quiser ver como isso aparece na tela antes de cadastrar qualquer coisa, o painel de demonstração está aberto, com dados fictícios e sem cadastro.
Se o seu caso é nota de serviço em vez de NF-e, o canal é outro — o ambiente nacional da NFS-e —, e ele está explicado na página de download de NFS-e em lote.
Perguntas de quem já tentou baixar em lote
- Dá para baixar XML de NF-e em lote direto no portal da SEFAZ?
- Não. O portal da NF-e serve para consultar e baixar documento a documento, e a consulta pública ainda pede a chave de acesso de 44 dígitos e a resolução de um captcha a cada vez. Não existe botão de exportar o período inteiro. O canal desenhado para volume é outro: o webservice de Distribuição de DFe, que entrega vários documentos por chamada e exige certificado digital.
- Preciso de certificado digital para baixar em lote?
- Sim. O webservice de Distribuição de DFe é uma conexão mTLS: o certificado da empresa é apresentado no momento da consulta e é ele que identifica de quem são os documentos devolvidos. Não há como consultar a fila de outro CNPJ, e não há como consultar a sua sem o certificado dela. A XSafe usa o A1 (arquivo .pfx) porque ele é um arquivo — o A3, em cartão ou token, exige alguém com o dispositivo plugado, o que não sobrevive a uma rotina que roda de madrugada.
- Quantos documentos vêm por consulta?
- A fila é sequencial e responde por lotes, avançando a partir do último NSU já lido — na prática, algumas dezenas de documentos por chamada, e não o histórico inteiro de uma vez. Baixar um acervo grande é repetir a chamada muitas vezes, respeitando os intervalos, até a fila responder que não há mais nada novo. É exatamente esse laço que a XSafe roda sozinha a cada 15 minutos.
- Consigo recuperar o XML de notas antigas?
- Por esse canal, só o que ainda estiver na fila — ela retém cerca de 90 dias de documentos e descarta o que passa disso. Documento mais antigo que isso não está disponível para ninguém que use a fonte oficial: nem para a XSafe, nem para os concorrentes. Para o que já saiu, as saídas são o XML que o próprio emitente guardou (ele também é obrigado a guardar) ou a consulta avulsa por chave de acesso, uma a uma.
- E depois de baixado, como eu entrego tudo isso ao contador?
- Na XSafe, o acervo do período sai em um arquivo ZIP com os XMLs e em um CSV com o índice (chave de acesso, emitente, valor e data de emissão), que abre no Excel com os acentos no lugar. Além disso, no começo de cada mês o ZIP do mês anterior é enviado por e-mail para o endereço que você cadastrar, sem ninguém precisar abrir o painel.
R$ 24,90 por mês, por CNPJ
NF-e, CT-e e NFS-e no mesmo cofre, baixados das fontes oficiais. 14 dias de teste sem cartão de crédito — e se você cancelar, os documentos continuam baixáveis.
Contador com vários clientes? Existe um plano para escritório.
Leia também
- Como consultar notas emitidas contra meu CNPJUm fornecedor pode emitir uma nota contra a sua empresa sem te avisar. As formas oficiais de descobrir, e o que fazer com nota que você não reconhece.
- Backup automático de XML de nota fiscalPor quanto tempo guardar, onde o XML costuma sumir e como manter uma segunda cópia sem depender de alguém lembrar de copiar pasta.
- Como baixar XML de CT-e automaticamenteO conhecimento de transporte fica com a transportadora, mas o tomador precisa do XML. Ele vem pela mesma fila da NF-e.
- DANFE substitui o XML da nota fiscal?Resposta curta: não. O DANFE é a representação impressa; o documento fiscal é o XML assinado — e o PDF não volta a virar XML.