Consulta de NF-e pela chave em números: o que milhares de consultas mostram

Em setembro de 2026 medimos as consultas por chave de acesso feitas no Gerador de Danfe. Quatro em cada cinco consultas de NF-e terminam com o documento entregue; as falhas se concentram em poucos motivos, quase todos evitáveis.

De onde vêm estes números

Os números deste artigo saem das consultas feitas no próprio Gerador de Danfe em setembro de 2026. Nenhum dado de nota foi lido para escrevê-lo: contamos tentativas, resultados e motivos de erro. A chave de acesso não é guardada no registro de falhas, só a UF e o modelo que ela indica.

Publicamos os números porque quase todo conteúdo sobre consulta de NF-e pela chave de acesso explica como a consulta deveria funcionar. Pouca gente mostra como ela funciona na prática, com as falhas que aparecem no dia a dia. Os números valem para o nosso serviço, no período medido, e não para a SEFAZ como um todo.

O volume: muita gente consulta a mesma nota

Em setembro foram 3.352 consultas por chave e 2.095 chaves diferentes. Ou seja, cerca de 37% das consultas pediam uma nota que alguém já tinha pedido antes.

Isso tem uma explicação simples. A mesma NF-e passa por várias mãos: o fornecedor que emitiu, o comprador que recebeu, o contador dos dois lados e a transportadora que levou a carga. Quando uma dessas pessoas consulta a nota, ela entra no nosso acervo, e a próxima consulta da mesma chave sai na hora.

• Mais da metade das entregas do mês saiu de nota que já estava no acervo.
• Nota repetida volta em segundos, sem nova ida ao portal.
• Quem recebe muita nota do mesmo fornecedor tende a cair nesse caso com frequência.

A taxa de sucesso: quatro em cada cinco

Numa amostra de dias úteis do começo de setembro, 80% das consultas de NF-e pela chave terminaram com o documento entregue. Os outros 20% foram chaves que não puderam ser localizadas.

Um detalhe sobre essa amostra. Na primeira leitura, a taxa parecia ser de 70%, porque falhas de envio de XML tinham entrado na mesma conta. Separadas as duas coisas, a taxa da consulta por chave é de 80%. Chave e XML são caminhos diferentes, com falhas diferentes, e misturar os dois esconde onde está o problema.

Quando a consulta não acha a nota, o caminho é o XML. O emissor é obrigado a gerar o XML autorizado, e com ele o DANFE sai completo. Veja como baixar o XML da nota fiscal e depois gere o DANFE pelo XML.

Por que a consulta falha

As falhas se concentram em poucos motivos.

O primeiro é a NFC-e, o cupom fiscal eletrônico do varejo, modelo 65. Em setembro, 85 chaves de NFC-e de 17 estados diferentes não puderam ser atendidas pela consulta por chave. O motivo é estrutural: a NFC-e é consultada pelo QR Code do cupom, no portal de cada estado, e não pelo mesmo caminho da NF-e. Quem tem o XML da NFC-e gera o DANFCE normalmente. Quem só tem a chave precisa do QR Code ou do XML.

O segundo motivo é a nota que existe mas não tem documento completo disponível. Nesse caso a consulta pública devolve só um resumo, e o DANFE sai com emitente, destinatário, valores e data corretos, mas sem os itens. Isso não é defeito: desde o Ajuste SINIEF 16/2018, a consulta pública divulga só o resumo da nota. O DANFE completo exige o XML.

O terceiro motivo é a chave errada. Um dígito trocado na digitação gera uma chave que não existe. O dígito verificador, o último da chave, pega a maior parte desses erros antes de qualquer consulta. Você pode conferir no validador de chave de NF-e, que decodifica a chave e confere o dígito sem enviar nada.

• NFC-e (modelo 65): use o QR Code do cupom ou o XML.
• Nota só com resumo: use o XML para ter os itens.
• Chave com dígito trocado: confira a chave antes de consultar.

Os erros de XML também têm padrão

Entre as tentativas de gerar DANFE pelo XML que falharam no período, os motivos se repetiram.

O mais comum foi o XML cortado. Ao copiar o XML de um e-mail ou de um sistema e colar no campo, parte do texto fica para trás, e o arquivo termina no meio de uma tag. O remédio é enviar o arquivo pelo botão de upload em vez de copiar e colar.

O segundo foi o arquivo que não é NF-e: um PDF, um XML de NFS-e, uma página HTML salva de portal ou a própria chave colada no campo de XML. Cada um desses casos agora recebe uma mensagem que diz o que veio e o que fazer, em vez de um erro técnico.

• Prefira o upload do arquivo .xml ao copiar e colar.
• O XML certo começa com a tag nfeProc ou NFe, não com %PDF nem com html.
• Para abrir e conferir o arquivo antes, veja como abrir o arquivo XML da NF-e.

Quanto tempo leva

Nota que já está no acervo volta em segundos. Quando a consulta precisa ir ao portal público, o tempo cresce bastante: a consulta ao portal de São Paulo costuma levar cerca de 20 segundos, porque passa por uma verificação anti-robô a cada pedido.

Por isso a tela mostra o progresso e, se a espera passar do limite, avisa em vez de ficar carregando. Se você consulta notas com frequência, o histórico da conta guarda o PDF e o XML de cada consulta, e a nota não precisa ser consultada de novo.

O que fazer com estes números

Se você só tem a chave, consulte. Quatro em cada cinco vezes o DANFE sai na hora. Se a consulta não achar a nota, ou devolver só o resumo, peça o XML ao emissor. É o documento fiscal de verdade e é o que você deve guardar, como explicamos em XML ou DANFE: qual guardar.

Para volume, como escritório de contabilidade, transportadora ou ERP, a API de DANFE faz o mesmo processamento sem passar pela tela.

Perguntas frequentes

Por que a mesma chave às vezes dá resultado e às vezes não? Uma nota recém-autorizada pode levar um tempo para ficar disponível nas consultas. Se a chave foi conferida e a nota é recente, vale tentar de novo mais tarde ou pedir o XML ao emissor.

A consulta por chave serve para NFC-e? Em geral, não. A NFC-e é consultada pelo QR Code do cupom, no portal do estado. Com o XML da NFC-e, o DANFCE é gerado normalmente pelo gerador de DANFE pelo XML.

Os números deste artigo vão mudar? Sim. São medidas de setembro de 2026 e serão atualizadas. A data de atualização aparece no topo da página.