Serviço NFeDistribuicaoDFe: Consulta DF-e por NSU e Chave | 2024

A Nota Técnica 2014.002 detalha o uso do Web Service NFeDistribuicaoDFe, que disponibiliza informações e Documentos Fiscais eletrônicos (DF-e) de interesse dos atores da Nota Fiscal Eletrônica (NF-e). O serviço visa prover acesso eficiente e confiável aos dados fiscais relevantes para pessoas físicas e jurídicas envolvidas nas operações.

Este documento técnico, atualizado para a Versão 1.20 em maio de 2024, inclui o evento "Ator Interessado". O Web Service NFeDistribuicaoDFe distribui documentos e informações resumidas, funcionando de forma síncrona através do método nfeDistDFeInteresse.

Funcionamento do Web Service NFeDistribuicaoDFe

O serviço NFeDistribuicaoDFe permite que emitentes, destinatários, transportadores e terceiros (informados na tag autXML) consultem DF-e e informações resumidas que não foram gerados por eles, mas são de seu interesse fiscal. Para acessar o serviço, é necessário possuir um certificado digital de Pessoa Jurídica (PJ) ou Pessoa Física (PF) válido.

Para Pessoas Jurídicas, a autenticação ocorre pelo CNPJ base (os oito primeiros dígitos). É possível realizar consultas para qualquer CNPJ completo (14 dígitos) da empresa, desde que o CNPJ base consultado seja o mesmo do certificado digital utilizado. Os documentos e informações ficam disponíveis para distribuição por até 90 dias após sua recepção pelo Ambiente Nacional da NF-e.

Disponibilidade de documentos por ator

A disponibilidade dos documentos fiscais eletrônicos e eventos varia conforme o papel do interessado na operação, seja ele emitente, destinatário, transportador, terceiro ou ator interessado.

A tabela a seguir detalha quais documentos estão disponíveis para cada tipo de ator:

Documentos	Emitente	Destinatário ¹	Transportador ²	Terceiros ³	CNPJ informado em evento 'Ator Interessado'
NF-e	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 NF-e	Não	Sim	Não	Não	Não
Resumo de Eventos CT-e Autorizado/Cancelado	Sim	Sim	Sim	Sim	Sim
Resumo de Eventos MDF-e Autorizado/Cancelado	Sim	Sim	Sim	Sim	Sim
Resumo de Eventos de Registro de Passagem	Sim	Sim	Sim	Sim	Sim
Evento de Comprovante de Entrega Autorizado/Cancelado propagado do CT-e	Sim	Sim	Sim	Sim	Sim
Evento de Comprovante de entrega na NF-e e Cancelamento	Não	Sim	Sim	Sim	Sim

Observações sobre a disponibilidade:

¹ Destinatário: Documentos fiscais e resumos de eventos ficam disponíveis somente após a manifestação do destinatário ("Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação"), com exceção do Evento de Cancelamento. Antes da manifestação, apenas o resumo da NF-e e o cancelamento ficam acessíveis.
² Transportador: A NF-e está disponível se o transportador for identificado no grupo X03 ou no evento "Ator Interessado na NF-e" (código 110150).
³ Terceiros: A NF-e está disponível se o CNPJ ou CPF do terceiro for informado na tag autXML.
A partir da versão 1.13 da Nota Técnica 2014.002, 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.

Leiautes e compactação de mensagens

As mensagens de entrada e retorno do Web Service seguem estruturas XML definidas por Schemas específicos (distDFeInt_v9.99.xsd para entrada e retDistDFeInt _v9.99.xsd para retorno).

Para otimizar o uso da infraestrutura de rede, cada documento contido na mensagem de retorno é compactado individualmente utilizando o padrão Gzip (GNU zip). Essa compactação pode reduzir o tamanho da mensagem em cerca de 60%, sendo necessária a descompactação pelo aplicativo cliente para o tratamento do documento. O retorno do serviço tem um limite de 50 documentos por lote.

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

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

É importante observar que novos usuários ou aqueles que retomam o uso após 60 dias sem consulta terão o NSU gerado a partir do primeiro acesso subsequente, sem retroatividade. O primeiro acesso pode retornar "cStat=137 - Nenhum documento localizado", mas as consultas futuras, após o período de uso indevido (item 3.11.4), podem retornar documentos. A verificação da continuidade do serviço ocorre pelo CPF ou CNPJ base na requisição XML.

Antes de gerar NSU para transportadores e CNPJs informados na tag autXML, é verificado se esses CNPJs também são destinatários na mesma NF-e. Se forem, o NSU só é gerado após a manifestação do destinatário.

Tipos de consulta no serviço NFeDistribuicaoDFe

O XML do pedido de distribuição suporta três tipos de consultas, definidas pela tag informada: distNSU, consNSU e consChNFe.

distNSU - Distribuição de conjunto de DF-e a partir do NSU informado:
O cliente informa o último NSU que possui, e o Ambiente Nacional retorna todos os documentos (NF-e e eventos) disponíveis a partir desse NSU. Se o NSU informado for menor que o primeiro NSU disponível, o serviço fornecerá os documentos mais antigos, desde que as NF-e e seus eventos tenham sido autorizados há menos de 90 dias. A resposta pode ser:
- Rejeição (com código cStat e motivo).
- cStat=137 (Nenhum documento localizado).
- cStat=138 (Documento(s) localizado(s)).
  Após receber cStat=137, é recomendado aguardar uma hora para nova solicitação e evitar o consumo indevido. Se o ultNSU for igual ao maxNSU, não há mais documentos novos no momento.
consNSU - Consulta DF-e vinculado ao NSU informado:
Permite consultar pontualmente um NSU específico que foi identificado como faltante na base de dados do interessado. O serviço retorna um único documento fiscal (NF-e ou evento) referente ao NSU solicitado. Assim como outras consultas, esta está disponível para documentos recebidos nos últimos 90 dias. A resposta pode ser:
- Rejeição (com código cStat e motivo).
- cStat=137 (Nenhum documento localizado).
- cStat=138 (Documento localizado).
consChNFe - Consulta de NF-e por chave de acesso informada:
Permite consultar uma NF-e específica utilizando sua chave de acesso. A chave deve ser válida, existir no Ambiente Nacional e estar vinculada ao interessado como destinatário, transportador ou terceiro. O serviço retorna apenas a NF-e (não retorna eventos) referente à chave informada. A partir da versão 1.15 da Nota Técnica 2014.002, não é mais necessária a prévia geração de NSU para o documento fiscal consultado. Esta consulta também se limita a documentos recebidos nos últimos 90 dias. A resposta pode ser:
- Rejeição (com código cStat e motivo).
- cStat=137 (Nenhum documento localizado).
- cStat=138 (Documento localizado).

Informação do CNPJ ou CPF do interessado

É obrigatório informar o CPF da pessoa física ou o CNPJ da empresa para recuperar DF-e de seu interesse. Para empresas, este campo permite a recuperação de DF-e de qualquer um de seus estabelecimentos utilizando um único certificado digital.

Envio das informações

O pedido de distribuição é enviado via Web Service, exigindo o uso de um certificado digital de PJ ou PF válido. O Web Service do Ambiente Nacional é acionado pelo aplicativo cliente, que deve enviar uma mensagem de acordo com os padrões do manual.

Leiautes resumidos de NF-e e eventos

Para facilitar o compartilhamento de informações importantes de forma segura, o Ambiente Nacional criou leiautes contendo informações resumidas da NF-e (resNFe_v9.99.xsd) e de eventos de NF-e (resEvento_v9.99.xsd).

Leiaute resumo da NF-e

É uma estrutura XML gerada pelo Ambiente Nacional com informações resumidas da NF-e. Este documento é distribuído aos destinatários para possibilitar a manifestação na operação acobertada pela Nota Fiscal Eletrônica. Contém dados como chave de acesso da NF-e, CNPJ/CPF e nome do emitente, 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 situação da NF-e (autorizada, denegada, cancelada).

Leiaute resumo do evento de NF-e

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

Visão geral do modelo de distribuição

O modelo de distribuição de documentos se baseia na geração de um Número Sequencial Único (NSU) para cada CNPJ ou CPF. O processo envolve:

Um emitente gera e transmite uma NF-e, que é autorizada pela Sefaz e compartilhada com o Ambiente Nacional.
O Ambiente Nacional gera um NSU para o destinatário do resumo da NF-e e o disponibiliza para consulta.
O destinatário consulta o Web Service NFeDistribuicaoDFe a partir do último NSU recebido e recupera o resumo da NF-e.
Com o resumo da NF-e, o destinatário gera um evento de manifestação.
O Ambiente Nacional gera um NSU do evento para o emitente e o disponibiliza 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 NF-e completa (liberando 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 NF-e.
O emitente gera um evento de sua NF-e (por exemplo, um evento de cancelamento), que é compartilhado com o Ambiente Nacional.
O Ambiente Nacional gera um NSU para o destinatário do evento gerado pelo emitente e o disponibiliza para consulta.
O destinatário consulta o Web Service e recupera o evento gerado pelo emitente.
Um evento gerado pelo Fisco é recebido pelo Ambiente Nacional, que gera um NSU para o emitente e outro para o destinatário, disponibilizando-os.
Emitente e destinatário consultam o Web Service e recuperam o evento gerado pelo Fisco.

Este modelo permite ao emitente consultar eventos de manifestação dos destinatários e ao destinatário acessar qualquer evento gerado pelo emitente, além dos eventos gerados pelo Fisco para ambos. A recuperação da NF-e pelo destinatário é simplificada, pois após a manifestação, um NSU referente à NF-e é gerado automaticamente, permitindo seu download.

Recomendações para evitar o uso indevido

O Ambiente Nacional mantém controles para identificar situações de "consumo indevido" que sobrecarregam os recursos, como tentativas sucessivas de buscar registros já disponibilizados. Essas tentativas são rejeitadas com o erro 656 - Rejeição: Consumo Indevido.

Uso indevido na consulta com a tag `distNSU`

Ausência de documentos a distribuir e consulta contínua: Se não houver mais documentos a serem retornados (cStat=137), o usuário deve aguardar uma hora para realizar uma nova consulta. Consultas realizadas antes desse período resultarão em uso indevido e bloqueio do CNPJ por uma hora. O campo xMotivo informará: "Rejeicao: Consumo Indevido. Deve ser aguardado 1 hora para efetuar nova solicitacao caso nao existam mais documentos a serem pesquisados. Tente apos 1 hora".
Consulta de NSU fora de sequência: O usuário deve sempre realizar a consulta baseada no ultNSU retornado na consulta anterior. O ultNSU indica o ponto de onde a leitura dos blocos de documentos deve continuar. Se o ultNSU for igual ao maxNSU, não há mais documentos. Nesse caso, deve-se aguardar uma hora. Consultar fora de sequência resultará em bloqueio. O xMotivo informará: "Rejeicao: Consumo Indevido. Deve ser utilizado o ultNSU nas solicitacoes subsequentes. Tente apos 1 hora". Aplicações de um mesmo ator (emitente, destinatário, transportador ou autXML) consultando o mesmo CNPJ (14 dígitos) devem seguir a mesma sequência ordenada e ascendente de NSU para evitar uso indevido. A partir da versão 1.14 da Nota Técnica 2014.002, o número da última consulta é retornado no XML de rejeição 656 para a tag distNSU.

Uso indevido nas consultas com as tags `consChNFe` e `consNSU`

As consultas por chave de acesso e NSU são para buscas pontuais de documentos com no máximo 90 dias de retroatividade. Para download de todas as NF-e de um ator interessado dentro do período de 90 dias, a consulta distNSU deve ser utilizada.

Quantidade de consultas por hora excedida: Existe um limite de consultas por chave de acesso ou NSU em um período de 1 hora (20 consultas). Exceder este limite resulta em cStat=656 e bloqueio do CNPJ por uma hora. O campo xMotivo informará que o limite foi ultrapassado. Em qualquer dos três tipos de consulta, se o usuário receber cStat=656, deve aguardar uma hora. Reiniciar a consulta antes do término da hora reinicia a contagem do bloqueio.

Validações e códigos de erro

O Web Service NFeDistribuicaoDFe executa diversas validações para garantir a integridade e segurança das informações.

Validação do certificado de transmissão

São realizadas verificações como validade do certificado (datas de início e fim), cadeia de certificação (AC emissora cadastrada, certificado de AC não revogado), Lista de Certificados Revogados (LCR) e se o certificado raiz difere da ICP-Brasil. Também é verificada a existência da extensão de CNPJ ou CPF no certificado. Essas validações são críticas para a autenticação e autorização das requisições.

Validação inicial da mensagem no Web Service

Inclui a verificação do tamanho do XML de dados (máximo 10 KB) e o status de funcionamento do servidor de processamento (se paralisado momentaneamente ou sem previsão). Mensagens que excedem o limite de tamanho podem ser descartadas sem retorno de erro se o controle for feito por configurações de rede.

Validação da área de dados

A validação da área de dados ocorre em duas etapas:

Validação de forma: Verifica o Schema XML, o uso de prefixos no namespace, a codificação UTF-8 e se a versão dos dados informada é compatível com a versão vigente.
Validação de regras de negócio: Inclui verificações como a compatibilidade do ambiente da NF-e com o ambiente do Web Service, a validade do CNPJ/CPF do interessado, a correspondência do CNPJ base/CPF do certificado digital com o consultado, se o NSU informado é superior ao maior NSU disponível e a validade da chave de acesso (dígito verificador, código UF, ano, mês, CNPJ, modelo, número da NF). Também verifica se a NF-e está dentro do prazo de 90 dias para download e se o interessado possui permissão para consultá-la.

A Nota Técnica 2014.002 apresenta uma tabela completa de códigos de erros e suas descrições, facilitando a identificação e correção de problemas. Alguns exemplos de códigos são: 108 (Serviço Paralisado Momentaneamente), 137 (Nenhum documento localizado), 138 (Documento localizado), 214 (Tamanho da mensagem excedeu o limite), 472 (CPF consultado difere do CPF do Certificado Digital), 656 (Consumo Indevido).

Exemplos de requisições e retornos XML

A nota técnica oferece exemplos de requisições XML para os três tipos de consulta (distNSU, consNSU, consChNFe), demonstrando a estrutura necessária para enviar os pedidos ao Web Service. Também são fornecidos exemplos de retornos XML, ilustrando situações de sucesso (cStat=138), ausência de documentos (cStat=137) e rejeição por erro (cStat=589), com suas respectivas mensagens de motivo.

Endereços dos Web Services

Os endereços para acessar os Web Services de Distribuição do Ambiente Nacional estão publicados nos portais da NF-e:
* Portal Nacional da NF-e
* Portal de Homologação
Ambos são acessíveis pelo menu "Serviços" / "Relação de Serviços Web".

Conclusão

O Web Service NFeDistribuicaoDFe, detalhado na Nota Técnica 2014.002, é uma ferramenta essencial para a gestão fiscal de empresas e pessoas físicas. Ele permite o acesso eficiente a DF-e e eventos, crucial para a conformidade tributária e a manifestação do destinatário. A adesão às regras de consulta e às recomendações para evitar o consumo indevido garante a continuidade e a eficácia na utilização do serviço, mantendo a conformidade com as exigências fiscais.

Tributos.io

Chave Acesso

Serviço NFeDistribuicaoDFe: Consulta DF-e por NSU e Chave | 2024

CNPJ Alfanumérico 2026: Impacto em DFe, NFe e Sistemas Fiscais