NFeDistribuicaoDFe: Consulta DF-e por NSU e Chave de Acesso (2024)

O Web Service NFeDistribuicaoDFe é um serviço fundamental no Projeto Nota Fiscal Eletrônica, projetado para fornecer aos envolvidos nos processos da NFe acesso eficiente e confiável a documentos fiscais eletrônicos (DF-e) e informações de seu interesse. Esta funcionalidade, detalhada na Nota Técnica 2014.002, versão 1.20 de Maio de 2024, visa regulamentar a distribuição de documentos para emitentes, destinatários, transportadores e terceiros autorizados.

NFeDistribuicaoDFe: O serviço de distribuição

O Web Service NFeDistribuicaoDFe distribui documentos e informações relevantes para os atores da NFe. Sua função principal é disponibilizar informações resumidas e documentos fiscais eletrônicos para qualquer pessoa física ou jurídica que possua um certificado digital, mesmo que não os tenha gerado diretamente. Este serviço opera de forma síncrona, utilizando o método nfeDistDFeInteresse e segue o pacote de schemas PL_NFeDistDFe_102.

Escopo e autenticação

Uma Pessoa Jurídica pode autenticar-se pelo CNPJ base (os oito primeiros dígitos) e realizar consultas para qualquer CNPJ completo (14 dígitos) da empresa, desde que o CNPJ base consultado corresponda ao do certificado digital. Os documentos e informações resumidas ficam disponíveis para distribuição por até 90 dias após a recepção pelo Ambiente Nacional da NFe.

Para o destinatário, o Ambiente Nacional verifica a existência de uma manifestação (Ciência da Operação, Operação Não Realizada ou Confirmação de Operação). Se houver manifestação, a NFe completa é retornada. Caso contrário, apenas o resumo da NFe é disponibilizado, fornecendo os dados necessários para que o destinatário realize a manifestação. Para transportadores e terceiros, a NFe é integralmente disponibilizada na consulta.

Documentos distribuídos e atores interessados

A distribuição de documentos é realizada para os seguintes atores, com base em seu papel na NFe e informações específicas no XML:

Emitente: CNPJ informado no grupo do Emitente.
Destinatário: CNPJ informado no grupo do Destinatário.
Transportador: CNPJ informado no grupo do Transportador.
Terceiros: CNPJ ou CPF informado no grupo de pessoas físicas autorizadas a acessar o XML.
CNPJ informado em evento 'Ator Interessado'.

A tabela a seguir detalha quais documentos são distribuídos para cada ator:

Documentos	Emitente	Destinatário	Transportador	Terceiros	CNPJ em 'Ator Interessado'
NFe	Não	Sim	Sim	Sim	Sim
Evento de Cancelamento	Não	Sim	Sim	Sim	Sim
Evento de Carta de Correção	Não	Sim	Sim	Sim	Sim
Eventos de Manifestação do Destinatário	Sim	Não	Não	Sim	Não
Eventos da Suframa (Vistoria/Internalização)	Sim	Sim	Não	Sim	Não
EPEC	Não	Sim	Sim	Não	Sim
Eventos de Pedido de Prorrogação de Prazo	Não	Sim	Não	Não	Não
Eventos do Fisco em Resposta ao Pedido de Prorrogação	Sim	Sim	Não	Não	Não
Evento de Averbação	Sim	Sim	Sim	Sim	Sim
Resumo de NFe	Não	Sim	Não	Não	Não
Resumo de Eventos CTe Autorizado/Cancelado	Sim	Sim	Sim	Sim	Sim
Resumo de Eventos MDFe Autorizado/Cancelado	Sim	Sim	Sim	Sim	Sim
Resumo de Eventos de Registro de Passagem	Sim	Sim	Sim	Sim	Sim
Evento de Comprovante de Entrega propagado do CTe	Sim	Sim	Sim	Sim	Sim
Evento de Comprovante de entrega na NFe e Cancelamento	Não	Sim	Sim	Sim	Sim

Observações sobre a distribuição:

Os documentos e resumos de eventos são disponibilizados ao destinatário após sua manifestação (Ciência da Operação, Operação Não Realizada ou Confirmação de Operação). A exceção é o Evento de Cancelamento, que é disponibilizado independentemente da manifestação. Antes da manifestação, o destinatário acessa apenas o resumo da NFe e o cancelamento.
Para o transportador, a NFe fica disponível se ele for identificado no grupo X03 ou no evento 'Ator Interessado na NFe' (código 110150).
Terceiros com CNPJ ou CPF na "tag autXML" têm acesso à NFe.
Eventos de Pedido de Prorrogação de Prazo, como EPP1 e EPP2, e seus cancelamentos (ECPP1 e ECPP2), estão previstos na Nota Técnica 2015.001.
Os eventos do Fisco em resposta a pedidos de prorrogação, como EFPP1 e EFPP2, também são da Nota Técnica 2015.001.
Eventos de averbação são distribuídos conforme o Boletim Técnico 2017/001 v1.0.
Eventos de comprovante de entrega propagados do CTe são distribuídos a partir do Boletim Técnico 2019.001 v.1.10.
Desde a versão 1.13 da Nota Técnica, eventos gerados pelo Fisco são distribuídos ao emitente independentemente da manifestação do destinatário, mesmo que emitente e destinatário sejam o mesmo.

Estrutura das mensagens

A comunicação com o Web Service NFeDistribuicaoDFe utiliza mensagens XML para solicitação e retorno.

Mensagem de entrada: Tipos de consulta

A mensagem de entrada, conforme o Schema XML distDFeInt_v9.99.xsd, permite três tipos de consultas, identificadas por tags específicas:

distNSU - Distribuição de conjunto de DF-e a partir do NSU informado:
- O cliente informa o último Número Sequencial Único (ultNSU) que possui. O Ambiente Nacional fornece todos os documentos (NFe e eventos) disponíveis a partir desse NSU.
- Se o NSU informado for menor que o primeiro NSU disponível, a consulta retorna documentos autorizados nos últimos 90 dias, a partir do NSU mais antigo dentro desse período.
consNSU - Consulta DF-e vinculado ao NSU informado:
- Permite a consulta pontual de um DF-e (NFe ou evento) a partir de um NSU específico que o interessado identificou como faltante em sua base de dados. O Ambiente Nacional retorna um único documento referente ao NSU solicitado.
consChNFe - Consulta de NFe por chave de acesso informada:
- Permite a consulta pontual de uma NFe através de sua chave de acesso. O cliente informa uma chave de acesso válida, e o Ambiente Nacional retorna somente a NFe (sem eventos) relacionada àquela chave.
- Desde a versão 1.15 desta Nota Técnica, não é mais necessária a prévia geração de NSU para a NFe consultada por chave de acesso.

A mensagem de entrada também requer informações como o tipo de ambiente (produção/homologação), o código da UF do autor (cUFAutor) e o CNPJ ou CPF do interessado. Para pessoas jurídicas, o CNPJ base do certificado digital deve corresponder ao CNPJ base consultado, permitindo a recuperação de DF-e de qualquer estabelecimento da empresa com um único certificado.

Mensagem de retorno: Estrutura e compactação

A mensagem de retorno, seguindo o Schema XML retDistDFeInt_v9.99.xsd, contém os documentos de interesse do ator, com um máximo de 50 documentos por lote. Ela inclui dados como:

tpAmb: Identificação do ambiente (1=Produção / 2=Homologação).
verAplic: Versão do aplicativo que processou a consulta.
cStat: Código do status da resposta.
xMotivo: Descrição literal do status da resposta.
dhResp: Data e hora da resposta.
ultNSU: Último NSU pesquisado no Ambiente Nacional, útil para continuar consultas.
maxNSU: Maior NSU existente no Ambiente Nacional para o CNPJ/CPF consultado.
loteDistDFeInt: Conjunto de informações resumidas e DF-e.
docZip: Informação resumida ou documento fiscal eletrônico, compactado no padrão Gzip.

Para minimizar a demanda de infraestrutura de rede, cada documento na mensagem de retorno é compactado individualmente (campo docZip) utilizando o padrão Gzip. Estima-se uma redução de aproximadamente 60% no tamanho da mensagem. A aplicação cliente deve descompactar e processar o documento descompactado.

Processo de distribuição de documentos

O serviço pode ser consumido por emitentes, destinatários, transportadores ou terceiros (com CPF ou CNPJ no grupo autXML), tanto pessoas físicas quanto jurídicas, utilizando certificado digital.

Geração de NSU

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

Para usuários que consultam o serviço nos últimos 60 dias, a geração de NSU continua normalmente.
Para novos usuários (distNSU), a geração de NSU começa a partir do primeiro acesso, sem retroatividade.
Se um usuário deixar de usar o serviço (distNSU) por mais de 60 dias, a geração de NSU é interrompida e retomada na próxima consulta, sem retroatividade para o período de interrupção.

Nestes casos, o primeiro acesso pode retornar "cStat=137 - Nenhum documento localizado". Após uma hora, e respeitando as regras de uso indevido, as consultas subsequentes podem retornar documentos. A verificação de continuidade do uso do serviço se dá pelo CPF ou CNPJ-base da requisição.

Antes de gerar NSU para transportadores e CNPJ informados no grupo autXML, o sistema verifica se esses CNPJs também são destinatários na mesma NFe. Se sim, o NSU só é gerado após a manifestação do destinatário.

Os documentos recuperados devem apresentar uma sequência numérica sem intervalos na base de dados do interessado. O processo de recepção e sincronização no Ambiente Nacional não segue a ordem cronológica de emissão ou autorização, mas sim a ordem de inserção dos documentos, garantindo que todos os documentos sejam recuperados assim que recebidos. É prudente manter um controle do primeiro NSU válido para consulta.

As respostas do Web Service podem ser:
* Rejeição: Mensagem com o motivo da falha no cStat.
* Nenhum documento localizado: cStat=137.
* Documento(s) localizado(s): cStat=138.

Após receber cStat=137, o interessado deve aguardar no mínimo uma hora antes de fazer uma nova solicitação de distribuição. Se o ultNSU informado for igual ao maxNSU retornado, isso indica que não há mais documentos a serem pesquisados no momento.

Validações no Web Service

O processo de consulta no Web Service NFeDistribuicaoDFe inclui diversas etapas de validação para garantir a segurança e a integridade das informações.

Validação do certificado de transmissão

O certificado digital utilizado na transmissão da mensagem é validado quanto a:

Inexistência ou formato inválido do certificado.
Validade (datas de início e fim).
Cadeia de certificação (AC emissora, revogação, assinatura).
Lista de Certificados Revogados (LCR).
Status de revogação.
Certificado Raiz diferente de "ICP-Brasil".
Falta da extensão de CNPJ ou CPF.

Muitas dessas validações são realizadas pelo protocolo SSL, mas a validação de "Certificado Raiz difere da ICP-Brasil" pode exigir atenção se houver outros certificados de Autoridade Certificadora Raiz não ICP-Brasil no servidor.

Validação inicial da mensagem

O Web Service realiza uma validação inicial da mensagem XML:

Tamanho do XML: Mensagens com mais de 10 KB são rejeitadas (código 214). O controle pode ser feito no aplicativo ou na rede.
Servidor paralisado: Verifica se o servidor de processamento está paralisado momentaneamente (código 108) ou sem previsão (código 109).

Validação da área de dados

A área de dados da mensagem passa por validações de forma e regras de negócio:

Validação de forma:
- Verificação do Schema XML da área de dados (código 215).
- Uso de prefixo no namespace não permitido (código 404).
- Codificação XML diferente de UTF-8 (código 402).
- Versão dos Dados superior à vigente (código 238) ou não suportada (código 239).
Validação de regras de negócio:
- Ambiente da NFe diferente do ambiente do Web Service (código 252).
- CNPJ ou CPF do interessado inválido (códigos 489, 490).
- CNPJ base do certificado digital diferente do CNPJ base consultado (código 593).
- CPF do certificado digital diferente do CPF consultado (código 472).
- NSU informado superior ao maior NSU disponível (código 589) – para consultas distNSU e consNSU.
- Chave de Acesso inválida (códigos 236, 614, 615, 616, 617, 618, 619) – para consulta consChNFe.
- NFe inexistente para a chave de acesso (código 217).
- NFe fora do prazo de 90 dias para download (código 632).
- CNPJ/CPF do interessado sem permissão para consultar a NFe (código 640).
- NFe indisponível para o emitente (código 641).
- NFe Cancelada ou Denegada, arquivo indisponível para download (códigos 653, 654).

Leiautes resumidos

Para viabilizar o compartilhamento de informações relevantes com sigilo, foram desenvolvidos leiautes para informações resumidas de NFe e de seus eventos.

Leiaute resumo da NFe

A estrutura XML resNFe_v9.99.xsd contém informações resumidas da NFe, gerada pelo Ambiente Nacional quando a NFe é autorizada ou denegada. Este resumo é distribuído aos destinatários para permitir sua manifestação na operação. Inclui campos como:

chNFe: Chave de acesso da NFe.
CNPJ / CPF: CNPJ ou CPF do emitente.
xNome: Razão social ou nome do emitente.
IE: Inscrição Estadual do emitente.
dhEmi: Data de emissão da NFe.
tpNF: Tipo de operação (0=Entrada; 1=Saída).
vNF: Valor total da NFe.
digVal: Digest Value da NFe.
dhRecbto: Data de autorização da NFe.
nProt: Número de protocolo da NFe.
cSitNFe: Situação da NFe (1=Uso autorizado; 2=Uso denegado; 3=NFe Cancelada).

Leiaute resumo do evento de NFe

A estrutura XML resEvento_v9.99.xsd apresenta o conjunto de informações resumidas de um evento de NFe, gerado pelo Ambiente Nacional. Contém campos como:

cOrgao: Código do órgão de recepção do evento (91 para Ambiente Nacional).
CNPJ / CPF: CNPJ ou CPF do emitente.
chNFe: Chave de acesso da NFe.
dhEvento: Data e hora do evento.
tpEvento: Código do evento.
nSeqEvento: Número sequencial do evento.
xEvento: Descrição do evento.
dhRecbto: Data de autorização do evento.
nProt: Número de protocolo do evento.

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 de distribuição exemplifica a geração do NSU para emitente e destinatário:

O emitente gera e transmite uma NFe, autorizada pela Sefaz e compartilhada com o Ambiente Nacional.
O Ambiente Nacional gera um NSU para o destinatário do resumo da NFe, disponibilizando-o para consulta.
O destinatário consulta o Web Service NFeDistribuicaoDFe a partir do último NSU recebido e recupera o resumo da NFe.
Com o resumo, o destinatário gera um evento de manifestação.
O Ambiente Nacional gera um NSU do evento para o emitente, disponibilizando-o para consulta.
Se a manifestação do destinatário não for de "desconhecimento da operação", o Ambiente Nacional gera um NSU para o destinatário com a NFe completa, permitindo o download.
O emitente consulta o Web Service e recupera o evento gerado pelo destinatário.
O destinatário consulta o Web Service e recupera a NFe completa.
O emitente gera um evento de sua NFe (ex.: cancelamento), que é compartilhado com o Ambiente Nacional.
O Ambiente Nacional gera um NSU do evento para o destinatário, disponibilizando-o para consulta.
O destinatário consulta o Web Service e recupera o evento gerado pelo emitente.
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.
Emitente e destinatário consultam o Web Service e recuperam o evento gerado pelo fisco.

Este modelo permite ao emitente consultar eventos manifestados pelos destinatários de suas NFes, e ao destinatário acessar eventos gerados pelo emitente. Eventos do fisco são disponibilizados para ambos. A recuperação da NFe é simplificada, pois após a manifestação do destinatário, o Ambiente Nacional gera automaticamente um NSU referenciando a NFe para download.

Recomendações para evitar uso indevido

O Ambiente Nacional implementa controles para identificar e prevenir o uso indevido do Web Service, visando evitar sobrecarga nos recursos. Tentativas sucessivas de busca de registros já disponibilizados ou consultas inadequadas podem levar à rejeição com o erro 656 - Rejeição: Consumo Indevido.

Uso indevido em consultas `distNSU`

Usuário continua consultando mesmo sem documentos a distribuir: Se o retorno indicar cStat=137 (nenhum documento localizado), o usuário deve aguardar uma hora para nova consulta. Consultas realizadas antes desse intervalo resultam em cStat=656 e bloqueio do CNPJ por uma hora.
Usuário não consulta os NSU de forma sequencial: As consultas devem ser baseadas no ultNSU retornado na consulta anterior para manter a sequência ordenada e ascendente. Se o ultNSU for igual ao maxNSU, significa que não há mais documentos a recuperar, e o usuário deve aguardar uma hora para evitar bloqueio.

O campo xMotivo nas mensagens de rejeição fornece descrições detalhadas para ajudar a identificar a causa do uso indevido. Caso diversas aplicações do mesmo ator consultem por NSU para o mesmo CNPJ, elas devem seguir a mesma sequência de numeração para evitar bloqueio. A partir da versão 1.14 da Nota Técnica, o NSU da última consulta realizada para o CNPJ de 14 dígitos é retornado na rejeição 656, auxiliando o usuário a retomar a consulta.

Uso indevido em consultas `consChNFe` e `consNSU`

Essas consultas são projetadas para buscas pontuais, limitadas a documentos dos últimos 90 dias. Para download de múltiplos documentos dentro desse período, a consulta distNSU é a mais indicada.

Quantidade de NFes ou NSUs consultada excede o limite 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.

Se a mensagem 656 for recebida, o usuário deve aguardar uma hora. Se a consulta for retomada antes desse período, o contador de tempo é zerado e reinicia.

Códigos de erros e descrições

A Nota Técnica detalha uma série de códigos de erro e suas respectivas descrições, fornecendo informações sobre o resultado do processamento da solicitação ou os motivos de não atendimento. Exemplos incluem 108 (Serviço Paralisado Momentaneamente), 137 (Nenhum documento localizado), 214 (Tamanho da mensagem excedeu o limite), 472 (CPF consultado difere do CPF do Certificado Digital), e 656 (Consumo Indevido).

Acesso aos Web Services

Os endereços dos Web Services de Distribuição do Ambiente Nacional são publicados nos portais oficiais da NFe. O portal de produção (http://www.nfe.fazenda.gov.br/portal) e o portal de homologação (http://hom.nfe.fazenda.gov.br/portal) oferecem a relação completa de serviços Web no menu 'Serviços'.

Conclusão

O Web Service NFeDistribuicaoDFe, conforme a Nota Técnica 2014.002, estabelece um framework robusto para a distribuição de documentos fiscais eletrônicos e informações resumidas. A compreensão dos tipos de consulta (por NSU, NSU específico e chave de acesso), das regras de geração e disponibilização de NSU, e das diretrizes para evitar o uso indevido é fundamental para o acesso eficiente e contínuo aos documentos fiscais de interesse dos atores da NFe.

Tributos.io

Consulta Dfe

NFeDistribuicaoDFe: Consulta DF-e por NSU e Chave de Acesso (2024)