Web Service NFeDistribuicaoDFe: Distribuição de DF-e e Eventos

O projeto Nota Fiscal Eletrônica (NFe) demanda um fornecimento de informações ágil e confiável aos diversos participantes envolvidos. Para atender a essa necessidade, a Nota Técnica 2014/002 introduziu o Web Service NFeDistribuicaoDFe. Este serviço visa disponibilizar documentos fiscais eletrônicos (DF-e) e informações resumidas para emitentes, destinatários, transportadores e terceiros com interesse em uma NFe.

O NFeDistribuicaoDFe substitui, a partir de maio de 2017, os Web Services NfeConsultaDest e NFeDownloadNF, unificando a distribuição de documentos. Ele permite que um ator da NFe acesse documentos que não gerou diretamente, mas que são de seu interesse fiscal.

Evolução do Web Service NFeDistribuicaoDFe

O Web Service NFeDistribuicaoDFe passou por atualizações para aprimorar a distribuição de DF-e. A versão inicial foi desenvolvida em janeiro de 2014. Em outubro de 2016, a Nota Técnica 2014/002 incluiu a distribuição de novos eventos, como o Registro de Passagem, Pedido de Prorrogação/Cancelamento do prazo de suspensão do ICMS em remessas para industrialização, e outros Eventos de Resposta do Fisco. Também foi adicionada a consulta ao Web Service por uma chave de acesso específica da NFe.

Outra mudança importante foi a distribuição do Evento de Cancelamento para o destinatário, independentemente de sua manifestação. O pacote de schemas PL_NFeDistDFe_102 entrou em vigência em ambiente de homologação em 05/12/2016 e em ambiente de produção em 09/01/2017. Os Web Services NfeConsultaDest e NFeDownloadNF foram desativados em 31/05/2017.

Função do Web Service NFeDistribuicaoDFe

Este serviço tem como função distribuir informações resumidas e documentos fiscais eletrônicos (DF-e) de interesse de um ator, seja ele pessoa física ou jurídica. O processo é síncrono e utiliza o método nfeDistDFeInteresse.

A consulta pode ser feita por qualquer ator da NFe (emitente, destinatário, transportador ou terceiro) que possua um certificado digital, seja de pessoa jurídica (PJ) ou pessoa física (PF). Para uma Pessoa Jurídica, a autenticação ocorre pelo CNPJ base, e a consulta pode ser realizada com qualquer CNPJ da empresa, desde que o CNPJ base consultado seja o mesmo do certificado digital.

Documentos e informações resumidas ficam disponíveis para distribuição por até três meses após a recepção pelo Ambiente Nacional da NFe. A distribuição é direcionada aos atores que desempenham papéis específicos na NFe, identificados nos grupos do Emitente (emit), Destinatário (dest), Transportador (transporta) e pessoas físicas autorizadas a acessar o XML (autXML).

Documentos e eventos disponíveis para distribuição

A tabela abaixo detalha quais documentos e eventos são distribuídos e para quais atores, considerando as condições específicas para acesso:

• NF-e: Disponível para destinatário (com manifestação de "Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação"), transportador (identificado no grupo X03) e terceiros (cujo CNPJ ou CPF esteja na tag autXML).
• Evento de Cancelamento: Disponível para destinatário, transportador e terceiros, mesmo sem manifestação.
• Evento de Carta de Correção: Disponível para destinatário, transportador e terceiros.
• Eventos de Manifestação do Destinatário: Disponível para emitente e terceiros.
• Eventos da Suframa (Vistoria/Internalização): Disponível para emitente, destinatário e terceiros.
• EPEC: Disponível para destinatário e transportador.
• Eventos de Pedido de Prorrogação de Prazo (NT 2015.001): Disponível para destinatário.
• Eventos do Fisco em Resposta ao Pedido de Prorrogação (NT 2015.001): Disponível para emitente e destinatário.
• Evento de Averbação: Disponível para emitente, destinatário, transportador e terceiros.
• Resumo de NF-e: Disponível para destinatário (antes da manifestação).
• Resumo de Eventos CT-e Autorizado/Cancelado: Disponível para emitente, destinatário, transportador e terceiros.
• Resumo de Eventos MDF-e Autorizado/Cancelado: Disponível para emitente, destinatário, transportador e terceiros.
• Resumo de Eventos de Registro de Passagem: Disponível para emitente, destinatário, transportador e terceiros.

Estrutura das mensagens

As interações com o Web Service NFeDistribuicaoDFe seguem leiautes XML específicos tanto para a mensagem de entrada quanto para a de retorno.

Mensagem de entrada

A mensagem de entrada é uma estrutura XML com o pedido de distribuição de DF-e. Os principais campos incluem:

• Versão do leiaute: Identifica a versão do layout utilizado.
• Ambiente de operação (tpAmb): Indica se é produção (1) ou homologação (2).
• Código da UF do autor (cUFAutor): Código do estado do autor da solicitação (opcional).
• CNPJ ou CPF do interessado: Permite a recuperação de DF-e para qualquer estabelecimento de uma empresa usando um único certificado digital PJ, ou para o CPF da pessoa física.
• Grupo para distribuição (distNSU): Contém o último número sequencial único (ultNSU) recebido. Se o ultNSU for zero ou muito antigo, a consulta retorna informações dos últimos 3 meses.
• Grupo para consulta por NSU específico (consNSU): Contém o NSU do documento fiscal a ser consultado pontualmente.
• Grupo para consulta por chave de acesso NFe (consChNFe): Contém a chave de acesso específica da NFe para consulta.

Mensagem de retorno

A mensagem de retorno é uma estrutura XML contendo os documentos de interesse do ator, com um limite máximo de 50 documentos por lote. Os campos relevantes são:

• Versão do leiaute: Versão do layout de retorno.
• Ambiente de operação (tpAmb): Indica se é produção ou homologação.
• Versão do aplicativo (verAplic): Versão do sistema que processou a consulta.
• Código e descrição do status (cStat, xMotivo): Indicam o resultado do processamento da requisição.
• Data e hora da resposta (dhResp): Horário da mensagem de retorno.
• Último NSU pesquisado (ultNSU): O NSU até onde a consulta foi processada. Permite que o solicitante continue a busca.
• Maior NSU no Ambiente Nacional (maxNSU): O maior NSU disponível para o CNPJ/CPF consultado.
• Lote de documentos (loteDistDFeInt): Contém o conjunto de informações resumidas e documentos fiscais.
• Documento compactado (docZip): Informação resumida ou documento fiscal eletrônico de interesse, compactado no padrão Gzip. Cada documento tem seu NSU e identificação do schema XML para validação.

Mensagem de retorno compactada

Para otimizar a infraestrutura de rede, cada documento na mensagem de retorno é compactado individualmente no padrão Gzip. Essa compactação reduz o tamanho da mensagem em cerca de 60%. A aplicação cliente deve descompactar os documentos para processamento.

Processo de distribuição de DF-e

O Ambiente Nacional atribui um Número Sequencial Único (NSU) a cada documento fiscal eletrônico para cada interessado. Isso garante uma sequência de numeração sem intervalos na base de dados do interessado.

O XML do pedido de distribuição suporta três tipos de consultas, definidas pelas tags distNSU, consNSU e consChNFe.

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

Neste tipo de consulta, a aplicação cliente informa o último NSU que possui (ultNSU). O Ambiente Nacional retorna um lote de até 50 documentos com NSU superior ao informado. Se o ultNSU for menor que o primeiro NSU disponível, a consulta retorna documentos a partir do primeiro.

Os lotes são gerados em ordem crescente de NSU e podem conter diversos tipos de documentos. Documentos emitidos pela própria empresa não estão disponíveis nesta consulta. É recomendado aguardar pelo menos uma hora para uma nova solicitação caso não haja mais documentos a serem pesquisados.

Consulta DF-e vinculado ao NSU informado (consNSU)

Quando uma lacuna é identificada na sequência de NSUs do interessado, este método permite consultar pontualmente um NSU específico. A aplicação cliente informa o NSU faltante, e o Web Service retorna o documento correspondente ou informa que o NSU não existe.

Consulta de NFe por chave de acesso informada (consChNFe)

Este processo permite consultar uma NFe 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.

• 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 NFe completa é retornada. Caso contrário, apenas o resumo da NFe é disponibilizado.
• Para transportador e terceiros: A NFe é disponibilizada integralmente.
• Para o emitente: A NFe não é disponibilizada por esta consulta.

A consulta por chave de acesso está disponível para documentos recebidos pelo Ambiente Nacional nos últimos 90 dias. Após esse período, não é possível recuperar a NFe.

Respostas das requisições

Para todas as modalidades de consulta, a resposta do Web Service pode ser:

• Rejeição: Com um código e motivo da falha (cStat).
• Nenhum documento localizado: (cStat='137').
• Documento(s) localizado(s): (cStat='138') com a devolução dos documentos fiscais.

Validação

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

Validação do certificado de transmissão

São verificadas a validade do certificado, a cadeia de certificação (ICP-Brasil), a presença da extensão de CNPJ ou CPF, e se o certificado não está revogado. Estas validações são críticas para a autenticação do ator.

Validação inicial da mensagem

O sistema verifica se o tamanho do XML de dados não excede 10 KB. Mensagens maiores podem ser descartadas. Também são realizadas verificações sobre a disponibilidade do servidor de processamento.

Validação da área de dados

Inclui a verificação do schema XML, o uso correto de prefixos no namespace, a codificação UTF-8, e se a versão dos dados informada é suportada.

Validação de regras de negócio

Estas são validações essenciais para o processamento da requisição:

• Ambiente: O tipo de ambiente da NFe deve ser igual ao ambiente do Web Service.
• CNPJ/CPF: Validação do formato e dígitos verificadores do CNPJ ou CPF do interessado.
• Certificado digital: O CNPJ base do certificado digital deve ser o mesmo do CNPJ consultado. Similarmente para o CPF.
• NSU: O NSU informado não pode ser superior ao maior NSU disponível no Ambiente Nacional.
• Chave de acesso: Validação do dígito verificador, código da UF, ano, mês, CNPJ, modelo (deve ser 55 para NFe) e número da NFe.
• Prazo de download: Verifica se a NFe está no prazo de 90 dias do recebimento no Ambiente Nacional.
• Permissão: Verifica se o CNPJ/CPF do interessado tem permissão para consultar a NFe e se não é o emitente da NFe (neste tipo de consulta).
• Situação da NFe: NF-e Cancelada ou Denegada não estará disponível para download via consulta por chave.

Leiautes resumidos

Para viabilizar o compartilhamento de informações relevantes mantendo o sigilo, foram criados leiautes resumidos da NFe e de eventos.

Leiaute resumo da NFe (resNFe)

Esta estrutura XML contém informações resumidas de uma NFe, gerada pelo Ambiente Nacional quando a NFe é autorizada ou denegada. É distribuído aos destinatários para que possam se manifestar sobre a operação. Inclui campos como a chave de acesso, CNPJ/CPF e razão social do emitente, inscrição estadual, data de emissão, tipo de operação, valor total da NFe, digest value, data de recebimento e número do protocolo, além da situação da NFe (uso autorizado, denegado, cancelada).

Leiaute resumo do evento de NFe (resEvento)

Esta estrutura XML contém informações resumidas de um evento de NFe. Contém campos como o código do órgão de recepção, CNPJ/CPF do emitente, chave de acesso da NFe, data e hora do evento, código e descrição do evento, número sequencial, data de autorização e número do protocolo do evento.

Modelo de distribuição

O modelo de distribuição se baseia na geração de um NSU para cada CNPJ ou CPF interessado. O Ambiente Nacional gera e disponibiliza NSUs para emitentes e destinatários conforme o fluxo de eventos e documentos. Por exemplo:

1. O emitente transmite uma NFe, que é autorizada e compartilhada com o Ambiente Nacional.
2. Um NSU é gerado para o destinatário com o resumo da NFe.
3. O destinatário consulta o Web Service NFeDistribuicaoDFe e recupera o resumo.
4. O destinatário gera um evento (como manifestação).
5. Um NSU do evento é gerado para o emitente.
6. Se a manifestação do destinatário liberar, um NSU é gerado para o destinatário com a NFe completa para download.
7. Emitente e destinatário consultam seus respectivos NSUs para recuperar os documentos e eventos de seu interesse.

Esse modelo permite que emitentes consultem eventos manifestados por destinatários e que destinatários recebam eventos gerados pelos emitentes ou pelo fisco. O download da NFe é simplificado, pois o Ambiente Nacional gera automaticamente um NSU referenciando a NFe após a manifestação do destinatário, permitindo sua recuperação. Outros documentos técnicos sobre o Projeto Nota Fiscal Eletrônica podem ser consultados para mais detalhes aqui e aqui.

Prevenção de uso indevido

Para evitar sobrecarga nos ambientes autorizadores devido a aplicações que realizam consultas repetitivas de registros já disponibilizados, o Web Service NFeDistribuicaoDFe possui controles. Tentativas sucessivas de busca de registros já entregues serão rejeitadas com o código de erro "656-Rejeição: Consumo Indevido".

Endereço do Web Service

O endereço oficial do Web Service de Distribuição do Ambiente Nacional está disponível no Portal da NFe (http://www.nfe.fazenda.gov.br/portal), na seção "Serviços" / "Relação de Serviços Web". O mesmo se aplica ao ambiente de homologação, acessível pelo Portal de Homologação (http://hom.nfe.fazenda.gov.br/portal).

Códigos de erros

A Nota Técnica 2014/002 detalha uma tabela completa de códigos de erros e descrições de mensagens, indicando o resultado do processamento ou o motivo do não atendimento da solicitação. Estes códigos são essenciais para o diagnóstico de problemas na comunicação com o Web Service, cobrindo desde falhas de certificado (280, 281) e schema XML (215) até validações de regras de negócio (489, 490 para CNPJ/CPF inválido, 614 a 619 para chave de acesso inválida) e condições de acesso (632 para prazo excedido, 640 para permissão negada, 656 para consumo indevido).

Conclusão

O Web Service NFeDistribuicaoDFe, conforme detalhado na Nota Técnica 2014/002, representa uma solução centralizada para a distribuição de documentos fiscais eletrônicos e eventos relacionados à NFe. Ele oferece um mecanismo eficiente para que os atores do processo (emitentes, destinatários, transportadores e terceiros) acessem informações de seu interesse de forma padronizada e segura, utilizando um sistema de NSU e consultas específicas. A compreensão dos leiautes, processos de consulta, validações e códigos de erro é fundamental para a correta integração e uso deste serviço pelos contadores e empresas.