Captura automática de NF-e via SEFAZ: guia da Distribuição DF-e

O que é a Distribuição DF-e e por que ela existe

Toda vez que um fornecedor emite uma NF-e contra o seu CNPJ, a SEFAZ já tem essa nota. O problema é que, sem um mecanismo formal de entrega, a empresa destinatária ficava esperando o fornecedor mandar o XML por e-mail, WhatsApp ou portal próprio — um processo manual, sujeito a atraso e perda de documento.

A Distribuição de Documentos Fiscais Eletrônicos (DF-e) nasceu para resolver isso. Regulamentada pelo Ajuste SINIEF 5/2018 e especificada tecnicamente na NT 2014.002, ela é um serviço da SEFAZ que entrega ao CNPJ destinatário todas as notas emitidas contra ele, eventos de cancelamento, cartas de correção e manifestações — sem depender do fornecedor fazer mais nada.

Neste guia você vai entender como funciona a captura por NSU, quais documentos entram no fluxo, como o certificado digital se encaixa, quais são as quatro manifestações do destinatário e os erros mais comuns em implementações reais.

---

Como funciona o NSU — o índice das notas

O NSU (Número Sequencial Único) é o mecanismo central da Distribuição DF-e. Pense nele como um contador global da SEFAZ: cada documento fiscal — nota, evento, cancelamento — recebe um NSU em ordem crescente. A empresa destinatária consulta a SEFAZ passando o último NSU que já buscou, e recebe todos os documentos novos a partir daí.

Esse modelo de captura iterativa tem consequências práticas importantes:

• Multi-page de 50 documentos por resposta — cada requisição retorna até 50 registros. Se houver backlog (muitas notas acumuladas), o sistema precisa fazer múltiplas consultas em sequência até esvaziar a fila.
• Retry exponencial — quando a SEFAZ retorna erro de disponibilidade ou timeout, o sistema aguarda intervalos crescentes (ex: 1 min, 2 min, 4 min) antes de tentar de novo, evitando o erro de consumo indevido (código 656).
• NSU nunca retrocede — se um documento chega com NSU 10.500 e o sistema salva esse número, a próxima consulta começa do 10.501. Documentos anteriores ao NSU já consultado não aparecem mais na fila.

O BoxFiscal executa esse ciclo automaticamente por um agendador de jobs em background, com HttpClient compartilhado e seleção dinâmica de certificado por empresa, sem vazamento de conexão no pool da SEFAZ.

---

O que entra na captura — resNFe, procNFe, resEvento e procEvento

A SEFAZ distribui quatro tipos de documento via DF-e, e entender a diferença evita confusão na hora de tratar os XMLs:

Além das notas emitidas diretamente contra o CNPJ da empresa (recebidas), a Distribuição DF-e também entrega documentos em que o CNPJ aparece apenas como citado — por exemplo, uma nota de terceiro que menciona a empresa como transportadora ou como intermediária. O BoxFiscal separa os três papéis em abas distintas: Emitidos, Recebidos e Citados.

---

Certificado A1 vs A3 — qual usar na captura automática

A autenticação na SEFAZ para a Distribuição DF-e exige um certificado digital válido vinculado ao CNPJ da empresa. Os dois padrões disponíveis têm características bem diferentes para captura 24/7:

Certificado A1 (.pfx)

Arquivo de software com validade de 1 ano. É carregado na plataforma uma única vez — o sistema usa a senha para assinar as requisições automaticamente em qualquer horário, sem interação humana. Ideal para captura automática: não exige presença física, não precisa de leitor de cartão, funciona em qualquer servidor. A desvantagem é que o arquivo precisa ser substituído anualmente antes do vencimento.

Certificado A3 (smartcard ou token físico)

O certificado fica gravado em um dispositivo físico (cartão ou token USB). Para cada operação de assinatura, o dispositivo precisa estar conectado ao computador e, em muitos casos, exige interação com PIN. Isso o torna incompatível com automação contínua em servidor — a assinatura só funciona quando o hardware está plugado a uma máquina com o driver correto.

Recomendação para captura SEFAZ automatizada: use certificado A1. O BoxFiscal emite alerta de expiração com antecedência para que o novo certificado seja cadastrado antes do vencimento do anterior, sem interrupção na captura.

---

Manifestação do destinatário — 4 tipos e prazo legal

A manifestação do destinatário é um evento que a empresa destinatária envia à SEFAZ para registrar sua posição sobre uma NF-e recebida. Ela tem efeito legal e prazo definido na NT 2012.002. Existem quatro tipos:

1. Ciência da Operação — confirma que a empresa tomou conhecimento da nota, mas ainda não pode confirmar se a mercadoria foi recebida. Libera o acesso ao XML completo (procNFe) na Distribuição DF-e.
2. Confirmação da Operação — a mercadoria foi recebida e a operação está confirmada. Esse evento impede o emitente de cancelar a nota após 24h da emissão.
3. Desconhecimento da Operação — a empresa declara que não reconhece aquela transação. Útil para fraudes ou notas emitidas indevidamente contra o CNPJ.
4. Operação Não Realizada — a empresa reconhece que a nota foi emitida, mas a entrega não aconteceu (mercadoria devolvida, operação cancelada antes de sair). Deve ser acompanhada de justificativa.

O prazo para manifestar é de 180 dias corridos a partir da data de autorização da NF-e (NT 2012.002). Após esse prazo, a SEFAZ bloqueia o envio da manifestação. Por isso, a automação da captura e da manifestação não é só conveniência — é gestão de prazo legal.

No BoxFiscal, a manifestação é feita diretamente na tela de documentos, sem sair do sistema. O status de cada nota é atualizado em tempo real após o envio para a SEFAZ.

---

Erros comuns na captura DF-e

Implementações manuais ou mal configuradas costumam travar nos mesmos pontos:

• Código 656 — consumo indevido: a SEFAZ bloqueia temporariamente o CNPJ quando o sistema faz consultas com frequência acima do limite permitido. A causa é ausência de retry exponencial — o sistema erra, tenta de novo imediatamente, e entra em loop. A solução é backoff progressivo após cada erro de disponibilidade.
• Certificado expirado: a SEFAZ retorna erro de autenticação e a captura para silenciosamente. Sem alerta proativo, a empresa só descobre dias depois que as notas não chegaram. Certificado A1 com validade de 1 ano exige rotina de renovação antes do vencimento.
• NSU duplicado: quando o sistema não salva o último NSU consultado de forma atômica (antes de processar os documentos), uma falha durante o processamento faz o sistema reconsultar o mesmo intervalo e tentar inserir documentos já existentes. O resultado é erro de constraint no banco ou duplicação silenciosa.
• Sem resposta da SEFAZ: a SEFAZ tem janelas de manutenção programada (geralmente madrugadas de domingo). Um sistema robusto registra o estado “sem resposta” e retoma do mesmo NSU quando o serviço volta, sem pular documentos.

---

Como o BoxFiscal executa a Distribuição DF-e

O BoxFiscal foi construído em cima da Distribuição DF-e como mecanismo principal de captura de notas recebidas. Veja como cada ponto crítico está resolvido:

• 1 clique para configurar: cadastro do certificado A1 na tela /config/certificados, vinculação com a empresa, e a captura começa no próximo ciclo agendado. Sem instalar software, sem configurar driver de A3.
• Captura 24/7 agendada: jobs agendados rodam em background com fila dedicada para captura SEFAZ, separada da fila de processamento de documentos e de envio do Kit Contador.
• Retry exponencial nativo: o código de retry está embutido no worker de captura — código 656 e erros de disponibilidade da SEFAZ acionam backoff automático.
• Multi-page transparente: quando há backlog, o sistema percorre todas as páginas de 50 documentos até NSU atualizado, sem intervenção manual.
• Manifestação direta na tela: Ciência, Confirmação, Desconhecimento e Operação Não Realizada disponíveis na interface — sem trocar de sistema.
• Round-robin por conta: a fila de processamento usa window function SQL (ROW_NUMBER OVER PARTITION BY ContaId), garantindo que uma empresa com alto volume não trava as demais.
• Alerta de expiração de certificado: o sistema notifica antes do vencimento do A1 para que o novo certificado seja cadastrado sem interrupção da captura.
• Monitor em tempo real: a tela /config/monitor mostra o status da última captura, NSU atual e logs de erro — o auditor que confere CST/CSOSN trabalha sobre os mesmos documentos capturados.

Tudo isso faz parte da captura automática 24/7 do BoxFiscal — sem planilha de controle, sem aguardar e-mail do fornecedor.

---

Perguntas frequentes sobre Distribuição DF-e

---

Conclusão — captura é a base de tudo

Sem notas chegando automaticamente, toda a gestão de documentos fiscais fica comprometida: relatórios incompletos, auditorias com lacunas, Kit Contador Mensal com XML faltando. A Distribuição DF-e por NSU é o mecanismo oficial da SEFAZ para resolver isso — e a qualidade da implementação (retry, multi-page, certificado, manifestação dentro do prazo) determina se a captura é confiável ou uma fonte constante de problema.