NFeDistribuicaoDFe: Consulta de NF-e e documentos fiscais eletrônicos

A Nota Técnica 2014.002 regulamenta o Web Service NFeDistribuicaoDFe, serviço dedicado a disponibilizar informações e documentos fiscais eletrônicos de interesse para os diversos atores da Nota Fiscal Eletrônica (NF-e). Este recurso otimiza o acesso a documentos fiscais para emitentes, destinatários, transportadores e terceiros autorizados.

Histórico de atualizações do serviço

O Web Service NFeDistribuicaoDFe passou por diversas atualizações para aprimorar sua funcionalidade. A versão inicial (1.00) foi implantada em produção em janeiro de 2014. Desde então, a nota técnica incorporou melhorias significativas.

• A versão 1.02b, por exemplo, incluiu a distribuição de eventos como Registro de Passagem, Pedido de Prorrogação/Cancelamento do prazo de suspensão do ICMS e outros eventos de resposta do Fisco. Também possibilitou a consulta por chave de acesso de NF-e.
• A Nota Técnica 2014.002 v1.13 introduziu a disponibilização de eventos do Fisco para emitente e destinatário, mesmo quando fossem iguais.
• O retorno do ultNSU na rejeição 656, em consultas distNSU, foi adicionado na versão 1.14.
• Na Nota Técnica 2014.002 v1.15, o retorno do NSU se tornou facultativo.
• A versão mais recente, Nota Técnica 2014.002 v1.20, implantada em produção em junho de 2024, incluiu o evento "Ator Interessado".

O Web Service NFeDistribuicaoDFe

O serviço NFeDistribuicaoDFe distribui documentos e informações relevantes para o ator da NF-e. Ele é um processo síncrono que utiliza o método nfeDistDFeInteresse. Pode ser consumido por qualquer pessoa física ou jurídica que possua um certificado digital (PF ou PJ).

A autenticação para Pessoa Jurídica permite consultas para qualquer CNPJ do estabelecimento, desde que o CNPJ base (os 8 primeiros dígitos) consultado seja o mesmo do certificado digital utilizado. Os documentos fiscais eletrônicos e informações resumidas ficam disponíveis para distribuição por até 90 dias após sua recepção pelo Ambiente Nacional da NF-e.

Documentos e atores atendidos

A distribuição de documentos fiscais e eventos é realizada para diversos atores, conforme seu papel na NF-e:

• Emitente: Recebe eventos de manifestação do destinatário, eventos da Suframa (vistoria/internalização), eventos do Fisco em resposta a pedido de prorrogação, evento de averbação, resumos de eventos CT-e/MDF-e/Registro de Passagem e eventos de comprovante de entrega (propagados do CT-e e na NF-e).
• Destinatário: Tem acesso à NF-e (após manifestação), eventos de cancelamento, carta de correção, eventos da Suframa, eventos de pedido de prorrogação de prazo, eventos do Fisco em resposta a pedido de prorrogação, evento de averbação, resumo de NF-e (antes da manifestação), resumos de eventos CT-e/MDF-e/Registro de Passagem e eventos de comprovante de entrega.
• Transportador: A NF-e estará disponível para o transportador identificado no grupo X03 ou no evento 'Ator Interessado'. Recebe NF-e, eventos de cancelamento, carta de correção, EPEC, evento de averbação, resumos de eventos CT-e/MDF-e/Registro de Passagem e eventos de comprovante de entrega.
• Terceiros: Pessoas cujo CNPJ ou CPF esteja informado na tag autXML terão acesso à NF-e, eventos de cancelamento, carta de correção, eventos de manifestação do destinatário, eventos da Suframa, evento de averbação, resumos de eventos CT-e/MDF-e/Registro de Passagem e eventos de comprovante de entrega.
• CNPJ em evento 'Ator Interessado': CNPJs informados neste evento também recebem NF-e, eventos de cancelamento, carta de correção, EPEC, evento de averbação, resumos de eventos CT-e/MDF-e/Registro de Passagem e eventos de comprovante de entrega.

Para o destinatário, a NF-e completa só é retornada se houver manifestação ("Ciência da Operação", "Operação Não Realizada" ou "Confirmação de Operação"). Caso contrário, é retornado apenas o resumo da NF-e, com as informações necessárias para realizar a manifestação. Eventos de cancelamento são disponibilizados ao destinatário mesmo sem manifestação prévia.

Mensagens de entrada e retorno

A comunicação com o Web Service NFeDistribuicaoDFe envolve mensagens XML de entrada (pedido de distribuição) e retorno.

Mensagem de entrada (pedido de distribuição)

A estrutura XML de entrada, baseada no schema distDFeInt_v9.99.xsd, contém os dados da solicitação. Campos relevantes incluem:

• tpAmb: Indica o ambiente (1 para Produção, 2 para Homologação).
• cUFAutor: Código da Unidade da Federação do autor da solicitação.
• CNPJ ou CPF: Identificador do interessado no DFe.
• Tags específicas para cada tipo de consulta: distNSU, consNSU ou consChNFe.

Mensagem de retorno

O retorno do serviço, limitado a um máximo de 50 documentos, é uma estrutura XML conforme o schema retDistDFeInt_v9.99.xsd. Contém:

• tpAmb: Ambiente da resposta.
• verAplic: Versão do aplicativo que processou a consulta.
• cStat: Código do status da resposta (ex: 137 para nenhum documento localizado, 138 para documento localizado).
• xMotivo: Descrição literal do status da resposta.
• dhResp: Data e hora da mensagem de resposta.
• ultNSU: Último NSU pesquisado no Ambiente Nacional, indicando o ponto para continuar futuras consultas.
• maxNSU: O maior NSU existente no Ambiente Nacional para o CNPJ/CPF consultado.
• loteDistDFeInt: Conjunto de informações resumidas e documentos fiscais eletrônicos.
• docZip: Cada documento fiscal eletrônico ou informação resumida, compactado no padrão Gzip.

Mensagem de retorno compactada

O tamanho médio de uma NF-e é de aproximadamente 10 KB. Para minimizar a demanda de infraestrutura de rede, cada documento (tag:docZip) na mensagem de retorno é compactado individualmente no padrão Gzip (GNU zip). Essa compactação pode reduzir o tamanho da mensagem em cerca de 60%. A aplicação cliente é responsável por descompactar o conteúdo antes de processar o documento.

Processo de distribuição de documentos fiscais eletrônicos

O Ambiente Nacional gera um Número Sequencial Único (NSU) para cada documento fiscal de interesse, atribuído a cada interessado. A geração do NSU, a partir da versão 1.10 da Nota Técnica, considera apenas os usuários do serviço nos últimos 60 dias.

• Para usuários que utilizam o serviço continuamente, a geração de NSU prossegue normalmente.
• Novos usuários ou aqueles que não utilizam o serviço por mais de 60 dias não terão NSU gerados retroativamente para o período de inatividade. A geração é retomada a partir do primeiro acesso com o método distNSU.

O XML de pedido de distribuição aceita três modalidades de consulta:

1. distNSU: Distribuição de conjunto de DFe a partir do NSU informado

A aplicação cliente deve informar o ultNSU que possui. O Ambiente Nacional fornece todos os documentos (NF-e e eventos) disponíveis para o interessado a partir desse NSU. Se o NSU informado for menor que o primeiro NSU disponível, o sistema retorna documentos dos últimos 90 dias.

A formação dos lotes de documentos obedece às seguintes regras:

• Ordem crescente de NSU.
• Lote pode conter qualquer tipo de documento válido e seu NSU.
• Quantidade máxima de 50 documentos por lote.

Os documentos são disponibilizados conforme o papel do interessado como ator da NF-e e devem formar uma sequência numérica sem lacunas. A consulta é limitada a documentos recebidos pelo Ambiente Nacional nos últimos 90 dias. A geração do NSU é organizada por ordem de inserção dos documentos, não pela data de emissão ou autorização.

2. consNSU: Consulta de DFe vinculado ao NSU informado

Este método permite consultar um NSU específico que foi identificado como faltante na base de dados do interessado. A aplicação cliente informa o NSU desejado, e o Ambiente Nacional retorna um único documento fiscal (NF-e ou evento) correspondente. Esta consulta também está disponível para documentos recebidos nos últimos 90 dias.

3. consChNFe: Consulta de NF-e por chave de acesso informada

Permite consultar pontualmente uma NF-e pela chave de acesso. A chave informada deve ser válida, existir no Ambiente Nacional e estar vinculada ao interessado (destinatário, transportador ou terceiro). O Ambiente Nacional retorna apenas a NF-e (sem eventos) referente à chave. Desde a versão 1.15 da Nota Técnica, esta consulta não exige a prévia geração de NSU para o documento fiscal. A disponibilidade é de 90 dias.

CPF ou CNPJ do interessado

É mandatório informar o CPF da pessoa física ou CNPJ da empresa para recuperar os DFe. Para empresas, um único certificado digital permite a recuperação de DFe de qualquer estabelecimento, desde que o CNPJ base do certificado corresponda ao do CNPJ consultado.

Envio das informações

O pedido de distribuição é realizado por meio do Web Service, e é obrigatório o uso de um certificado digital (PJ ou PF) válido. A aplicação cliente do interessado aciona o WS do Ambiente Nacional, enviando uma mensagem XML que deve seguir os padrões estabelecidos na nota técnica.

Validações no Web Service NFeDistribuicaoDFe

O serviço executa diversas validações para assegurar a conformidade e a segurança das operações.

Validação do certificado de transmissão

São realizadas validações obrigatórias no certificado digital do transmissor:

• A01: Validade e tipo do certificado.
• A02: Validade do certificado (data início e fim).
• A03: Verificação da cadeia de certificação (AC emissora, revogação, assinatura).
• A04: Verificação da Lista de Certificados Revogados (LCR).
• A05: Certificado do Transmissor revogado.
• A06: Certificado Raiz difere da "ICP-Brasil".
• A07: Ausência da extensão de CNPJ ou CPF no certificado.

Validação inicial da mensagem

Antes de processar a requisição, a mensagem passa por validações preliminares:

• B01: Tamanho do XML de dados superior a 10 KB (erro 214).
• B02: Servidor de processamento paralisado momentaneamente (erro 108).
• B03: Servidor de processamento paralisado sem previsão (erro 109).

Validação da área de dados

Inclui validações de forma e de regras de negócio específicas.

Validação de forma da área de dados

• D01: Schema XML da área de dados (erro 215).
• D02: Uso de prefixo no namespace (erro 404).
• D03: XML utiliza codificação diferente de UTF-8 (erro 402).
• D04: Versão dos dados informada superior à vigente (erro 238).
• D05: Versão dos dados não suportada (erro 239).

Validação de regras de negócio

• H01: Tipo do ambiente da NF-e difere do ambiente do Web Service (erro 252).
• H02/H03: CNPJ ou CPF do interessado na distribuição inválido (erros 489/490).
• H04/H05: CNPJ base ou CPF do certificado digital diferente do consultado (erros 593/472).
• H06: NSU informado superior ao maior NSU disponível (erro 589).
• H07-H13: Chave de Acesso inválida (dígito verificador, UF, ano, mês, CNPJ, modelo, número da NF, erros 236, 614-619).
• H14: NF-e inexistente para a chave de acesso informada (erro 217).
• H15: NF-e fora do prazo de download de 90 dias (erro 632).
• H16: CNPJ/CPF do interessado sem permissão para consultar a NF-e (erro 640).
• H17: NF-e indisponível para o emitente (erro 641).
• H18/H19: NF-e Cancelada ou Denegada, arquivo indisponível para download (erros 653/654).

Leiautes resumidos

Para permitir o compartilhamento de informações essenciais de forma mais leve e com sigilo, foram criados leiautes com dados resumidos da NF-e e de eventos.

Leiaute resumo da NF-e

A estrutura XML resNFe_v9.99.xsd é um conjunto de informações resumidas da NF-e, gerado pelo Ambiente Nacional quando a NF-e é autorizada ou denegada. Este documento é distribuído aos destinatários, fornecendo dados suficientes para sua manifestação na operação. Inclui a chave de acesso da NF-e, CNPJ/CPF do emitente, razão social, inscrição estadual, data de emissão, tipo de operação, valor total da NF-e, Digest Value, data de autorização, número de protocolo e a situação da NF-e.

Leiaute resumo do evento de NF-e

A estrutura XML resEvento_v9.99.xsd contém informações resumidas de um evento de NF-e. Inclui o código do órgão de recepção, CNPJ/CPF do emitente, chave de acesso da NF-e, data e hora do evento, tipo e número sequencial do evento, descrição, data de autorização e número de protocolo do evento.

Visão geral do modelo de distribuição

O modelo de distribuição baseia-se na geração de um Número Sequencial Único (NSU) para cada CNPJ ou CPF. O fluxo abaixo detalha a sequência de geração de NSU para emitente e destinatário:

1. O emitente gera e transmite uma NF-e, que é autorizada pela Sefaz e compartilhada com o Ambiente Nacional.
2. O Ambiente Nacional gera um NSU para o destinatário referente ao resumo da NF-e e o disponibiliza para consulta.
3. O destinatário consulta o Web Service NFeDistribuicaoDFe com seu último NSU e recupera o resumo da NF-e.
4. Com o resumo, o destinatário gera um evento de manifestação de NF-e.
5. O Ambiente Nacional gera um NSU do evento para o emitente e o disponibiliza para consulta.
6. Caso seja um evento de manifestação do destinatário diferente de "desconhecimento da operação", o Ambiente Nacional gera um NSU para o destinatário com a NF-e completa para download.
7. O emitente consulta o Web Service NFeDistribuicaoDFe e recupera o evento gerado pelo destinatário.
8. O destinatário consulta o Web Service NFeDistribuicaoDFe e recupera a NF-e completa.
9. O emitente gera um evento para sua NF-e (ex.: cancelamento), que é compartilhado com o Ambiente Nacional.
10. O Ambiente Nacional gera um NSU para o destinatário referente ao evento gerado pelo emitente e o disponibiliza para consulta.
11. O destinatário consulta o Web Service NFeDistribuicaoDFe e recupera o evento gerado pelo emitente.
12. O Ambiente Nacional recebe um evento gerado pelo Fisco e gera um NSU para o emitente e outro para o destinatário, disponibilizando-os para consulta.
13. Ambos, emitente e destinatário, consultam o Web Service NFeDistribuicaoDFe e recuperam o evento gerado pelo Fisco.

Este modelo permite ao emitente consultar os eventos manifestados pelos destinatários de suas NF-e. Da mesma forma, o destinatário acessa qualquer evento gerado pelo emitente e os eventos do Fisco. O processo de download da NF-e é simplificado, pois a manifestação do destinatário aciona automaticamente a geração de um NSU referenciando a NF-e completa para recuperação.

Recomendações para evitar o uso indevido

O Web Service NFeDistribuicaoDFe implementa controles para identificar e gerenciar situações de uso indevido, como tentativas repetitivas de busca de registros já consultados. Requisições que configuram uso indevido são rejeitadas com o código 656-Rejeição: Consumo Indevido.

Uso indevido na consulta distNSU

1. Não há mais documentos a distribuir e o usuário continua consultando: Se o retorno cStat=137 (Nenhum documento localizado) for recebido, o usuário deve aguardar uma hora antes de realizar uma nova consulta. Novas consultas dentro desse período de uma hora configuram uso indevido, resultando em bloqueio do CNPJ por uma hora.
2. Usuário não está consultando os NSU de forma sequencial: É mandatório utilizar sempre o ultNSU retornado na consulta anterior. Se o ultNSU for igual ao maxNSU (indicando que não há mais documentos a serem recuperados no momento), é preciso aguardar uma hora para novas consultas. Desrespeitar essa sequência resulta em bloqueio.

É fundamental que as aplicações de um mesmo ator (seja emitente, destinatário, transportador ou informado na tag autXML) sigam a mesma sequência ordenada e ascendente de NSU para o mesmo CNPJ (14 dígitos) para evitar bloqueio por uso indevido. O número da última consulta (ultNSU) é retornado na rejeição 656, permitindo retomar a sequência.

Uso indevido nas consultas consChNFe e consNSU

Estas consultas são projetadas para buscar pontualmente uma NF-e ou um NSU específico, limitadas a um período retroativo de 90 dias. Para o download de todas as NF-e de um CNPJ ator interessado dentro desse prazo, a consulta distNSU deve ser utilizada.

• Consultada uma quantidade de NF-e ou NSU superior ao limite permitido por hora: Há um limite de 20 consultas por chave de acesso ou NSU em um período de uma hora. Exceder esse limite resulta na mensagem 656 - Consumo indevido e bloqueio do CNPJ por uma hora.

Em qualquer modalidade de consulta, ao receber a mensagem 656 - consumo indevido, o usuário deve aguardar uma hora. Se a consulta for retomada antes de completar esse período, o tempo de bloqueio é zerado, reiniciando a contagem de uma hora.

Endereços do Web Service NFeDistribuicaoDFe

Os endereços para acesso ao Web Service de Distribuição do Ambiente Nacional são publicados no Portal Nacional da NF-e (http://www.nfe.fazenda.gov.br/portal) e no Portal de Homologação (http://hom.nfe.fazenda.gov.br/portal), acessíveis no menu 'Serviços' / 'Relação de Servios Web'.

Tabela de códigos de erros

O sistema utiliza códigos e descrições para indicar o resultado do processamento da solicitação ou os motivos de não atendimento. Abaixo, alguns exemplos:

• 108: Serviço Paralisado Momentaneamente.
• 109: Serviço Paralisado sem Previsão.
• 137: Nenhum documento localizado.
• 138: Documento localizado.
• 214: Rejeição: Tamanho da mensagem excedeu o limite.
• 215: Rejeição: Falha no schema XML.
• 217: Rejeição: NF-e inexistente para a chave de acesso informada.
• 236: Rejeição: Chave de Acesso com dígito verificador inválido.
• 238: Rejeição: Versão do arquivo XML superior à Versão vigente.
• 239: Rejeição: Versão do arquivo XML não suportada.
• 252: Rejeição: Ambiente informado diverge do Ambiente de recebimento.
• 280-286: Rejeições referentes a problemas no Certificado Transmissor (inválido, data de validade, cadeia de certificação, revogado, ICP-Brasil, LCR).
• 402: Rejeição: XML da área de dados com codificação diferente de UTF-8.
• 404: Rejeição: Uso de prefixo de namespace não permitido.
• 472: Rejeição: CPF consultado difere do CPF do Certificado Digital.
• 473: Rejeição: Certificado Transmissor sem CNPJ ou CPF.
• 489/490: Rejeição: CNPJ/CPF informado inválido.
• 589: Rejeição: NSU informado superior ao maior NSU disponível.
• 593: Rejeição: CNPJ-Base consultado difere do CNPJ-Base do Certificado Digital.
• 614-619: Rejeições para Chave de Acesso inválida (Código UF, Ano, Mês, CNPJ, modelo, número NF).
• 632: Rejeição: Solicitação fora de prazo (NF-e não disponível para download após 90 dias).
• 640: Rejeição: CNPJ/CPF do interessado não possui permissão para consultar esta NF-e.
• 641: Rejeição: NF-e indisponível para o emitente.
• 653/654: Rejeição: NF-e Cancelada/Denegada, arquivo indisponível para download.
• 656: Rejeição: Consumo Indevido.
• 999: Rejeição: Erro não catalogado.

Conclusão

O Web Service NFeDistribuicaoDFe representa um recurso essencial para a gestão de documentos fiscais eletrônicos, permitindo que diversos atores da NF-e acessem informações e documentos de seu interesse de forma padronizada e segura. A compreensão dos tipos de consulta (distNSU, consNSU, consChNFe), do modelo de geração de Número Sequencial Único (NSU) e das regras para evitar o uso indevido é fundamental para otimizar a recuperação de dados e garantir a conformidade fiscal. As contínuas atualizações, como a inclusão do evento "Ator Interessado" na versão 1.20, demonstram a evolução do serviço para atender às demandas do ambiente tributário brasileiro.