NFeDistribuicaoDFe: Consulta de NF-e e Eventos Fiscais (NT 2014.002)

O projeto Nota Fiscal Eletrônica (NF-e) busca fornecer informações de interesse de forma eficiente e confiável aos atores envolvidos. O Web Service NFeDistribuicaoDFe foi criado para disponibilizar documentos fiscais eletrônicos (DF-e) e informações resumidas para emitentes, destinatários, transportadores e terceiros com interesse legítimo.

Histórico de alterações e cronograma da nota técnica

A Nota Técnica 2014.002, que regulamenta o Web Service NFeDistribuicaoDFe, passou por diversas atualizações desde sua versão inicial. Estas revisões visam aprimorar a distribuição de DF-e, incluir novos eventos e otimizar o acesso às informações. Por exemplo, a Nota Técnica 2014.002, v1.12 introduziu melhorias na documentação para esclarecer os tipos de consulta e as situações de uso indevido.

A evolução da nota técnica incluiu marcos como:

• Versão 1.02b: Inclusão da distribuição de eventos como Registro de Passagem, Pedido de Prorrogação/Cancelamento do prazo de suspensão do ICMS e outros eventos de Resposta do Fisco. Também permitiu a consulta por chave de acesso de NF-e e a distribuição do Evento de Cancelamento para o destinatário, mesmo sem manifestação.
• Versão 1.02c: Adição da distribuição dos Eventos de Averbação e do Evento de Comprovante de Entrega.
• Versão 1.10/1.11: Alteração na geração do Número Sequencial Único (NSU) para otimizar a distribuição de NF-e e eventos, além de incluir o evento de comprovante de entrega da NF-e previsto na NT 2021.001.
• Versão 1.13: Disponibilização de eventos do Fisco para emitente e destinatário, mesmo quando são iguais, conforme detalhado na Nota Técnica 2014.002, v1.13.
• Versão 1.14: Retorno do último NSU (ultNSU) na rejeição 656, que ocorre em casos de consumo indevido, auxiliando o usuário a retomar a consulta.
• Versão 1.15: O retorno de NSU tornou-se facultativo, modificando a necessidade de prévia geração de NSU para consultas por chave de acesso.
• Versão 1.20: Inclusão do evento 'Ator Interessado', expandindo as possibilidades de distribuição, conforme a Nota Técnica 2014.002, v1.20.

O web service NFeDistribuicaoDFe

O Web Service NFeDistribuicaoDFe tem a função de distribuir informações resumidas e documentos fiscais eletrônicos (DF-e) de interesse de um ator, seja pessoa física ou jurídica. Este serviço opera de forma síncrona, utilizando o método nfeDistDFeInteresse.

Para consumir este serviço, o ator da NF-e (Pessoa Jurídica ou Pessoa Física) deve possuir um certificado digital válido. No caso de Pessoa Jurídica, a autenticação ocorre pelo CNPJ base (os oito primeiros dígitos). É possível consultar documentos para qualquer CNPJ da empresa (os 14 dígitos), desde que o CNPJ base consultado seja o mesmo do certificado digital.

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

Documentos e informações acessíveis por ator

A distribuição de documentos e informações varia conforme o papel do interessado na NF-e. Os atores elegíveis incluem o emitente (grupo do Emitente), o destinatário (grupo do Destinatário), o transportador (grupo do Transportador) e terceiros (grupo de pessoas físicas autorizadas a acessar o XML). A tabela a seguir detalha quais documentos estão disponíveis para cada tipo de ator:

É importante notar algumas condições específicas:

• Para o destinatário: Os documentos fiscais e resumos de eventos são disponibilizados apenas após a manifestação ("Ciência da Operação", "Operação não Realizada" ou "Confirmação de Operação"), com exceção do Evento de Cancelamento, que é retornado sem a necessidade de manifestação. Antes da manifestação, apenas a estrutura XML de 'Resumo de NF-e' e o cancelamento de NF-e estão disponíveis.
• Para o transportador: A NF-e integral está disponível se o transportador for identificado no grupo do Transportador ou no evento 'Ator Interessado na NF-e' (código 110150).
• Para terceiros: A NF-e está disponível se o CNPJ ou CPF estiver informado no grupo de pessoas físicas autorizadas a acessar o XML.

Mensagem de retorno compactada

Para otimizar o uso da infraestrutura de rede, os documentos na mensagem de retorno do serviço NFeDistribuicaoDFe são compactados individualmente utilizando o padrão Gzip (GNU zip). Essa compactação pode reduzir o tamanho da mensagem em cerca de 60%, impactando positivamente o consumo de recursos. A aplicação cliente deve descompactar o documento para o tratamento normal.

Processo de distribuição de documentos fiscais eletrônicos

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

• Usuários ativos: A geração de NSU continua normalmente.
• Novos usuários: A geração de NSU inicia a partir do primeiro acesso, sem retroatividade.
• Usuários inativos: Se o serviço não for utilizado por mais de 60 dias, a geração de NSU é interrompida e retomada na próxima consulta, também sem retroatividade ao período de interrupção.

Nestes casos de primeiro acesso ou retomada após inatividade, a primeira consulta pode retornar cStat=137 (Nenhum documento localizado). Consultas subsequentes, após o período de espera para evitar uso indevido, podem então retornar documentos. A verificação da continuidade de uso é feita pelo CPF ou CNPJ base na requisição XML.

Antes da geração do NSU para transportadores e CNPJs no grupo de pessoas físicas autorizadas a acessar o XML, é verificado se eles 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.

Tipos de consulta no web service

O XML do pedido de distribuição suporta três tipos de consultas, definidas pela tag utilizada na requisição: distNSU, consNSU e consChNFe.

Consulta distNSU: distribuição de conjunto de DF-e a partir do NSU informado

Neste tipo de consulta, a aplicação cliente informa o último NSU que possui (ultNSU). O Ambiente Nacional retorna todos os documentos (NF-e e eventos) disponíveis para o interessado a partir desse NSU. Se o NSU informado for menor que o primeiro NSU disponível, o sistema fornecerá os documentos mais antigos cujas NF-es e eventos foram autorizados há menos de 90 dias.

A criação do lote de documentos segue regras específicas:

• Ordem crescente de NSU.
• O lote pode conter qualquer tipo de documento válido e seu respectivo NSU.
• Quantidade máxima de 50 documentos por lote.

Os documentos (NF-e e eventos) são disponibilizados de acordo com o papel do interessado na NF-e. É fundamental que o processo de recepção e sincronização não seja realizado em ordem cronológica de emissão, mas sim de receção pelo Ambiente Nacional, pois a geração do NSU é organizada por essa ordem. É recomendável manter um controle do primeiro NSU válido para futuras consultas.

As possíveis respostas do Web Service incluem:

• Rejeição: Mensagem com o motivo da falha (cStat).
• Nenhum documento localizado: (cStat=137), indicando que não há documentos para o CNPJ/CPF informado.
• Documento(s) localizado(s): (cStat=138), com os documentos fiscais encontrados.

Se o retorno for cStat=137, a empresa deve aguardar um tempo mínimo de uma hora antes de fazer uma nova solicitação para evitar uso indevido. Se o NSU informado (ultNSU) for igual ao maior NSU do Ambiente Nacional (maxNSU), isso significa que não há mais documentos a serem pesquisados naquele momento.

Consulta consNSU: consulta DF-e vinculado ao NSU informado

Esta consulta permite que o interessado verifique pontualmente um NSU específico que tenha sido identificado como faltante em sua base de dados. O Ambiente Nacional, que gera NSU sem lacunas, fornece aqui um único documento fiscal (NF-e ou evento) referente ao NSU informado na requisição.

Assim como outras consultas, esta também está disponível para documentos recebidos nos últimos 90 dias. Após esse período, a NF-e não poderá ser recuperada.

As respostas podem ser:

• Rejeição: Mensagem com o motivo da falha.
• Nenhum documento localizado: (cStat=137), indicando que o NSU não foi gerado.
• Documento localizado: (cStat=138), com o documento fiscal encontrado.

Consulta consChNFe: consulta de NF-e por chave de acesso informada

Este processo permite consultar uma NF-e específica a partir de sua chave de acesso. A chave de acesso deve ser válida, existir no Ambiente Nacional e estar vinculada ao interessado como destinatário, transportador ou terceiro. O sistema retorna apenas a NF-e (não eventos) referente à chave informada.

A partir da versão 1.15 da Nota Técnica 2014.002, a consulta por chave de acesso não exige mais uma prévia geração de NSU para o documento fiscal. O período de disponibilidade para esta consulta é de 90 dias após a recepção do documento pelo Ambiente Nacional.

As respostas possíveis incluem:

• Rejeição: Com o motivo da falha.
• Nenhum documento localizado: (cStat=137), se a NF-e não for encontrada ou não estiver vinculada ao interessado.
• Documento localizado: (cStat=138), com o documento fiscal retornado.

Envio das informações e autenticação

O pedido de distribuição é enviado via Web Service, exigindo o uso de um certificado digital (PJ ou PF) válido. O Web Service do Ambiente Nacional é acionado pela aplicação cliente, que deve enviar uma mensagem XML seguindo os padrões do manual.

Validação de mensagens e regras de negócio

Para garantir a integridade e a segurança do processo, o Web Service NFeDistribuicaoDFe realiza diversas validações.

Validação do certificado de transmissão

O certificado digital utilizado para a transmissão da mensagem é validado quanto à sua validade, cadeia de certificação (ICP-Brasil), lista de certificados revogados (LCR) e se possui as extensões de CNPJ ou CPF apropriadas. As falhas nessa etapa resultam em rejeição da requisição.

Validação inicial da mensagem no web service

O sistema verifica o tamanho do XML de dados, que não deve exceder 10 KB. Mensagens maiores podem ser descartadas sem retorno de erro, dependendo da implementação do controle de tamanho. Também são verificadas as condições de funcionamento do servidor de processamento (paralisado momentaneamente ou sem previsão).

Validação da área de dados e regras de negócio

Após a validação inicial, são aplicadas verificações sobre o formato do XML (schema, uso de prefixo no namespace, codificação UTF-8) e regras de negócio:

• Ambiente da NF-e: Deve coincidir com o ambiente do Web Service.
• CNPJ/CPF do interessado: Deve ser válido.
• Certificado Digital: O CNPJ base ou CPF do certificado deve corresponder ao CNPJ/CPF consultado.
• NSU informado: Não deve ser superior ao maior NSU disponível para consulta.
• Chave de Acesso: Validação do dígito verificador, código da UF, ano, mês, CNPJ, modelo (deve ser 55), número da NF.
• Prazo de download: A NF-e deve estar no prazo de 90 dias da data de recebimento no Ambiente Nacional.
• Permissão de consulta: O interessado deve ter permissão para consultar a NF-e, e a NF-e não deve ser disponibilizada para o próprio emitente.
• Situação da NF-e: NF-e Cancelada ou Denegada resultam em arquivo indisponível para download.

Leiautes resumidos de NF-e e eventos

Para permitir o compartilhamento de informações relevantes sem expor todos os detalhes da NF-e, o Ambiente Nacional gera leiautes resumidos.

Leiaute resumo da NF-e

Este é um XML com um conjunto de informações resumidas da NF-e, gerado quando a NF-e é autorizada ou denegada. Ele é distribuído aos destinatários para que possam realizar a manifestação da operação. Contém dados como:

• Chave de acesso da NF-e
• CNPJ ou CPF do emitente e sua razão social ou nome
• Inscrição Estadual (IE) do emitente
• Data de emissão, tipo de operação
• Valor total da NF-e
• Digest Value da NF-e
• Data de autorização e número de protocolo
• Situação da NF-e: Uso autorizado, uso denegado ou NF-e cancelada.

Leiaute resumo do evento de NF-e

Similarmente, este XML contém informações resumidas de um evento de NF-e, como:

• Código do órgão de recepção do evento (91 para Ambiente Nacional)
• CNPJ ou CPF do emitente
• Chave de acesso da NF-e
• Data e hora do evento
• Código e número sequencial do evento
• Descrição do evento
• Data de autorização e número de protocolo

Visão geral do modelo de distribuição

O modelo de distribuição baseia-se na geração de um NSU para cada CNPJ ou CPF. O fluxo abaixo ilustra o processo:

1. O emitente gera e transmite uma NF-e, que será 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 para consulta.
3. O destinatário consulta o Web Service NFeDistribuicaoDFe usando o último NSU recebido e recupera o resumo.
4. Com o resumo, o destinatário pode gerar um evento de manifestação de destinatário.
5. O Ambiente Nacional gera um NSU para o emitente sobre o evento gerado pelo destinatário.
6. Caso seja um evento de manifestação de destinatário diferente do tipo 'desconhecimento da operação', o Ambiente Nacional gera um NSU para o destinatário com a NF-e completa, liberando o download.
7. O emitente consulta o Web Service e recupera o evento gerado pelo destinatário.
8. O destinatário consulta o Web Service e recupera a NF-e.
9. O emitente pode gerar um evento de sua NF-e (ex.: evento de cancelamento), que será compartilhado pela Sefaz com o Ambiente Nacional.
10. O Ambiente Nacional gera um NSU para o destinatário sobre o evento gerado pelo emitente.
11. O destinatário consulta o Web Service e recupera o evento gerado pelo emitente.
12. O Ambiente Nacional recebe um evento gerado pelo fisco e gera um NSU para o emitente e outro NSU para o destinatário, disponibilizando-os para consulta.
13. Tanto o emitente quanto o destinatário consultam o Web Service NFeDistribuicaoDFe usando o último NSU recebido e recuperam o evento gerado pelo fisco.

Este modelo permite ao emitente consultar eventos manifestados pelos destinatários e ao destinatário acessar eventos gerados pelo emitente. Eventos do fisco são acessíveis por ambos. A simplificação no download da NF-e ocorre com a manifestação do destinatário, que dispara a geração de um NSU para a NF-e completa.

Recomendações para evitar o uso indevido

O Ambiente Nacional monitora o uso do Web Service NFeDistribuicaoDFe para identificar padrões de "uso indevido", como consultas excessivas que sobrecarregam os recursos. As tentativas de busca de registros já disponibilizados, especialmente com a consulta distNSU, podem ser rejeitadas com o erro 656-Rejeição: Consumo Indevido.

Uso indevido na consulta distNSU

Duas situações são consideradas uso indevido para a consulta distNSU:

1. Consulta contínua sem novos documentos: Se o sistema retornar cStat=137 (Nenhum documento localizado), o usuário deve aguardar uma hora antes de fazer nova consulta. Consultas realizadas antes desse período resultarão em uso indevido e bloqueio do CNPJ por uma hora. O motivo é descrito como 'Rejeição: Consumo Indevido. Deve ser aguardado 1 hora para efetuar nova solicitação caso não existam mais documentos a serem pesquisados. Tente apos 1 hora'.
2. Não utilização do NSU sequencial: O usuário deve sempre basear a consulta no ultNSU retornado na consulta anterior. O ultNSU indica o ponto de onde a leitura dos blocos de documentos deve continuar. Se ultNSU for igual a maxNSU, não há mais documentos. Consultas fora da sequência geram bloqueio por uma hora, com a mensagem 'Rejeição: Consumo Indevido. Deve ser utilizado o ultNSU nas solicitacoes subsequentes. Tente apos 1 hora'.

Se múltiplas aplicações do mesmo ator (emitente, destinatário, transportador ou pessoa física ou jurídica autorizada a acessar o XML) realizarem consultas por NSU para o mesmo CNPJ (14 dígitos) sem seguir a mesma sequência ordenada e ascendente, isso também será enquadrado como uso indevido. O retorno do último NSU na rejeição 656 ajuda a retomar a sequência correta.

Uso indevido nas consultas consChNFe e consNSU

Estas consultas são projetadas para buscas pontuais de NF-e ou NSU em um período retroativo de até 90 dias. Para download de múltiplos documentos dentro desse limite, a consulta distNSU é a recomendada.

• Limite de consultas por hora: Existe um limite de consultas por chave de acesso ou NSU em um período de 1 hora (20 consultas). Exceder esse limite resulta em 656 - Consumo indevido e bloqueio do CNPJ por uma hora.

Em qualquer tipo de consulta, se o erro 656 - Consumo indevido for recebido, o usuário deve aguardar uma hora. Retomar a consulta antes do fim desse período reinicia a contagem do tempo de bloqueio.

Endereços do web service

Os endereços dos Web Services de distribuição do Ambiente Nacional estão publicados nos portais oficiais:

• Portal Nacional da NF-e: http://www.nfe.fazenda.gov.br/portal
• Portal de Homologação: http://hom.nfe.fazenda.gov.br/portal

Eles podem ser encontrados no menu 'Serviços' / 'Relação de Servicos Web'.

Tabela de códigos e descrições de erros

O serviço de distribuição retorna códigos de status (cStat) e mensagens de motivo (xMotivo) para indicar o resultado do processamento da solicitação. Estes códigos são essenciais para o diagnóstico e tratamento de eventuais falhas.

Exemplos práticos de requisições e retornos

Os exemplos de XML fornecidos na Nota Técnica ilustram como as requisições ao Web Service NFeDistribuicaoDFe são estruturadas e quais são os possíveis retornos. Estes exemplos são fundamentais para o desenvolvimento de aplicações que interagem com o serviço.

Requisição com distNSU

A requisição para distribuição de um conjunto de DF-e a partir de um NSU específico (distNSU) é enviada em ambiente de homologação, informando o CNPJ do interessado e o último NSU conhecido.

<distDFeInt xmlns="http://www.portalfiscal.inf.br/nfe" versao="1.01">
    <tpAmb>2</tpAmb>
    <cUFAutor>29</cUFAutor>
    <CNPJ>99999999999999</CNPJ>
    <distNSU>
        <ultNSU>000000000000001</ultNSU>
    </distNSU>
</distDFeInt>

Neste exemplo, o valor 2 em tpAmb indica o ambiente de homologação, cUFAutor é o código da UF do autor, e o CNPJ identifica o interessado. O ultNSU indica a partir de qual Número Sequencial Único os documentos devem ser buscados.

Requisição com consNSU

Para consultar um DF-e pontual por seu NSU (consNSU) em ambiente de produção:

<distDFeInt xmlns="http://www.portalfiscal.inf.br/nfe" versao="1.01">
    <tpAmb>1</tpAmb>
    <cUFAutor>29</cUFAutor>
    <CNPJ>99999999999999</CNPJ>
    <consNSU>
        <NSU>000000000000001</NSU>
    </consNSU>
</distDFeInt>

Aqui, o valor 1 em tpAmb é para ambiente de produção, e o NSU específico a ser consultado é fornecido diretamente.

Requisição com consChNFe

A consulta de uma NF-e pela chave de acesso (consChNFe) em ambiente de produção é realizada da seguinte forma:

<distDFeInt xmlns="http://www.portalfiscal.inf.br/nfe" versao="1.01">
    <tpAmb>1</tpAmb>
    <cUFAutor>29</cUFAutor>
    <CNPJ>99999999999999</CNPJ>
    <consChNFe>
        <chNFe>35220499999999999999550010020000001240556603</chNFe>
    </consChNFe>
</distDFeInt>

O campo chNFe contém a chave de acesso da NF-e que se deseja consultar de forma pontual.

Exemplos de retornos do web service

Os retornos do Web Service indicam o status da consulta.

• Rejeição (cStat=589): Sinaliza uma falha na consulta, como quando o NSU informado é superior ao maior NSU disponível na base de dados do Ambiente Nacional.
• Nenhum documento localizado (cStat=137): Indica que não há documentos a serem disponibilizados para a consulta atual, seja por já terem sido obtidos ou por não existirem.
• Documento(s) localizado(s) (cStat=138): Retorna os documentos encontrados, compactados em formato Gzip no campo docZip, juntamente com o NSU e o esquema XML (schema) do documento, que identifica seu tipo e versão.

Conclusão

O Web Service NFeDistribuicaoDFe é um componente para a gestão fiscal, permitindo que os diversos atores da NF-e acessem documentos e eventos de seu interesse de forma padronizada. Compreender os tipos de consulta, as regras de geração e uso do NSU e as validações é fundamental para utilizar o serviço corretamente e evitar bloqueios por uso indevido. As atualizações da Nota Técnica 2014.002 demonstram o compromisso em aprimorar a distribuição de informações, facilitando o cumprimento das obrigações fiscais e o acompanhamento das operações.