Como consultar documentos da NF-e pela Distribuição DF-e usando NSU

Este serviço está disponível na rota de NF-e. A API não possui uma rota NFCe/Distribuicao.

Pré-requisitos

Antes de iniciar, tenha:

• Token de acesso válido;
• Certificado digital válido para o ator que fará a consulta;
• CPF ou CNPJ do ator consultado;
• Código da UF autora informado em cUFAutor;
• Controle local do último NSU processado, quando utilizar a sincronização contínua.

Endpoint

POST /api/v1/{CPF_CNPJ}/NFe/Distribuicao

Envie o XML distDFeInt no corpo da requisição, com Content-Type: application/xml.

Authorization: Bearer {seu_token}
Content-Type: application/xml

A API aceita XML distDFeInt nas versões 1.35 e 1.01. Para novas integrações, utilize a versão mais atual aceita pela sua operação.

Escolha o tipo de consulta

Envie somente um dos grupos de consulta em cada XML: distNSU, consNSU ou consChNFe.

1. Sincronizar documentos novos por NSU

Use distNSU para buscar todos os documentos disponibilizados após o último NSU processado.

<?xml version="1.0" encoding="utf-8"?>
<distDFeInt versao="1.35" xmlns="http://www.portalfiscal.inf.br/nfe">
  <tpAmb>2</tpAmb>
  <cUFAutor>41</cUFAutor>
  <CNPJ>12345678000199</CNPJ>
  <distNSU>
    <ultNSU>000000000000000</ultNSU>
  </distNSU>
</distDFeInt>

Substitua ultNSU pelo último NSU efetivamente processado e armazenado pela sua aplicação. Na primeira execução, utilize 000000000000000.

Ao receber a resposta, processe os documentos retornados e grave o novo ultNSU. Repita a consulta até que o ultNSU retornado alcance o maxNSU retornado pelo serviço.

Consulta por CPF

Quando o ator for pessoa física, use CPF no lugar de CNPJ:

<distDFeInt versao="1.35" xmlns="http://www.portalfiscal.inf.br/nfe">
  <tpAmb>2</tpAmb>
  <cUFAutor>41</cUFAutor>
  <CPF>12345678901</CPF>
  <distNSU>
    <ultNSU>000000000000000</ultNSU>
  </distNSU>
</distDFeInt>

2. Consultar um NSU específico

Use consNSU quando a sua aplicação já conhece o NSU que deseja recuperar:

<?xml version="1.0" encoding="utf-8"?>
<distDFeInt versao="1.35" xmlns="http://www.portalfiscal.inf.br/nfe">
  <tpAmb>2</tpAmb>
  <cUFAutor>41</cUFAutor>
  <CNPJ>12345678000199</CNPJ>
  <consNSU>
    <NSU>000000000000123</NSU>
  </consNSU>
</distDFeInt>

3. Consultar pela chave de acesso da NF-e

Use consChNFe quando você possui a chave de acesso de 44 dígitos:

<?xml version="1.0" encoding="utf-8"?>
<distDFeInt versao="1.35" xmlns="http://www.portalfiscal.inf.br/nfe">
  <tpAmb>2</tpAmb>
  <cUFAutor>41</cUFAutor>
  <CNPJ>12345678000199</CNPJ>
  <consChNFe>
    <chNFe>41260112345678000199550010000000011000000010</chNFe>
  </consChNFe>
</distDFeInt>

Como tratar o retorno

A resposta é o XML retDistDFeInt do Ambiente Nacional. Ao processá-la:

• Verifique o código e a mensagem de retorno antes de considerar a consulta concluída;
• Armazene ultNSU e maxNSU retornados no fluxo distNSU;
• Processe cada docZip retornado;
• Decodifique e descompacte o conteúdo de docZip antes de identificar o XML distribuído;
• Guarde o XML recuperado e a chave/NSU correspondente para evitar processamento duplicado.

Os documentos distribuídos podem incluir resumos de NF-e, XMLs completos liberados ao ator e eventos vinculados à NF-e.

Boas práticas para a sincronização

• Execute a rotina por distNSU de forma recorrente e persista o último NSU processado;
• Não avance o NSU local antes de processar os documentos recebidos com sucesso;
• Não use a distribuição como consulta repetitiva de status de uma NF-e recém-emitida;
• Evite chamadas em sequência quando a resposta não trouxer novos documentos;
• Mantenha a rotina ativa: a geração de novos NSUs depende do uso contínuo do serviço pelo ator consultado.

O Ambiente Nacional não gera NSUs retroativos para períodos em que o ator ficou inativo no serviço. Consulte a documentação oficial para as regras de disponibilidade, frequência e uso indevido.

Erros comuns

Referências

• Web Service NFeDistribuicaoDFe — Portal da NF-e
• Regras de distribuição, NSU e consultas — Portal da NF-e