NFeDistribuicaoDFe: Consulta NF-e e DF-e para Atores Fiscais

O projeto Nota Fiscal Eletrônica (NF-e) enfrenta o desafio de fornecer informações eficientes e confiáveis aos envolvidos. Para atender a essa demanda, a Secretaria da Fazenda lançou o Web Service NFeDistribuicaoDFe. Este serviço centraliza e distribui documentos fiscais eletrônicos (DF-e) e resumos de informações relevantes para emitentes, destinatários, transportadores e terceiros, como detalhado na Nota Técnica 2014/002.

A implementação do NFeDistribuicaoDFe representa uma evolução, substituindo o Web Service NfeConsultaDest. A transição foi planejada com prazos específicos: o ambiente de homologação esteve disponível a partir de 15/09/2014, o ambiente de produção a partir de 06/10/2014, e o NfeConsultaDest foi desativado em 31/05/2017.

Função do Web Service NFeDistribuicaoDFe

A principal função do NFeDistribuicaoDFe é distribuir informações resumidas e documentos fiscais eletrônicos que interessam a um determinado ator, seja pessoa física ou jurídica. Este serviço opera de forma síncrona, utilizando o método nfeDistDFeInteresse.

Qualquer ator de NF-e, seja Pessoa Jurídica ou Pessoa Física, pode consumir este serviço, desde que possua um certificado digital válido (PJ ou PF). Para Pessoas Jurídicas, a autenticação ocorre pelo CNPJ base, permitindo a consulta com qualquer CNPJ da empresa, desde que o CNPJ base consultado seja o mesmo do certificado digital.

Os DF-e e as informações resumidas ficam disponíveis para distribuição por até três meses após a recepção pelo Ambiente Nacional da NF-e. A distribuição é direcionada aos atores que desempenham papéis específicos: emitente (grupo emit), destinatário (grupo dest), transportador (grupo transporta) e terceiros autorizados a acessar o XML (grupo autXML).

Documentos e eventos disponíveis para cada ator

A tabela a seguir detalha quais documentos e eventos estão acessíveis para cada papel, observando condições específicas:

NF-e: Disponível para destinatário, transportador e terceiros. Para o destinatário, a NF-e completa é liberada após manifestação ("Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação"), exceto o cancelamento, que é disponibilizado independentemente. Para o transportador, a NF-e é acessível se o CNPJ/CPF estiver no grupo transporta. Para terceiros, se o CNPJ/CPF estiver na tag autXML.
Evento de Cancelamento: Destinatário, transportador e terceiros.
Evento de Carta de Correção: Destinatário, transportador e terceiros.
Eventos de Manifestação do Destinatário: Emitente e terceiros.
Eventos da Suframa (Vistoria/Internalização): Emitente, destinatário e terceiros.
EPEC: Destinatário e transportador.
Eventos de Pedido de Prorrogação de Prazo (NT 2015.001): Destinatário. Inclui Evento Pedido de Prorrogação (EPP1, EPP2) e Evento Cancelamento Pedido de Prorrogação (ECPP1, ECPP2).
Eventos do Fisco em Resposta ao Pedido de Prorrogação (NT 2015.001): Emitente e destinatário. Inclui Evento Fisco Resposta ao Pedido de Prorrogação (EFPP1, EFPP2) e Evento Fisco Resposta ao Cancelamento de Prorrogação (EFCPP1, EFCPP2).
Evento de Averbação (BT 2017/001): Emitente, destinatário, transportador e terceiros.
Resumo de NF-e: Destinatário. Antes da manifestação, o destinatário acessa apenas a estrutura XML de resumo da NF-e e o cancelamento da NF-e.
Resumo de Eventos CTe Autorizado/Cancelado: Emitente, destinatário, transportador e terceiros.
Resumo de Eventos MDFe Autorizado/Cancelado: Emitente, destinatário, transportador e terceiros.
Resumo de Eventos de Registro de Passagem (NT 2014/002 v1.02): Emitente, destinatário, transportador e terceiros.

Estrutura das Mensagens NFeDistribuicaoDFe

O serviço de distribuição opera com um leiaute XML específico para mensagens de entrada e retorno.

Leiaute da Mensagem de Entrada (distDFeInt)

A mensagem de entrada é uma estrutura XML que encapsula o pedido de distribuição de DF-e. O schema XML utilizado é o distDFeInt_v9.99.xsd. Os principais campos incluem:

Raiz (distDFeInt): Tag principal da estrutura.
Versão (versao): Versão do leiaute.
Tipo de Ambiente (tpAmb): Indica se é produção (1) ou homologação (2).
Código da UF do Autor (cUFAutor): Código da Unidade Federativa do solicitante.
CNPJ do Interessado (CNPJ): CNPJ da empresa que busca o DF-e.
CPF do Interessado (CPF): CPF da pessoa que busca o DF-e.
Grupo para Distribuir DF-e por Interesse (distNSU): Permite a distribuição de um conjunto de DF-e.
- Último NSU Recebido (ultNSU): O último Número Sequencial Único que o ator já possui. Se informado como zero ou muito antigo, a consulta retorna resumos e DF-e dos últimos 3 meses.
Grupo para Consultar DF-e por NSU Específico (consNSU): Usado para consultar um DF-e pontual.
- Número Sequencial Único (NSU): O NSU específico a ser consultado.

Leiaute da Mensagem de Retorno (retDistDFeInt)

A mensagem de retorno é uma estrutura XML que contém os documentos de interesse do ator, com um limite máximo de 50 documentos por lote. O schema XML é retDistDFeInt_v9.99.xsd. Os campos incluem:

Raiz (retDistDFeInt): Tag principal da resposta.
Versão (versao): Versão do leiaute.
Tipo de Ambiente (tpAmb): Produção ou homologação.
Versão do Aplicativo (verAplic): Indica a versão do aplicativo que processou a consulta.
Código de Status (cStat): Código do status da resposta.
Descrição do Status (xMotivo): Descrição literal do status da resposta.
Data e Hora da Resposta (dhResp): Data e hora da mensagem de resposta.
Último NSU Pesquisado (ultNSU): O último NSU pesquisado no Ambiente Nacional. Permite ao solicitante continuar a consulta.
Maior NSU Existente (maxNSU): O maior NSU disponível no Ambiente Nacional para o CNPJ/CPF informado.
Conjunto de Informações (loteDistDFeInt): Lote de informações resumidas e documentos fiscais.
Documento Compactado (docZip): Informação resumida ou DF-e compactado no padrão Gzip.
- NSU do Documento Fiscal (NSU): Número Sequencial Único do documento fiscal.
- Identificação do Schema (schema): Nome do schema XML para validar o documento (ex: resNFe_v1.00.xsd).

Mensagem de Retorno Compactada

Para otimizar a infraestrutura de rede, cada documento na mensagem de retorno é compactado individualmente no padrão Gzip. Esta compactação pode reduzir o tamanho da mensagem em aproximadamente 60%. A aplicação cliente deve descompactar o conteúdo da tag docZip para processar o documento.

Processo de Distribuição de DF-e

O Web Service NFeDistribuicaoDFe permite a recuperação de DF-e e informações de interesse, gerando um Número Sequencial Único (NSU) para cada documento relacionado a um CNPJ ou CPF específico.

Geração do Pedido de Distribuição

O XML do pedido de distribuição suporta dois tipos de consultas, definidas pelas tags distNSU e consNSU:

distNSU - Distribuição de Conjunto de DF-e a Partir do NSU Informado: A aplicação cliente deve fornecer o ultNSU que já possui. O Ambiente Nacional retorna os documentos com NSU superior ao informado. Se o ultNSU for menor que o primeiro NSU disponível, a consulta inicia do primeiro disponível, limitado aos documentos dos últimos três meses.
consNSU - Distribuição de DF-e Vinculado ao NSU Informado: Permite consultar um NSU específico que esteja faltando na base de dados do interessado. A aplicação cliente informa o NSU desejado.

CNPJ ou CPF do Interessado

É necessário informar o CPF da pessoa ou CNPJ da empresa para recuperar os DF-e. Uma empresa pode usar um único certificado digital de PJ para consultar os DF-e de qualquer um de seus estabelecimentos, desde que o CNPJ base seja o mesmo do certificado.

Envio das Informações

O pedido de distribuição é enviado por Web Service, exigindo um certificado digital de Pessoa Jurídica ou Pessoa Física válido. O Ambiente Nacional processa a mensagem que deve seguir os padrões estabelecidos na nota técnica.

Processamento da Requisição (distNSU)

O Web Service gera lotes de até 50 documentos, incluindo informações resumidas ou DF-e, com NSU superior ao informado. Se o NSU for menor que o primeiro disponível, a consulta começa do primeiro.

As regras de criação de lote são:
* Ordem crescente de NSU.
* O lote pode conter qualquer tipo de documento válido e seu NSU.
* Quantidade máxima: 50 documentos por lote.

Documentos emitidos pela própria empresa não são disponibilizados para consulta. O Ambiente Nacional gera o NSU por ordem cronológica de recepção dos documentos. A sincronização não é em tempo real com todos os documentos autorizados, mas garante que todos os documentos de interesse sejam recuperados assim que recebidos.

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

É recomendado aguardar um mínimo de uma hora para uma nova solicitação se não houver mais documentos a serem pesquisados (quando ultNSU for igual ao maxNSU do Ambiente Nacional).

Processamento da Requisição (consNSU)

Considerando que o Ambiente Nacional gera NSUs sem lacunas, a identificação de falhas na sequência numérica na base do interessado pode ser corrigida com consultas pontuais. Para isso, o interessado deve usar o método nfeDistDFeInteresse com a tag consNSU informando o NSU faltante.

As respostas podem ser:
* Rejeição: Mensagem com o motivo da falha (cStat).
* Nenhum documento localizado: O Ambiente Nacional não gerou o NSU; deve ser desconsiderado (cStat='137-Nenhum documento localizado').
* Documento localizado: Retorno do documento fiscal encontrado (cStat='138-Documento localizado').

Regras de Validação

O processo de distribuição de DF-e inclui diversas validações para garantir a segurança e a integridade das operações.

Validação do Certificado de Transmissão

O certificado digital utilizado na transmissão da solicitação passa por verificações rigorosas:

A01 - Certificado de Transmissor Inválido: Verifica se o certificado existe, se a versão é "3", se o Basic Constraint é verdadeiro (não pode ser Certificado de AC) e se o KeyUsage define "Autenticação Cliente". Crítica obrigatória, resulta em rejeição (código 280).
A02 - Validade do Certificado: Verifica a data de início e fim da validade. Crítica obrigatória, rejeição (código 281).
A03 - Verificação da Cadeia de Certificação: Confere se o certificado da AC emissora está cadastrado, se não está revogado e se o certificado foi assinado pela AC emissora. Crítica obrigatória, rejeição (código 283).
A04 - LCR do Certificado de Transmissor: Verifica a existência e disponibilidade da Lista de Certificados Revogados (LCR). Crítica obrigatória, rejeição (código 286).
A05 - Certificado do Transmissor revogado: Confirma se o certificado não está revogado. Crítica obrigatória, rejeição (código 284).
A06 - Certificado Raiz difere da "ICP-Brasil": Verifica se o certificado raiz pertence à cadeia ICP-Brasil. Crítica obrigatória, rejeição (código 285).
A07 - Falta a extensão de CNPJ ou CPF: Verifica a presença da extensão de CNPJ (OID=2.16.76.1.3.3) ou CPF (OID=2.16.76.1.3.1). Crítica obrigatória, rejeição (código 473).

As validações A01 a A05 são realizadas pelo protocolo SSL. A validação A06 também pode ser feita via SSL, mas pode falhar se houver outros certificados de Autoridade Certificadora Raiz diferentes de 'ICP-Brasil' no servidor do Web Service.

Validação Inicial da Mensagem no Web Service

A mensagem também é validada em sua estrutura inicial:

B01 - Tamanho do XML de Dados superior a 10 KB: Mensagens que excedem 10 KB são descartadas. Se o controle for por aplicativo, o erro 214 pode ser retornado.
B02 - Verifica se o Servidor de Processamento está Paralisado Momentaneamente: Rejeição (código 108).
B03 - Verifica se o Servidor de Processamento está Paralisado sem Previsão: Rejeição (código 109).

Validação da Área de Dados

A área de dados do XML também passa por validações de forma e regras de negócio.

Validação de forma da área de dados:

D01 - Verifica Schema XML da área de dados: Rejeição (código 215).
D02 - Verifica o uso de prefixo no namespace: Rejeição (código 404).
D03 - XML utiliza codificação diferente de UTF-8: Rejeição (código 402).
D04 - Versão dos Dados informada superior à versão vigente: Rejeição (código 238).
D05 - Versão dos Dados não suportada: Rejeição (código 239).

Validação de regras de negócio:

H01 - Tipo do ambiente da NF-e difere do ambiente do Web Service: Rejeição (código 252).
H02 - CNPJ do interessado na distribuição inválido (DV ou zeros): Rejeição (código 489).
H03 - CPF do interessado na distribuição inválido (DV ou zeros): Rejeição (código 490).
H04 - CNPJ base do Certificado Digital utilizado na transmissão não é o mesmo do CNPJ consultado: Rejeição (código 593).
H05 - CPF do Certificado Digital utilizado na transmissão diferente do CPF consultado: Rejeição (código 472).
H06 - Número do NSU informado superior ao maior NSU disponível para consulta: Rejeição (código 589).

Leiautes Resumidos

Para permitir o compartilhamento de informações relevantes sem expor todos os detalhes do documento original, foram criados leiautes resumidos para NF-e e eventos.

Leiaute Resumo da NF-e (resNFe)

Esta estrutura XML é gerada pelo Ambiente Nacional com informações essenciais da NF-e. É distribuída aos destinatários para possibilitar a manifestação na operação. Os campos incluem:

Raiz (resNFe): Conjunto de informações resumidas da NF-e.
Versão (versao): Versão do leiaute.
Chave de Acesso da NF-e (chNFe): Identificador único da NF-e.
CNPJ do Emitente (CNPJ): CNPJ de quem emitiu a NF-e.
CPF do Emitente (CPF): CPF de quem emitiu a NF-e.
Razão Social ou Nome do Emitente (xNome): Nome do emitente.
Inscrição Estadual (IE): Inscrição Estadual do emitente (pode ser vazio, ISENTO ou a IE).
Data de Emissão (dhEmi): Data e hora de emissão da NF-e no formato UTC.
Tipo de Operação (tpNF): Entrada (0) ou Saída (1).
Valor Total da NF-e (vNF): Valor total da nota fiscal.
Digest Value da NF-e (digVal): Valor de hash para verificação da integridade.
Data de Recebimento da Autorização (dhRecbto): Data de recebimento da autorização da NF-e pelo Ambiente Nacional.
Número de Protocolo da NF-e (nProt): Protocolo de autorização.
Situação da NF-e (cSitNFe): Uso autorizado (1) ou uso denegado (2).

Leiaute Resumo do Evento de NF-e (resEvento)

Este leiaute XML contém informações resumidas de um evento de NF-e, gerado pelo Ambiente Nacional. Os campos principais são:

Raiz (resEvento): Tag raiz do resumo do evento.
Versão (versao): Versão do leiaute.
Código do Órgão (cOrgao): Código do órgão que recebeu o evento (91 para Ambiente Nacional).
CNPJ do Emitente (CNPJ): CNPJ do emitente do evento.
CPF do Emitente (CPF): CPF do emitente do evento.
Chave de Acesso da NF-e (chNFe): Chave de acesso da NF-e relacionada ao evento.
Data e Hora do Evento (dhEvento): Data e hora do evento no formato UTC.
Código do Evento (tpEvento): Identifica o tipo de evento (ex: cancelamento, carta de correção).
Número Sequencial do Evento (nSeqEvento): Sequência do evento.
Descrição do Evento (xEvento): Descrição textual do evento.
Data de Autorização do Evento (dhRecbto): Data de autorização do evento.
Número de Protocolo do Evento (nProt): Protocolo de autorização do evento.

Visão Geral do Modelo de Distribuição

O modelo de distribuição de documentos é baseado na geração de um Número Sequencial Único (NSU) para cada CNPJ ou CPF interessado. A consulta ao Web Service NFeDistribuicaoDFe pode ser feita a qualquer momento.

Um fluxo exemplifica o processo de geração de NSU para emitente e destinatário:

O 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 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 (ex: evento de manifestação do destinatário).
O Ambiente Nacional gera um NSU do evento para o emitente e o disponibiliza.
Se o evento de manifestação do destinatário for diferente de "desconhecimento da operação", o Ambiente Nacional gera um NSU para o destinatário com a NF-e completa (liberação do download).
O emitente consulta o NFeDistribuicaoDFe a partir do último NSU e recupera o evento do destinatário.
O destinatário consulta o NFeDistribuicaoDFe e recupera a NF-e completa.
O emitente gera um evento de sua NF-e (ex: cancelamento), que é compartilhado com o Ambiente Nacional.
O Ambiente Nacional gera um NSU para o destinatário do evento do emitente e o disponibiliza.
O destinatário consulta o NFeDistribuicaoDFe e recupera o evento do 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.
Ambos, emitente e destinatário, consultam o NFeDistribuicaoDFe e recuperam o evento do Fisco.

Este modelo resulta nos seguintes NSUs para cada ator no exemplo:

NSU Emitente
* 1: Evento do Destinatário
* 2: Evento do Fisco

NSU Destinatário
* 1: Resumo da NF-e
* 2: NF-e
* 3: Evento do Emitente
* 4: Evento do Fisco

Este modelo permite ao emitente consultar eventos manifestados pelos destinatários e ao destinatário acessar eventos gerados pelo emitente. Além disso, eventos gerados pelo Fisco são disponibilizados a ambos. A partir da manifestação do destinatário, o download da NF-e é simplificado, com a geração automática de um NSU referenciando a NF-e.

Recomendações Para Evitar o Uso Indevido

Para manter a estabilidade dos ambientes autorizadores, são aplicados controles para identificar e evitar o uso indevido do Web Service, como tentativas sucessivas e repetitivas de busca de registros já disponibilizados. Aplicações que entram em "loop", consumindo recursos excessivamente, sobrecarregam a comunicação. Tentativas de consumo indevido são rejeitadas com o código de erro "656-Rejeição: Consumo Indevido".

Conclusão

O Web Service NFeDistribuicaoDFe centraliza e facilita a consulta de documentos fiscais eletrônicos e resumos de eventos por todos os atores da NF-e. Ao prover um mecanismo eficiente e confiável para acesso a informações relevantes, o serviço otimiza a gestão fiscal das empresas e contadores. A padronização das mensagens, a compactação de dados e as rigorosas regras de validação garantem a segurança e a integridade do processo, resultando em maior transparência e controle sobre os DF-e.

Tributos.io

Xml Nf E

NFeDistribuicaoDFe: Consulta NF-e e DF-e para Atores Fiscais