NFeDistribuicaoDFe: Acesso a documentos fiscais eletrônicos e resumos

O projeto Nota Fiscal Eletrônica (NF-e) visa prover informações de interesse de seus atores de forma eficiente e confiável. Para atender a essa demanda, a Secretaria da Fazenda disponibilizou o Web Service NFeDistribuicaoDFe. Este serviço permite que emitentes, destinatários, transportadores e terceiros acessem documentos fiscais eletrônicos (DF-e) e informações resumidas que não foram gerados por eles, mas são de seu interesse.

Objetivo do Web Service NFeDistribuicaoDFe

A Nota Técnica 2014/002 introduziu o Web Service NFeDistribuicaoDFe para disponibilizar documentos fiscais eletrônicos e informações resumidas. Este serviço atende a pessoas físicas ou jurídicas que possuam um certificado digital válido. Ele substitui o antigo Web Service de Consulta da Relação de Documentos Destinados (NfeConsultaDest), que foi desativado em maio de 2017.

O serviço é síncrono e utiliza o método nfeDistDFeInteresse. A distribuição ocorre para os atores da NF-e que desempenham papéis de:
* Emitente (identificado na tag emit)
* Destinatário (identificado na tag dest)
* Transportador (identificado na tag transporta)
* Terceiros autorizados a acessar o XML (identificados na tag autXML)

Os 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 NF-e.

Documentos e eventos disponíveis para distribuição

A distribuição de DF-e e resumos de eventos depende do papel do ator.

Documentos para destinatários

Para o destinatário, os documentos fiscais e resumos de eventos estarão disponíveis se houver uma manifestação de "Ciência da Operação", "Operação Não Realizada" ou "Confirmação de Operação" para a NF-e. Uma exceção é o Evento de Cancelamento, que é disponibilizado mesmo sem manifestação. Antes da manifestação, o destinatário acessa somente o "Resumo de NF-e" e o cancelamento de NF-e.

Documentos para transportadores e terceiros

A NF-e está disponível para o transportador se este for identificado no grupo X03 e para terceiros cujo CNPJ ou CPF esteja na tag autXML.

Tabela de disponibilidade por ator

A seguir, os documentos e eventos distribuídos conforme o papel do ator:

Documentos	Emitente	Destinatário	Transportador	Terceiros
NF-e	Não	Sim	Sim	Sim
Evento de Cancelamento	Não	Sim	Sim	Sim
Evento de Carta de Correção	Não	Sim	Sim	Sim
Eventos de Manifestação do Destinatário	Sim	Não	Não	Sim
Eventos da Suframa (Vistoria/Internalização)	Sim	Sim	Não	Sim
EPEC	Não	Sim	Sim	Não
Eventos de Pedido de Prorrogação de Prazo	Não	Sim	Não	Não
Eventos do Fisco em Resposta à Prorrogação	Sim	Sim	Não	Não
Resumo de NF-e	Não	Sim	Não	Não
Resumo de Eventos CT-e Autorizado/Cancelado	Sim	Sim	Sim	Sim
Resumo de Eventos MDF-e Autorizado/Cancelado	Sim	Sim	Sim	Sim
Resumo de Eventos de Registro de Passagem	Sim	Sim	Sim	Sim

Os Eventos de Pedido de Prorrogação de Prazo da NT 2015.001 incluem EPP1, EPP2, ECPP1 e ECPP2. Os eventos do Fisco em resposta, também da NT 2015.001, são EFPP1, EFPP2, EFCPP1 e EFCPP2. O Resumo de Eventos de Registro de Passagem é distribuído a partir da implantação da NT 2014/002 v.1.02.

Estrutura das mensagens

O serviço utiliza mensagens XML para entrada e retorno, com leiautes específicos.

Leiaute mensagem de entrada (distDFeInt_v9.99.xsd)

A mensagem de entrada é uma estrutura XML para o pedido de distribuição de DF-e. Contém informações como:
* Versão do leiaute: Especifica a versão utilizada.
* Tipo de ambiente: Indica se é produção (1) ou homologação (2).
* Código da UF do autor: Identifica a Unidade Federativa.
* CNPJ ou CPF do interessado: Permite a recuperação dos DF-e.
* Grupo para distribuição (distNSU): Contém o último NSU recebido pelo ator para buscar novos documentos. Se informado com zero ou um NSU muito antigo, a consulta retorna informações dos últimos 3 meses.
* Grupo para consulta (consNSU): Permite consultar um DF-e a partir de um NSU específico.

Leiaute mensagem de retorno (retDistDFeInt_v9.99.xsd)

A mensagem de retorno é uma estrutura XML com os documentos de interesse, com quantidade máxima de 50 documentos por lote. Os campos incluem:
* Versão do leiaute e tipo de ambiente.
* Versão do aplicativo: Versão do software que processou a consulta.
* Código e motivo do status da resposta: Indicam o resultado do processamento.
* Data e hora da resposta.
* Último NSU pesquisado (ultNSU): Permite continuar a consulta.
* Maior NSU existente (maxNSU): O maior NSU disponível no Ambiente Nacional para o CNPJ/CPF.
* Lote de documentos (loteDistDFeInt): Conjunto de informações resumidas e DF-e.
* Documento compactado (docZip): Cada informação ou documento é compactado no padrão Gzip.
* NSU do documento fiscal: Número Sequencial Único do DF-e.
* Schema: Identificação do Schema XML para validação do XML contido no docZip, como resNFe_v1.00.xsd ou procNFe_v3.10.xsd.

Mensagem de retorno compactada

Para otimizar o uso da rede, cada documento na mensagem de retorno é compactado usando o padrão Gzip. Essa compactação reduz o tamanho da mensagem em aproximadamente 60%. A aplicação cliente deve descompactar o documento e seguir o processamento normal.

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

O serviço pode ser utilizado por atores da NF-e (emitente, destinatário, transportador, terceiro), pessoas físicas ou jurídicas, com certificado digital. O Ambiente Nacional gera um Número Sequencial Único (NSU) para cada interessado nos documentos fiscais, garantindo uma sequência sem intervalos.

Geração do pedido de distribuição

O XML do pedido de distribuição suporta dois tipos de consulta:
* distNSU - Distribuição de conjunto de DF-e a partir do NSU informado: A aplicação cliente informa o último ultNSU que possui. Se o NSU for menor que o primeiro NSU disponível, o Ambiente Nacional fornecerá os documentos a partir do primeiro.
* consNSU - Distribuição de DF-e vinculado ao NSU informado: Usado para consultar um NSU específico que foi identificado como faltante 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 de interesse. Uma empresa pode recuperar os DF-e de qualquer um de seus estabelecimentos utilizando apenas um certificado digital de PJ, desde que o CNPJ base seja o mesmo.

Envio das informações

O pedido de distribuição é enviado via Web Service, exigindo um certificado digital de PJ ou PF válido. A aplicação cliente do interessado aciona o WS do Ambiente Nacional com uma mensagem que segue os padrões estabelecidos na Nota Técnica.

Processamento das requisições

Requisição de distribuição de conjunto de DF-e (distNSU)

O Web Service gera lotes de até 50 documentos, com informações resumidas ou DF-e, cujo NSU seja superior ao informado.
* Ordem: Os documentos são enviados em ordem crescente de NSU.
* Conteúdo: O lote pode conter qualquer tipo de documento válido e seu respectivo NSU.
* Limitação: Documentos emitidos pela própria empresa não estão disponíveis para consulta por este método.
* Sincronização: A geração do NSU é organizada pela ordem cronológica de recepção dos documentos pelo Ambiente Nacional, não pela ordem de emissão ou autorização.

As respostas possíveis são:
* Rejeição: Com o motivo da falha no cStat.
* Nenhum documento localizado: cStat='137-Nenhum documento localizado'.
* Documento localizado: cStat='138-Documento localizado'.

É recomendado aguardar um tempo mínimo de uma hora antes de efetuar nova solicitação se não houver mais documentos. Isso ocorre quando o ultNSU informado é igual ao maxNSU do Ambiente Nacional.

Requisição de distribuição de DF-e vinculado ao NSU (consNSU)

Este método é utilizado para preencher lacunas na base de dados do interessado, identificadas por falhas no processo de distribuição. O interessado consulta pontualmente os NSU faltantes.

As respostas possíveis são:
* Rejeição: Com o motivo da falha no cStat.
* Nenhum documento localizado: cStat='137-Nenhum documento localizado', indicando que o Ambiente Nacional não gerou o NSU e o interessado deve desconsiderá-lo.
* Documento localizado: cStat='138-Documento localizado', com a devolução do documento fiscal encontrado.

Validações do Web Service

O processo de comunicação com o Web Service envolve diversas validações.

Validação do certificado de transmissão

São verificados aspectos como:
* Certificado de Transmissor Inválido: Inexistência, versão incorreta, Basic Constraint true (não pode ser AC), KeyUsage sem "Autenticação Cliente".
* Validade do Certificado: Período de validade.
* Cadeia de Certificação: Certificado da AC emissora cadastrado, não revogado, assinado pela AC.
* Lista de Certificados Revogados (LCR): Endereço da LCR, disponibilidade e validade.
* Certificado Revogado.
* Certificado Raiz: Deve ser "ICP-Brasil".
* Extensão CNPJ/CPF: Ausência da extensão de CNPJ ou CPF no certificado.

A maioria dessas validações é feita pelo protocolo SSL, mas algumas verificações de certificado raiz e extensões específicas são críticas.

Validação inicial da mensagem no Web Service

A mensagem passa por validações básicas antes do processamento:
* Tamanho do XML: O XML de dados não pode exceder 10 KB. Mensagens maiores podem ser descartadas sem retorno de erro se o controle for feito por firewall.
* Serviço paralisado: Verifica se o serviço está paralisado momentaneamente (código 108) ou sem previsão (código 109).

Validação da área de dados

As validações ocorrem em duas frentes:
* Forma da área de dados:
* Verificação do Schema XML.
* Uso de prefixo no namespace.
* Codificação diferente de UTF-8 (rejeitado).
* Versão dos dados informada superior à vigente ou não suportada.
* Regras de negócio:
* Ambiente da NF-e difere do ambiente do Web Service.
* CNPJ ou CPF do interessado inválido.
* CNPJ base do certificado digital diferente do CNPJ base consultado.
* CPF do certificado digital diferente do CPF consultado.
* NSU informado superior ao maior NSU disponível para consulta.

Leiautes resumidos

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

Leiaute resumo da NF-e (resNFe_v9.99.xsd)

Essa estrutura XML é gerada pelo Ambiente Nacional com informações resumidas da NF-e. É distribuída aos destinatários para que possam manifestar-se na operação. Contém dados como:
* Chave de acesso da NF-e.
* CNPJ/CPF e razão social/nome do emitente.
* Inscrição Estadual (IE) do emitente.
* Data de emissão (dhEmi) e tipo de operação (tpNF).
* Valor total da NF-e (vNF).
* Digest Value e número de protocolo (nProt).
* Situação da NF-e (cSitNFe: 1=Uso autorizado; 2=Uso denegado).

Leiaute resumo do evento de NF-e (resEvento_v9.99.xsd)

Estrutura XML com informações resumidas de um evento de NF-e, contendo:
* Código do órgão de recepção do evento (91 para Ambiente Nacional).
* CNPJ/CPF do emitente e chave de acesso da NF-e.
* Data e hora do evento (dhEvento).
* Código (tpEvento) e número sequencial do evento (nSeqEvento).
* Descrição do evento (xEvento).
* Data de autorização e número de protocolo do evento.

Modelo geral de distribuição

O modelo de distribuição de documentos baseia-se na geração de um Número Sequencial Único (NSU) para cada CNPJ ou CPF. O Ambiente Nacional disponibiliza para consulta os documentos de interesse de cada ator, com um fluxo que inclui:
1. Emitente transmite NF-e, autorizada e compartilhada com o Ambiente Nacional.
2. Ambiente Nacional gera NSU para o destinatário do resumo da NF-e.
3. Destinatário consulta o WS NFeDistribuicaoDFe com o último NSU e recupera o resumo.
4. Destinatário gera evento de manifestação (ex: "Ciência da Operação").
5. Ambiente Nacional gera NSU do evento para o emitente.
6. Para manifestações diferentes de "desconhecimento da operação", o Ambiente Nacional gera NSU para o destinatário com a própria NF-e (liberando download).
7. Emitente consulta o WS e recupera o evento gerado pelo destinatário.
8. Destinatário consulta o WS e recupera a NF-e.
9. Emitente gera um evento de sua NF-e (ex: cancelamento).
10. Ambiente Nacional gera NSU para o destinatário do evento do emitente.
11. Destinatário consulta o WS e recupera o evento do emitente.
12. Eventos do fisco geram NSU para emitente e destinatário.
13. Ambos consultam o WS e recuperam o evento do fisco.

Este modelo permite ao emitente consultar eventos manifestados pelos destinatários e disponibiliza para o destinatário qualquer evento gerado pelo emitente. Eventos do fisco também são distribuídos para ambos. O processo simplifica o download da NF-e, pois a manifestação do destinatário gera automaticamente um NSU que permite a recuperação da NF-e pelo WS NFeDistribuicaoDFe.

Uso indevido e recomendações

O Ambiente Nacional mantém controles para identificar situações de "consumo indevido", como sucessivas tentativas de busca de registros já disponibilizados. Aplicações que entram em "loop" e consomem recursos de forma indevida são identificadas. Novas tentativas nessas condições são rejeitadas com o erro 656-Rejeição: Consumo Indevido.

Para evitar o uso indevido, as aplicações cliente devem gerenciar corretamente o último NSU recebido e a frequência das consultas, aguardando o tempo mínimo recomendado para novas solicitações.

Endereços do Web Service

Os endereços do Web Service de Distribuição do Ambiente Nacional estão publicados no Portal da NF-e (http://www.nfe.fazenda.gov.br/portal), no link "Serviços" / "Relação de Serviços Web". O mesmo se aplica ao ambiente de homologação (http://hom.nfe.fazenda.gov.br/portal).

Tabela de códigos de erros

O Web Service retorna códigos de erro para indicar o resultado do processamento da solicitação ou os motivos de não atendimento.

Resultado do processamento

• 108: Serviço Paralisado Momentaneamente (curto prazo).
• 109: Serviço Paralisado sem Previsão.
• 137: Nenhum documento localizado.
• 138: Documento localizado.

Motivos de não atendimento

• 214: Rejeição: Tamanho da mensagem excedeu o limite estabelecido.
• 215: Rejeição: Falha no schema XML.
• 238: Rejeição: Cabeçalho - Versão do arquivo XML superior à 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 da base de dados do Ambiente Nacional.
• 593: Rejeição: CNPJ-Base consultado difere do CNPJ-Base do Certificado Digital.
• 656: Rejeição: Consumo Indevido.

É recomendado que o campo xMotivo da mensagem de erro para o código 999 seja informado com a mensagem de erro do aplicativo ou do sistema que gerou a exceção não prevista.