NFeDistribuicaoDFe: Consulta Eficiente de DF-e e NF-e

O projeto Nota Fiscal Eletrônica (NF-e) visa fornecer aos participantes do processo informações relevantes sobre NF-e de maneira eficiente e confiável. Para atender a essa demanda, a Nota Técnica 2014/002 detalha o funcionamento do Web Service NFeDistribuicaoDFe, que disponibiliza documentos fiscais eletrônicos (DF-e) e informações resumidas para emitentes, destinatários, transportadores e terceiros envolvidos. Este serviço substituiu o NfeConsultaDest, aprimorando a capacidade de acesso a dados fiscais.

O Web Service NFeDistribuicaoDFe

O Web Service NFeDistribuicaoDFe é um serviço síncrono, acessível pelo método nfeDistDFeInteresse, projetado para distribuir informações resumidas e DF-e para qualquer ator da NF-e, seja pessoa física ou jurídica. Para utilizá-lo, é necessário um certificado digital válido de pessoa jurídica ou física. No caso de pessoas jurídicas, a autenticação ocorre pelo CNPJ base, permitindo consultas para qualquer CNPJ da empresa, desde que o CNPJ base consultado seja o mesmo do certificado digital.

Este serviço armazena documentos e informações resumidas por até três meses após a recepção pelo Ambiente Nacional da NF-e. A distribuição abrange os seguintes papéis e documentos:

Emitente: Recebe Eventos de Manifestação do Destinatário, Eventos da Suframa, Eventos do Fisco em Resposta ao Pedido de Prorrogação, Resumo de Eventos CT-e Autorizado/Cancelado, Resumo de Eventos MDF-e Autorizado/Cancelado, e Resumo de Eventos de Registro de Passagem.
Destinatário: Acesso à NF-e (após manifestação, exceto para cancelamento), Evento de Cancelamento, Evento de Carta de Correção, Eventos da Suframa, EPEC, Eventos de Pedido de Prorrogação de Prazo, Eventos do Fisco em Resposta ao Pedido de Prorrogação, Resumo de NF-e, Resumo de Eventos CT-e Autorizado/Cancelado, Resumo de Eventos MDF-e Autorizado/Cancelado e Resumo de Eventos de Registro de Passagem.
Transportador: Recebe NF-e (se identificado no grupo do Transportador - tag transporta, id X03), Evento de Cancelamento, Evento de Carta de Correção, EPEC, Resumo de Eventos CT-e Autorizado/Cancelado, Resumo de Eventos MDF-e Autorizado/Cancelado e Resumo de Eventos de Registro de Passagem.
Terceiros: Acesso à NF-e (se o CNPJ ou CPF estiver na tag autXML, id GA01), Evento de Cancelamento, Evento de Carta de Correção, Eventos de Manifestação do Destinatário, Eventos da Suframa, Resumo de Eventos CT-e Autorizado/Cancelado, Resumo de Eventos MDF-e Autorizado/Cancelado e Resumo de Eventos de Registro de Passagem.

Para o destinatário, os documentos fiscais e resumos de eventos ficam disponíveis apenas se houver 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 recebe somente a estrutura XML de Resumo de NF-e e o cancelamento de NF-e. A NF-e integral só é acessível ao transportador se ele for explicitamente identificado no grupo X03, e a terceiros se seu CNPJ ou CPF constar na tag autXML.

Estruturas de Mensagens

A comunicação com o Web Service NFeDistribuicaoDFe é realizada através de mensagens XML, seguindo leiautes específicos para entrada e retorno.

Mensagem de entrada

O leiaute da mensagem de entrada, conforme o Schema XML distDFeInt_v9.99.xsd, permite ao ator interessado solicitar a distribuição de DF-e. Os principais campos incluem:

distDFeInt (TAG raiz): Abertura do pedido de distribuição.
versao: Versão do leiaute.
tpAmb: Identifica o ambiente: 1 para Produção, 2 para Homologação.
cUFAutor: Código da UF do autor da solicitação (opcional).
CNPJ ou CPF: Identificação do interessado no DF-e. Apenas um deve ser informado.

A requisição de distribuição pode ocorrer de três maneiras, definidas pela tag presente no XML:

distNSU - Distribuição de conjunto de DF-e a partir do NSU informado:
- ultNSU: Último Número Sequencial Único (NSU) recebido pelo ator. Se informado como zero ou um NSU muito antigo, a consulta retorna informações resumidas e DF-e recebidos pelo Ambiente Nacional nos últimos três meses.
consNSU - Consulta DF-e vinculado ao NSU informado:
- NSU: Número sequencial único específico. Usado para consultar um NSU faltante na base de dados do interessado, fechando lacunas.
consChNFe - Consulta de NF-e por chave de acesso informada:
- chNFe: Chave de acesso específica de 44 dígitos da NF-e.

Mensagem de retorno

O leiaute da mensagem de retorno, seguindo o Schema XML retDistDFeInt_v9.99.xsd, apresenta os documentos de interesse do ator, com um máximo de 50 documentos por retorno. Os campos relevantes são:

retDistDFeInt (TAG raiz): Contém a resposta da solicitação.
versao: Versão do leiaute de retorno.
tpAmb: Ambiente (Produção/Homologação).
verAplic: Versão do aplicativo que processou a consulta.
cStat: Código do status da resposta, indicando o resultado do processamento.
xMotivo: Descrição literal do status.
dhResp: Data e hora da resposta, no formato UTC.
ultNSU: Último NSU pesquisado no Ambiente Nacional. Permite continuar a consulta a partir deste ponto.
maxNSU: Maior NSU existente no Ambiente Nacional para o CNPJ/CPF consultado.
loteDistDFeInt: Grupo que contém o conjunto de informações resumidas e DF-e.
docZip: Informação resumida ou DF-e compactado no padrão Gzip (Base64Binary).
- NSU (atributo de docZip): NSU do documento fiscal.
- schema (atributo de docZip): Identificação do Schema XML para validação do XML contido no campo.

Mensagem de retorno compactada

Para otimizar a infraestrutura de rede, os documentos contidos na mensagem de retorno são compactados individualmente no padrão Gzip (GNU zip), na tag docZip. Esta compactação pode reduzir o tamanho da mensagem em aproximadamente 60%, facilitando a transmissão e recepção dos dados. A aplicação cliente deve descompactar cada documento e processá-lo normalmente.

Processo de Distribuição de DF-e

Este serviço pode ser consumido por atores que atuam como emitente, destinatário, transportador ou terceiro na NF-e, seja pessoa física ou jurídica, utilizando certificado digital. O Ambiente Nacional atribui um Número Sequencial Único (NSU) para cada interessado nos documentos fiscais, garantindo uma sequência numérica sem lacunas na base de dados do interessado.

Tipos de pedidos de distribuição

O XML do pedido de distribuição suporta três tipos de consultas, cada uma com sua finalidade:

Distribuição de conjunto de DF-e a partir do NSU informado (`distNSU`)

A aplicação cliente deve informar o ultNSU, que representa o último número sequencial único que ela possui. Se o ultNSU informado for menor que o primeiro NSU disponível para distribuição, o Ambiente Nacional fornecerá os documentos a partir do primeiro registro disponível. O Web Service gera lotes com até 50 documentos, incluindo informações resumidas ou DF-e, com NSU superior ao informado. Os lotes são ordenados crescentemente pelo NSU e podem conter diversos tipos de documentos.

É relevante notar que documentos emitidos pela própria empresa não são disponibilizados para consulta neste processo. A geração do NSU ocorre na ordem cronológica de recepção pelo Ambiente Nacional, não pela ordem de emissão ou autorização de uso.

As respostas possíveis para este tipo de requisição são:

Rejeição: Mensagem com o motivo da falha (cStat).
Nenhum documento localizado (cStat='137'): Não há documentos fiscais para o CNPJ/CPF informado.
Documento(s) localizado(s) (cStat='138'): Devolve os documentos fiscais encontrados.

Para evitar sobrecarga, caso o ultNSU informado seja igual ao maxNSU do Ambiente Nacional, indicando que não há mais documentos a serem pesquisados no momento, a empresa deve aguardar no mínimo uma hora antes de fazer uma nova solicitação de distribuição.

Consulta DF-e vinculado ao NSU informado (`consNSU`)

Este processo é utilizado quando o interessado identifica uma lacuna na sequência de NSUs em sua base de dados, sugerindo uma falha na distribuição. A aplicação cliente informa o NSU específico que está faltando. O Web Service NFeDistribuicaoDFe tentará retornar o documento correspondente ou informará que o NSU não existe.

As respostas possíveis são:

Rejeição: Mensagem com o motivo da falha (cStat).
Nenhum documento localizado (cStat='137'): O Ambiente Nacional não gerou o NSU, e o interessado deve desconsiderá-lo.
Documento localizado (cStat='138'): Devolve o documento fiscal encontrado.

Consulta de NF-e por chave de acesso informada (`consChNFe`)

Permite a consulta pontual de uma NF-e específica pela sua chave de acesso. A chave de acesso deve ser válida, existir no Ambiente Nacional e estar vinculada ao interessado como destinatário, transportador ou terceiro.

Detalhes da consulta por chave de acesso:

Para o destinatário: Se houver manifestação ("Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação"), a NF-e completa será retornada. Caso contrário, apenas o resumo da NF-e é enviado, contendo informações essenciais para a manifestação.
Para transportador e terceiros: A NF-e é disponibilizada integralmente.
Para o emitente: A NF-e não é disponibilizada nesta consulta.

Esta consulta está disponível apenas para documentos recebidos pelo Ambiente Nacional nos últimos 90 dias. Após esse período, a recuperação da NF-e não será possível.

As respostas possíveis são:

Rejeição: Mensagem com o motivo da falha (cStat).
Nenhum documento localizado (cStat='137'): O Ambiente Nacional não possui a NF-e consultada.
Documento localizado (cStat='138'): Devolve o documento fiscal encontrado.

CNPJ ou CPF do interessado no DF-e e envio das informações

É necessário informar o CPF da pessoa física ou o CNPJ da empresa para recuperar os DF-e de interesse. Este mecanismo permite que uma empresa consulte os DF-e de qualquer um de seus estabelecimentos usando um único certificado digital de Pessoa Jurídica.

O pedido de distribuição é enviado via Web Service, exigindo um certificado digital de Pessoa Jurídica ou Pessoa Física válido para autenticação. A aplicação cliente deve enviar uma mensagem conforme os padrões definidos na Nota Técnica.

Validações no Web Service

Para garantir a segurança e a integridade das operações, o Web Service NFeDistribuicaoDFe realiza diversas validações.

Validação do certificado de transmissão

O certificado digital utilizado para a transmissão da requisição é rigorosamente validado. As regras de validação incluem:

Validade do certificado: Verifica se o certificado não está vencido.
Cadeia de certificação: Garante que a cadeia de certificação (AC emissora) seja válida e cadastrada no Ambiente Nacional.
Lista de Certificados Revogados (LCR): Verifica a revogação do certificado.
Certificado raiz: Confirma que o certificado raiz pertence à ICP-Brasil.
Extensões OID: Exige a presença das extensões de CNPJ (OID=2.16.76.1.3.3) ou CPF (OID=2.16.76.1.3.1) no certificado, conforme o tipo de interessado.

A maioria dessas validações é processada pelo protocolo SSL, enquanto algumas podem falhar se houver certificados de Autoridade Certificadora Raiz diferentes da ICP-Brasil no repositório do servidor.

Validação inicial da mensagem no Web Service

Antes do processamento detalhado, a mensagem passa por uma validação inicial:

Tamanho do XML de dados: O XML não pode exceder 10 KB. Mensagens maiores podem ser descartadas ou gerar o erro "Rejeição: Tamanho da mensagem excedeu o limite estabelecido" (cStat=214).
Disponibilidade do servidor: O serviço verifica se o servidor de processamento não está paralisado momentaneamente (cStat=108) ou sem previsão (cStat=109).

Validação da área de dados

A área de dados da mensagem XML é validada quanto à sua forma e regras de negócio.

Validação de forma da área de dados

Schema XML: Verifica a conformidade com o Schema XML da área de dados (cStat=215).
Uso de prefixo no namespace: Não permite prefixos de namespace (cStat=404).
Codificação XML: Exige codificação UTF-8 (cStat=402).
Versão dos dados: Verifica se a versão informada é compatível (cStat=238 ou cStat=239).

Validação de regras de negócio

Ambiente: O tipo de ambiente da NF-e deve ser o mesmo do Web Service (cStat=252).
CNPJ/CPF do interessado: Valida se o CNPJ (cStat=489) ou CPF (cStat=490) do interessado é válido (dígito verificador ou zeros).
Certificado Digital: O CNPJ base ou CPF do certificado digital deve corresponder ao CNPJ ou CPF consultado (cStat=593 ou cStat=472).
NSU informado: Para consultas distNSU e consNSU, o NSU informado não pode ser superior ao maior NSU disponível (cStat=589).
Chave de Acesso: Para consultas consChNFe, valida o dígito verificador (cStat=236), código UF (cStat=614), ano (cStat=615), mês (cStat=616), CNPJ (cStat=617), modelo (deve ser 55, cStat=618), e número NF (cStat=619).
Existência da NF-e: A NF-e deve existir para a chave de acesso informada (cStat=217).
Prazo de download: A NF-e deve estar no prazo de 90 dias da data de recebimento no Ambiente Nacional para download (cStat=632).
Permissão de consulta: O CNPJ/CPF do interessado deve ter permissão para consultar a NF-e (cStat=640).
Consulta pelo emitente: A NF-e não é disponibilizada para o próprio emitente (cStat=641).
NF-e cancelada/denegada: Arquivo indisponível para download em caso de NF-e cancelada (cStat=653) ou denegada (cStat=654).

Leiautes Resumidos

Para compartilhar informações relevantes mantendo o sigilo, foram desenvolvidos leiautes resumidos da NF-e e de eventos.

Leiaute Resumo da NF-e (`resNFe_v9.99.xsd`)

Esta estrutura XML contém informações resumidas da NF-e, geradas pelo Ambiente Nacional quando a NF-e é autorizada ou denegada. É distribuída aos destinatários para possibilitar sua manifestação na operação. Campos importantes incluem:

chNFe: Chave de acesso da NF-e.
CNPJ / CPF: Identificação do emitente.
xNome: Razão Social ou Nome do Emitente.
IE: Inscrição Estadual do Emitente.
dhEmi: Data de Emissão da NF-e (UTC).
tpNF: Tipo de Operação (0=Entrada; 1=Saída).
vNF: Valor Total da NF-e.
digVal: Digest Value da NF-e.
dhRecbto: Data de autorização da NF-e (UTC).
nProt: Número de protocolo da NF-e.
cSitNFe: Situação da NF-e (1=Uso autorizado; 2=Uso denegado; 3=NF-e Cancelada).

Leiaute Resumo do Evento de NF-e (`resEvento_v9.99.xsd`)

Esta estrutura XML apresenta informações resumidas de um evento de NF-e, gerada pelo Ambiente Nacional. Campos essenciais são:

cOrgao: Código do órgão de recepção do evento (91 para Ambiente Nacional).
CNPJ / CPF: Identificação do emitente.
chNFe: Chave de acesso da NF-e vinculada ao evento.
dhEvento: Data e hora do evento (UTC).
tpEvento: Código do evento.
nSeqEvento: Número sequencial do evento.
xEvento: Descrição do evento.
dhRecbto: Data de autorização do evento (UTC).
nProt: 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 NSU para cada CNPJ ou CPF, garantindo que os documentos sejam disponibilizados de forma ordenada. O fluxo de NSU ocorre da seguinte forma:

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 referente ao resumo da NF-e, tornando-o disponível para consulta.
O destinatário consulta o Web Service NFeDistribuicaoDFe utilizando o último NSU recebido e recupera o resumo da NF-e.
Com o resumo, o destinatário pode gerar um evento de NF-e, como um evento de manifestação.
O Ambiente Nacional gera um NSU do evento para o emitente, disponibilizando-o para consulta.
Se o evento de manifestação do destinatário não for "desconhecimento da operação", o Ambiente Nacional gera um NSU para o destinatário, liberando o download da NF-e completa.
O emitente consulta o Web Service NFeDistribuicaoDFe com seu último NSU e recupera o evento gerado pelo destinatário.
O destinatário também consulta o Web Service NFeDistribuicaoDFe e recupera a NF-e.
Se o emitente gerar um evento de sua NF-e, como um cancelamento, este é compartilhado pela Sefaz com o Ambiente Nacional.
O Ambiente Nacional gera um NSU para o destinatário referente ao evento gerado pelo emitente.
O destinatário consulta o Web Service NFeDistribuicaoDFe e recupera o evento gerado pelo emitente.
Quando o fisco gera um evento, o Ambiente Nacional gera um NSU para o emitente e outro para o destinatário, disponibilizando-os para consulta.
Ambos, emitente e destinatário, podem consultar o Web Service NFeDistribuicaoDFe para recuperar o evento gerado pelo fisco.

Este modelo permite ao emitente consultar eventos manifestados pelos destinatários e disponibiliza ao destinatário qualquer evento gerado pelo emitente, além de eventos do fisco. A manifestação do destinatário simplifica o processo de download da NF-e, pois o Ambiente Nacional gera automaticamente um NSU referenciando a NF-e e permitindo sua recuperação.

Recomendações para evitar uso indevido

Para manter a estabilidade do sistema, o Ambiente Nacional monitora e aplica controles contra o uso indevido do Web Service. Aplicações que realizam tentativas excessivas e sucessivas de busca por registros já disponibilizados, como em "loops" indevidos, consomem recursos e podem sobrecarregar o canal de comunicação.

Tentativas identificadas como uso indevido serão rejeitadas com a mensagem de erro "Rejeição: Consumo Indevido" (cStat=656). Recomenda-se que as aplicações clientes implementem lógicas de controle e tempo de espera entre as requisições para evitar essa rejeição.

Endereço do Web Service

Os endereços para o Web Service de Distribuição no Ambiente Nacional estão disponíveis no Portal da NF-e (http://www.nfe.fazenda.gov.br/portal) no link "Serviços" / "Relação de Serviços Web". Para o ambiente de homologação, o endereço é encontrado no Portal de Homologação (http://hom.nfe.fazenda.gov.br/portal).

Códigos de erros e descrições de mensagens de erros

O Web Service NFeDistribuicaoDFe utiliza códigos de status (cStat) para comunicar o resultado do processamento das solicitações e os motivos de não atendimento. Conhecer esses códigos é fundamental para o desenvolvimento e a manutenção de aplicações que interagem com o serviço.

Código	Resultado do Processamento da Solicitação
108	Serviço Paralisado Momentaneamente (curto prazo)
109	Serviço Paralisado sem Previsão
137	Nenhum documento localizado
138	Documento localizado

Código	Motivos de Não Atendimento da Solicitação
214	Rejeição: Tamanho da mensagem excedeu o limite estabelecido
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: Cabeçalho - Versão do arquivo XML superior a Versão vigente
239	Rejeição: Cabeçalho - Versão do arquivo XML não suportada
252	Rejeição: Ambiente informado diverge do Ambiente de recebimento
280	Rejeição: Certificado Transmissor inválido
281	Rejeição: Certificado Transmissor Data Validade
283	Rejeição: Certificado Transmissor - erro Cadeia de Certificação
284	Rejeição: Certificado Transmissor revogado
285	Rejeição: Certificado Transmissor difere ICP-Brasil
286	Rejeição: Certificado Transmissor erro no acesso a 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	Rejeição: CNPJ informado inválido (DV ou zeros)
490	Rejeição: CPF informado inválido (DV ou zeros)
589	Rejeição: Número do NSU informado superior ao maior NSU do Ambiente Nacional
593	Rejeição: CNPJ-Base consultado difere do CNPJ-Base do Certificado Digital
614	Rejeição: Chave de Acesso inválida (Código UF inválido)
615	Rejeição: Chave de Acesso inválida (Ano menor que 06 ou Ano maior que Ano corrente)
616	Rejeição: Chave de Acesso inválida (Mês menor que 1 ou Mês maior que 12)
617	Rejeição: Chave de Acesso inválida (CNPJ zerado ou dígito inválido)
618	Rejeição: Chave de Acesso inválida (modelo diferente de 55)
619	Rejeição: Chave de Acesso inválida (número NF = 0)
632	Rejeição: Solicitação fora de prazo, a NF-e não está mais disponível para download
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	Rejeição: NF-e Cancelada, arquivo indisponível para download
654	Rejeição: NF-e Denegada, arquivo indisponível para download
656	Rejeição: Consumo Indevido

A Nota Técnica recomenda evitar caracteres especiais ou acentuação nos textos das mensagens de erro.

Conclusão

O Web Service NFeDistribuicaoDFe, conforme detalhado na Nota Técnica 2014/002, oferece um canal padronizado para a consulta e distribuição de documentos fiscais eletrônicos e informações resumidas. Ele otimiza o acesso a dados fiscais para todos os atores envolvidos na NF-e, desde emitentes e destinatários até transportadores e terceiros, mediante o uso de certificados digitais e um controle sequencial via NSU. A compreensão dos leiautes, processos de consulta e regras de validação é essencial para desenvolver sistemas que interagem de forma eficiente e em conformidade com as diretrizes do Ambiente Nacional. A correta utilização do serviço contribui para a integridade dos dados e a fluidez das operações fiscais eletrônicas.

Tributos.io

Nfedistribuicaodfe

NFeDistribuicaoDFe: Consulta Eficiente de DF-e e NF-e