Web Service NFeDistribuicaoDFe: Consulta a NF-e e Eventos Fiscais

A Nota Técnica 2014/002 estabeleceu o Web Service NFeDistribuicaoDFe, um serviço para disponibilizar informações e documentos fiscais eletrônicos (DF-e) a emitentes, destinatários, transportadores e terceiros. Este serviço visa prover acesso eficiente e confiável a dados de NF-e, substituindo funcionalidades de outros Web Services. Ele permite aos atores fiscais obter documentos e eventos de seu interesse que não foram gerados por eles mesmos.

Introdução ao NFeDistribuicaoDFe

O projeto Nota Fiscal Eletrônica (NF-e) enfrenta o desafio de fornecer informações relevantes aos envolvidos nos processos de forma eficiente. O Web Service NFeDistribuicaoDFe foi criado para centralizar a distribuição de documentos fiscais eletrônicos e informações resumidas. Ele busca atender às necessidades de diversos atores que antes dependiam de outros serviços, como o NfeConsultaDest, que será descontinuado.

A versão 1.02 da Nota Técnica, divulgada em Outubro de 2016, trouxe evoluções, incluindo a distribuição de novos eventos como Registro de Passagem, Pedido de Prorrogação de ICMS e Eventos de Resposta do Fisco. Também foi adicionada a possibilidade de consultar uma NF-e específica pela chave de acesso. O início da vigência em ambiente de homologação ocorreu em 05/12/2016, e em produção em 09/01/2017. Os Web Services NfeConsultaDest e NFeDownloadNF foram desativados em 02/05/2017.

Atores e Documentos Distribuídos

O serviço NFeDistribuicaoDFe distribui documentos e informações para atores que desempenham papéis na NF-e, como emitentes, destinatários, transportadores e terceiros. Para acessar, é necessário possuir um certificado digital (PJ ou PF). No caso de pessoa jurídica, a consulta pode ser feita com qualquer CNPJ da empresa, desde que o CNPJ base seja o mesmo do certificado digital utilizado na autenticação.

Os documentos fiscais eletrônicos e 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 ocorre para os seguintes atores, conforme suas características:

Emitente: Recebe Eventos de Manifestação do Destinatário, Eventos da Suframa, Eventos do Fisco em Resposta a 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: Tem acesso a NF-e (após manifestação), Eventos de Cancelamento, Eventos de Carta de Correção, Eventos da Suframa, EPEC, Eventos de Pedido de Prorrogação de Prazo, Eventos do Fisco em Resposta a 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.
- A NF-e integral só é liberada ao destinatário após manifestação como "Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação". Antes disso, ou em caso de cancelamento, somente o "Resumo de NF-e" e o Evento de Cancelamento são disponibilizados.
Transportador: A NF-e, Eventos de Cancelamento, Eventos 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 são disponibilizados apenas se o transportador for identificado no grupo X03 da NF-e.
Terceiros: A NF-e, Eventos de Cancelamento, Eventos 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 são acessíveis apenas se o CNPJ ou CPF estiver informado na tag autXML.

Os Eventos de Pedido de Prorrogação de Prazo mencionados incluem os da NT 2015.001, como EPP1, EPP2, ECPP1 e ECPP2. Da mesma forma, os Eventos do Fisco em Resposta ao Pedido de Prorrogação também se referem à NT 2015.001, abrangendo EFPP1, EFPP2, EFCPP1 e EFCPP2.

Tipos de Consulta Disponíveis

O XML de pedido de distribuição aceita três tipos de consulta, definidos pela tag informada no XML de entrada: distNSU, consNSU e consChNFe. O envio dessas informações é realizado por meio de Web Service, exigindo um certificado digital PJ ou PF válido.

Distribuição por NSU (distNSU)

Para obter um conjunto de DF-e a partir de um Número Sequencial Único (NSU) informado, a aplicação cliente deve enviar o último NSU que já possui. O Ambiente Nacional fornecerá os documentos a partir do primeiro NSU disponível para consulta que seja superior ao informado. Caso o NSU enviado seja menor que o primeiro NSU disponível, a consulta retornará a partir do primeiro documento existente na base do Ambiente Nacional.

O Web Service gera lotes de até 50 documentos, incluindo informações resumidas ou documentos fiscais eletrônicos, ordenados de forma crescente pelo NSU. Documentos emitidos pela própria empresa não são disponibilizados por essa consulta. A geração do NSU pelo Ambiente Nacional é organizada pela ordem cronológica de recepção dos documentos, não pela ordem de emissão ou autorização.

A resposta da solicitação pode ser:
* Rejeição: mensagem com o motivo da falha.
* Nenhum documento localizado: indica que não há documentos fiscais para o CNPJ/CPF informado (cStat = '137').
* Documento(s) localizado(s): devolve os documentos fiscais encontrados (cStat = '138').

É recomendado aguardar um período mínimo de uma hora antes de realizar uma nova solicitação se o ultNSU informado for igual ao maxNSU do Ambiente Nacional, indicando que não há novos documentos a serem pesquisados no momento.

Consulta por NSU Específico (consNSU)

Quando uma lacuna é identificada na sequência de NSUs do interessado, a consulta por NSU específico permite recuperar um documento pontual. A aplicação cliente informa o NSU faltante. Essa consulta preenche lacunas na base de dados do interessado.

As possíveis respostas são:
* Rejeição: com o motivo da falha.
* Nenhum documento localizado: o NSU não foi gerado pelo Ambiente Nacional (cStat = '137').
* Documento localizado: o documento fiscal é devolvido (cStat = '138').

Consulta por Chave de Acesso (consChNFe)

Este tipo de consulta permite que o interessado obtenha uma NF-e específica a partir de sua chave de acesso. A chave deve ser válida, existir no Ambiente Nacional e estar vinculada ao solicitante (destinatário, transportador ou terceiro).

Para o destinatário: a NF-e integral é retornada apenas se houver manifestação ("Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação"). Caso contrário, somente o resumo da NF-e é disponibilizado, contendo as informações necessárias para a manifestação.
Para transportador e terceiros: a NF-e completa é disponibilizada diretamente.
Para o emitente: a NF-e não é disponibilizada através desta consulta.

Assim como nas outras modalidades, esta consulta está limitada a documentos recebidos pelo Ambiente Nacional nos últimos 90 dias. Após este prazo, a NF-e não pode ser recuperada.

As respostas podem ser:
* Rejeição: com o motivo da falha.
* Nenhum documento localizado: a NF-e não existe (cStat = '137').
* Documento localizado: o documento fiscal é devolvido (cStat = '138').

Mensagens e Leiautes do Web Service

O NFeDistribuicaoDFe utiliza estruturas XML para mensagens de entrada e retorno, seguindo schemas específicos.

Mensagem de Entrada

A mensagem de entrada é uma estrutura XML com o pedido de distribuição, conforme o schema distDFeInt_v9.99.xsd. Inclui campos como:
* versao: Versão do leiaute.
* tpAmb: Identificação do ambiente (1=Produção / 2=Homologação).
* cUFAutor: Código da UF do autor.
* CNPJ ou CPF: Identificação do interessado no DF-e.
* Grupo distNSU: com o campo ultNSU (último NSU recebido).
* Grupo consNSU: com o campo NSU (NSU específico a consultar).
* Grupo consChNFe: com o campo chNFe (chave de acesso específica).

Mensagem de Retorno e Compactação Gzip

A mensagem de retorno é uma estrutura XML que contém os documentos de interesse do ator, seguindo o schema retDistDFeInt_v9.99.xsd. Pode conter até 50 documentos. Os campos incluem:
* versao: Versão do leiaute.
* tpAmb: Ambiente (Produção/Homologação).
* verAplic: Versão do aplicativo que processou a consulta.
* cStat: Código do status da resposta.
* xMotivo: Descrição literal do status.
* dhResp: Data e hora da resposta (UTC).
* ultNSU: Último NSU pesquisado, para continuar a consulta.
* maxNSU: Maior NSU existente no Ambiente Nacional para o CNPJ/CPF informado.
* loteDistDFeInt: Conjunto de informações e documentos.

Para otimizar a infraestrutura de rede, cada documento na mensagem de retorno é compactado individualmente no padrão Gzip (tag docZip). Essa compactação pode reduzir o tamanho da mensagem em aproximadamente 60%. A aplicação cliente é responsável por descompactar o conteúdo antes de seu tratamento normal.

Leiautes Resumidos: NF-e e Eventos

Para compartilhar informações relevantes mantendo o sigilo, foram criados leiautes resumidos para NF-e e eventos.

Leiaute Resumo da NF-e

A estrutura XML resNFe_v9.99.xsd é gerada pelo Ambiente Nacional com informações resumidas da NF-e quando esta é autorizada ou denegada. Este documento é distribuído aos destinatários para possibilitar sua manifestação. Contém campos como:
* chNFe: Chave de acesso da NF-e.
* 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 NF-e.
* tpNF: Tipo de operação (Entrada/Saída).
* vNF: Valor Total da NF-e.
* digVal: Digest Value da NF-e.
* dhRecbto: Data de autorização da NF-e.
* nProt: Número de protocolo da NF-e.
* cSitNFe: Situação da NF-e (Uso autorizado, denegado, cancelado).

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:
* cOrgao: Código do órgão de recepção do Evento (91 para Ambiente Nacional).
* CNPJ ou CPF: Do emitente.
* chNFe: Chave de acesso da NF-e.
* 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.

Validações e Regras de Negócio

O processamento das requisições no Web Service NFeDistribuicaoDFe envolve uma série de validações para garantir a integridade e segurança das informações.

Validação do Certificado de Transmissão

São realizadas verificações sobre o certificado digital utilizado na transmissão, incluindo:
* Certificado Inválido (280): Inexistente, versão incorreta, Basic Constraint incorreto, KeyUsage não define "Autenticação Cliente".
* Validade (281): Data de início e fim.
* Cadeia de Certificação (283): AC emissora não cadastrada, AC revogada, certificado não assinado pela AC.
* LCR (286): Endereço da LCR (CRL DistributionPoint) ausente, indisponível ou inválida.
* Certificado Revogado (284): O certificado do transmissor está revogado.
* Certificado Raiz (285): Diferente da "ICP-Brasil".
* Extensão CNPJ/CPF (473): Ausência da extensão de CNPJ ou CPF no certificado.

A maioria dessas validações é tratada pelo protocolo SSL, enquanto outras podem ser implementadas pelo aplicativo do Web Service.

Validação Inicial da Mensagem

O Ambiente Nacional executa validações preliminares na mensagem recebida:
* Tamanho do XML (214): A mensagem é descartada se o tamanho exceder 10 KB.
* Serviço Paralisado (108/109): Verifica se o servidor de processamento está temporária ou indefinidamente paralisado.

Validação da Área de Dados

A área de dados da mensagem XML passa por validações de formato e regras de negócio.

Validação de forma da área de dados

Schema XML (215): Verifica a conformidade com o schema XML.
Prefixo Namespace (404): Proíbe o uso de prefixos de namespace não permitidos.
Codificação UTF-8 (402): Rejeita XML com codificação diferente de UTF-8.
Versão dos Dados (238/239): Verifica se a versão informada é suportada ou superior à vigente.

Validação de regras de negócio

Ambiente Divergente (252): O ambiente da NF-e difere do ambiente do Web Service.
CNPJ/CPF Inválido (489/490): CNPJ ou CPF do interessado na distribuição com dígito verificador ou zeros inválidos.
CNPJ-Base/CPF do Certificado Divergente (593/472): O CNPJ-Base ou CPF do certificado digital não corresponde ao CNPJ/CPF consultado.
NSU Superior ao Máximo (589): O NSU informado é maior que o NSU máximo disponível.
Chave de Acesso Inválida (236, 614, 615, 616, 617, 618, 619): Diversos erros de formato na chave, como DV inválido, código UF inválido, ano/mês fora do período ou número da NF igual a zero.
NF-e Inexistente (217): Não há NF-e para a chave de acesso informada.
Fora do Prazo de Download (632): A NF-e não está disponível para download por ter ultrapassado 90 dias da recepção.
Permissão de Consulta (640): O CNPJ/CPF do interessado não possui permissão para consultar a NF-e.
NF-e Indisponível para Emitente (641): O emitente não pode consultar sua própria NF-e por este serviço.
NF-e Cancelada/Denegada (653/654): O arquivo da NF-e está indisponível para download devido a cancelamento ou denegação.

Visão Geral do Fluxo de Distribuição

O modelo de distribuição de documentos é baseado na atribuição de um Número Sequencial Único (NSU) para cada CNPJ ou CPF. O Ambiente Nacional gera um NSU para cada documento ou evento de interesse dos atores, organizando-os cronologicamente pela ordem de recepção.

Um fluxo comum de distribuição ocorre da seguinte forma:
1. O emitente 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.
3. O destinatário consulta o NFeDistribuicaoDFe com seu último NSU e recupera o resumo da NF-e.
4. Com o resumo, o destinatário pode gerar um evento (ex: manifestação do destinatário).
5. O Ambiente Nacional gera um NSU do evento para o emitente e o disponibiliza.
6. Se for um evento de manifestação (exceto "desconhecimento da operação"), o Ambiente Nacional gera um NSU para o destinatário, referenciando a NF-e completa para download.
7. O emitente consulta o NFeDistribuicaoDFe e recupera o evento gerado pelo destinatário.
8. O destinatário consulta o NFeDistribuicaoDFe e recupera a NF-e completa.
9. O emitente pode gerar um evento para sua NF-e (ex: cancelamento), que é compartilhado com o Ambiente Nacional.
10. O Ambiente Nacional gera um NSU do evento para o destinatário e o disponibiliza.
11. O destinatário consulta o NFeDistribuicaoDFe e recupera o evento gerado pelo emitente.
12. Um evento gerado pelo fisco é recebido pelo Ambiente Nacional, que gera NSUs para o emitente e o destinatário, disponibilizando-os.
13. Ambos, emitente e destinatário, consultam o NFeDistribuicaoDFe e recuperam o evento do fisco.

Este modelo permite que emitentes consultem eventos de manifestação dos destinatários e que destinatários recebam qualquer evento gerado pelo emitente. Eventos do fisco também são disponibilizados para ambos. O processo de download da NF-e é simplificado, com a liberação automática após a manifestação do destinatário.

Recomendações de Uso e Prevenção de Abuso

O Ambiente Nacional implementa controles para identificar o uso indevido do Web Service, como tentativas repetidas de busca por registros já fornecidos. Aplicações que entram em "loop" e sobrecarregam o sistema podem ter suas requisições rejeitadas com o erro "656-Rejeição: Consumo Indevido". Essas medidas visam manter a estabilidade e disponibilidade do serviço.

Endereço do Web Service

O endereço para o Web Service de Distribuição do Ambiente Nacional está disponível no Portal da NF-e. Para o ambiente de homologação, o endereço é publicado no Portal de Homologação da NF-e.

Tabela de Códigos de Erros e Descrições de Mensagens de Erros

A Nota Técnica detalha uma série de códigos de erro (cStat) e suas descrições literais, que são retornados pelo Web Service em caso de falha no processamento da solicitação ou nos motivos de não atendimento. Exemplos incluem:
* 108: Serviço Paralisado Momentaneamente.
* 137: Nenhum documento localizado.
* 138: Documento localizado.
* 214: Rejeição: Tamanho da mensagem excedeu o limite.
* 280: Rejeição: Certificado Transmissor inválido.
* 489: Rejeição: CNPJ informado inválido.
* 632: Rejeição: Solicitação fora de prazo.
* 656: Rejeição: Consumo Indevido.

É recomendado evitar caracteres especiais ou acentuação nos textos das mensagens de erro para melhor compatibilidade.

Conclusão

O Web Service NFeDistribuicaoDFe representa uma evolução para a gestão de documentos fiscais eletrônicos, centralizando e otimizando o acesso às informações de interesse dos diversos atores envolvidos na NF-e. Ao consolidar a distribuição de documentos e eventos, e estabelecer regras claras de consulta e validação, o serviço busca aprimorar a eficiência e a confiabilidade dos processos fiscais para empresas e contadores. A compreensão de seus mecanismos, tipos de consulta e validações é fundamental para o aproveitamento integral dessa funcionalidade.

Tributos.io

Obrigações Fiscais

Web Service NFeDistribuicaoDFe: Consulta a NF-e e Eventos Fiscais