NFe: Distribuição de DF-e via Web Service - Acesso e NT 2014.002 (2024)

A gestão da Nota Fiscal Eletrônica (NF-e) envolve a troca de informações fiscais entre diversos atores. Para otimizar este processo, o Ambiente Nacional disponibiliza o Web Service NFeDistribuicaoDFe, que permite o acesso a Documentos Fiscais Eletrônicos (DF-e) de interesse de pessoas físicas e jurídicas. O objetivo é prover informações de forma eficiente e confiável, regulamentadas pela Nota Técnica 2014.002, Versão 1.20, de Maio de 2024.

Histórico de alterações e cronograma

A Nota Técnica 2014.002 passou por diversas atualizações desde sua versão inicial. Estas mudanças visaram aprimorar a distribuição de documentos e eventos, garantindo maior abrangência e controle.

Inicialmente desenvolvida pelo Serpro, a versão 1.00 foi implantada em produção em janeiro de 2014. As versões seguintes trouxeram acertos e novas funcionalidades.

• A versão 1.02b, implantada em outubro de 2016, incluiu a distribuição de eventos como Registro de Passagem, Pedido de Prorrogação e Cancelamento do prazo de suspensão do ICMS. Também passou a permitir a consulta por chave de acesso da NF-e e a distribuição do evento de cancelamento para o destinatário, mesmo sem sua manifestação prévia.
• A versão 1.02c, implantada em setembro de 2020, adicionou a distribuição dos Eventos de Averbação e do Evento de Comprovante de Entrega. Melhorias na documentação, como o detalhamento dos tipos de consulta e situações de uso indevido, foram introduzidas na versão 1.02d.
• As versões 1.10 e 1.11, implementadas em novembro de 2021, otimizaram a geração de NSU para a distribuição de NF-e e eventos, incluindo o evento de comprovante de entrega da NF-e (NT 2021.001).
• A versão 1.12, de março de 2022, trouxe melhorias na documentação.
• A versão 1.13, de maio de 2022, implementou a disponibilização de eventos do Fisco para emitentes e destinatários iguais.
• A versão 1.14, de maio de 2022, introduziu o retorno do ultNSU na rejeição 656 em consultas do tipo distNSU.
• A versão 1.15, também de maio de 2022, tornou o retorno do NSU facultativo.
• A versão 1.20, de maio de 2024, incluiu a distribuição do evento "Ator Interessado".

Web Service NFeDistribuicaoDFe

O Web Service NFeDistribuicaoDFe atua na distribuição de informações resumidas e documentos fiscais eletrônicos para os atores da NF-e. Seu objetivo é permitir que pessoas físicas e jurídicas, munidas de um certificado digital, acessem DF-e que não foram gerados por elas, mas que são de seu interesse.

Este serviço é síncrono e utiliza o método nfeDistDFeInteresse. A autenticação para pessoas jurídicas é feita pelo CNPJ base (os oito primeiros dígitos), permitindo a consulta para qualquer CNPJ completo (14 dígitos) da empresa, desde que o CNPJ base consultado corresponda ao do certificado digital.

Documentos fiscais eletrônicos e informações resumidas ficam disponíveis para distribuição por até 90 dias após sua recepção pelo Ambiente Nacional.

Documentos e acesso por ator

A distribuição de DF-e ocorre para os atores que desempenham papéis de emitente, destinatário, transportador e terceiros (informados no grupo autXML do XML da NF-e), e também para CNPJ informado no evento 'Ator Interessado'. O acesso aos documentos varia conforme o papel do ator, conforme detalhado na Nota Técnica 2014.002:

• NF-e: Disponível para destinatário, transportador, terceiros e CNPJ do Ator Interessado. Para o destinatário, a NF-e completa só é liberada após manifestação ("Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação"). Caso contrário, é retornado apenas o resumo. Para transportador e terceiros, a NF-e é disponibilizada integralmente.
• Evento de Cancelamento, Carta de Correção, Averbação, Comprovante de Entrega: Disponíveis para destinatário, transportador, terceiros e CNPJ do Ator Interessado.
• Eventos de Manifestação do Destinatário: Disponíveis para emitente e terceiros.
• Eventos da Suframa (Vistoria/Internalização): Disponíveis para emitente, destinatário e terceiros.
• EPEC: Disponível para destinatário, transportador e CNPJ do Ator Interessado.
• Eventos de Pedido de Prorrogação de Prazo e Eventos do Fisco em Resposta ao Pedido de Prorrogação: Disponíveis para emitente e destinatário.
• Resumos (NF-e, Eventos CT-e/MDF-e Autorizado/Cancelado, Eventos de Registro de Passagem): Disponíveis para os atores conforme a necessidade de informação resumida para tomada de decisão ou manifestação.

A partir da versão 1.13 da Nota Técnica, eventos gerados pelo Fisco são distribuídos ao emitente, mesmo que emitente e destinatário sejam o mesmo, e independentemente da manifestação do destinatário.

Processo de distribuição de DF-e de interesse

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, considera somente os usuários do serviço nos últimos 60 dias.

• Para usuários ativos no período, a geração de NSU continua normalmente.
• Para novos usuários, o NSU é gerado a partir do primeiro acesso, sem retroatividade.
• Usuários que inativam o serviço por mais de 60 dias têm a geração de NSU interrompida, sendo retomada a partir da próxima consulta, também sem retroatividade ao período de interrupção. O primeiro acesso nessas situações retorna "Nenhum documento localizado" (cStat=137), sendo necessário aguardar o prazo de 1 hora para novas consultas.

A verificação de continuidade de uso do serviço é feita pelo CPF ou CNPJ base informado na requisição XML. Antes de gerar NSU para transportador e CNPJ do campo autXML, é verificado se esses CNPJs também são destinatários na mesma NF-e. Se forem, o NSU não é gerado até que o destinatário realize a manifestação.

Os documentos recuperados devem conter uma sequência de numeração sem intervalos em sua base de dados, em ordem crescente de NSU.

Tipos de consulta

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

1. Distribuição de Conjunto de DF-e a partir do NSU Informado (distNSU): A aplicação cliente informa o último NSU que possui (ultNSU). 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 disponível, são fornecidos documentos fiscais dos NSUs mais antigos, desde que autorizados há menos de 90 dias. Os lotes contêm até 50 documentos, organizados por ordem cronológica de recepção e inserção dos DF-e no Ambiente Nacional.
2. Consulta DF-e Vinculado ao NSU Informado (consNSU): Permite consultar pontualmente um NSU específico que foi identificado como faltante na base de dados do interessado. O Ambiente Nacional retorna um único documento fiscal (NF-e ou evento) referente ao NSU solicitado.
3. Consulta de NF-e por Chave de Acesso Informada (consChNFe): Permite consultar uma NF-e específica pela sua chave de acesso. O Ambiente Nacional retorna somente a NF-e (não eventos) relativa à chave informada. A partir da versão 1.15 da Nota Técnica, esta consulta não exige a geração prévia de NSU para o documento.

Para todas as consultas, os documentos ficam disponíveis por até 90 dias após a recepção pelo Ambiente Nacional.

Mensagens de entrada e retorno

As mensagens de entrada e retorno do Web Service NFeDistribuicaoDFe são estruturadas em XML.

• Mensagem de Entrada: Contém o pedido de distribuição de DF-e de interesse. Campos chave incluem: tpAmb (ambiente de produção ou homologação), cUFAutor (código da UF do autor), CNPJ ou CPF do interessado, e uma das tags de consulta (distNSU, consNSU ou consChNFe) com seus respectivos parâmetros (ultNSU, NSU ou chNFe).
• Mensagem de Retorno: Apresenta os documentos ou informações solicitadas. Inclui: cStat (código do status da resposta), xMotivo (descrição do status), dhResp (data e hora da resposta), ultNSU (último NSU pesquisado) e maxNSU (maior NSU existente). Se documentos forem localizados, eles vêm em um lote (loteDistDFeInt), compactados na tag docZip.

Mensagem de retorno compactada

Para otimizar a infraestrutura de rede e o canal de internet das empresas e do Ambiente Nacional, cada documento contido na mensagem de retorno é compactado individualmente no padrão Gzip. Estima-se uma redução de 60% no tamanho da mensagem de retorno. A aplicação cliente é responsável por descompactar o conteúdo da tag docZip para o tratamento normal do documento.

Leiautes resumidos

Para viabilizar o compartilhamento de informações relevantes mantendo o sigilo, foram criados leiautes contendo informações resumidas da NF-e (resNFe) e de eventos (resEvento).

• Leiaute Resumo da NF-e: Estrutura XML com informações resumidas da NF-e, como chave de acesso (chNFe), CNPJ/CPF e razão social do emitente, data de emissão (dhEmi), tipo de operação (tpNF), valor total da NF-e (vNF), e situação da NF-e (cSitNFe). Este resumo é distribuído para que o destinatário possa se manifestar sobre a operação.
• Leiaute Resumo do Evento de NF-e: Estrutura XML com informações resumidas de um evento da NF-e, incluindo o código do órgão de recepção, CNPJ/CPF do emitente, chave de acesso da NF-e, data e hora do evento (dhEvento), tipo e descrição do evento (tpEvento, xEvento), número sequencial e protocolo do evento (nSeqEvento, nProt).

Validações e rejeições no Web Service

Para garantir a integridade e segurança das operações, o Web Service NFeDistribuicaoDFe implementa diversas validações nas mensagens recebidas.

Validação do certificado de transmissão

Antes do processamento da requisição, o certificado digital do transmissor é validado. As regras abrangem:

• Validade do certificado (A01, A02).
• Verificação da cadeia de certificação (A03, A05).
• Disponibilidade e validade da Lista de Certificados Revogados (LCR) (A04).
• Certificado Raiz ICP-Brasil (A06).
• Presença da extensão de CNPJ ou CPF no certificado (A07).

Validação inicial da mensagem

São realizadas verificações básicas na mensagem XML:

• Tamanho do XML: O XML de dados não pode exceder 10 KB (B01). Mensagens maiores são descartadas.
• Serviço paralisado: Verifica se o servidor de processamento está temporária (B02) ou permanentemente paralisado (B03).

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: Inclui a verificação do Schema XML (D01), o uso de prefixo no namespace (D02), a codificação UTF-8 (D03), e a versão dos dados informada (D04, D05).
• Validação de regras de negócio: Garante a conformidade fiscal e operacional. Alguns exemplos incluem:
  • Ambiente da NF-e diferente do ambiente do Web Service (H01).
  • CNPJ ou CPF do interessado inválido (H02, H03).
  • CNPJ-base do certificado digital diferente do CNPJ-base consultado (H04).
  • CPF do certificado digital diferente do CPF consultado (H05).
  • NSU informado superior ao maior NSU disponível (H06).
  • Chave de acesso inválida por diversos motivos (H07 a H13).
  • NF-e inexistente para a chave de acesso (H14).
  • NF-e fora do prazo de 90 dias para download (H15).
  • Permissão de consulta (H16, H17).
  • NF-e Cancelada ou Denegada, tornando o arquivo indisponível (H18, H19).

A Nota Técnica 2014.002 detalha a tabela de códigos de erros (cStat) e descrições das mensagens de erro para auxiliar na identificação e correção de problemas.

Recomendações para evitar o uso indevido

O Ambiente Nacional monitora o uso do Web Service NFeDistribuicaoDFe para evitar sobrecargas e garantir a disponibilidade do serviço. O uso indevido pode resultar na rejeição "656-Rejeição: Consumo Indevido" e bloqueio do CNPJ/CPF por 1 hora.

As principais situações de uso indevido são:

1. Consulta excessiva sem documentos novos (distNSU): Se não há mais documentos a serem retornados (cStat=137), o usuário deve aguardar 1 hora para nova consulta. Tentativas antes desse prazo resultarão em consumo indevido.
2. Consulta de NSU fora de sequência (distNSU): O usuário deve sempre utilizar o ultNSU retornado na consulta anterior para manter a sequência. Consultas fora de ordem geram bloqueio. Se ultNSU for igual a maxNSU, significa que não há mais documentos naquele momento, e deve-se aguardar 1 hora.
3. Quantidade de consultas por chave de acesso ou NSU excedida (consChNFe, consNSU): Há um limite de 20 consultas por hora para estes tipos de requisição. Ultrapassar este limite resulta em bloqueio.

Quando uma mensagem cStat=656 é recebida, o tempo de bloqueio é de 1 hora. Tentar uma nova consulta antes de completar esse período reinicia a contagem. A partir da versão 1.14 da Nota Técnica, o ultNSU da última consulta é retornado na rejeição 656 para distNSU, permitindo que o usuário retome a consulta do ponto correto.

É importante que todas as aplicações de um mesmo ator (emitente, destinatário, transportador ou informado no autXML) que efetuem consultas por NSU sigam a mesma sequência numérica ordenada e ascendente para evitar o uso indevido.

Endereço dos Web Services

Os endereços dos Web Services de Distribuição do Ambiente Nacional são publicados no Portal Nacional da NF-e (http://www.nfe.fazenda.gov.br/portal) e no Portal de Homologação (http://hom.nfe.fazenda.gov.br/portal), no menu "Serviços" / "Relação de Servios Web".

Conclusão

O Web Service NFeDistribuicaoDFe é um componente essencial para a gestão eficiente da NF-e, permitindo que os diversos atores tenham acesso rápido e confiável aos documentos fiscais eletrônicos de seu interesse. O conhecimento das regras de acesso, tipos de consulta e validações é necessário para garantir a conformidade e evitar bloqueios por uso indevido. A aderência às diretrizes da Nota Técnica 2014.002 é fundamental para o sucesso na recuperação e gestão dos DF-e.