O que é a Validação e Consulta de NF-e
Toda NF-e (Nota Fiscal Eletrônica), ao ser emitida, recebe da SEFAZ uma chave de acesso de 44 dígitos única, no formato 35200114200166000187550010000000071123456789. Essa sequência codifica o CNPJ do emitente, o número da nota, a data de emissão, o modelo e outras informações, e funciona como o "documento de identidade global" da NF-e.
A API de Validação de NF-e permite que você, com essa chave de 44 dígitos, consulte a SEFAZ em tempo real: a nota é verdadeira ou falsa? Foi cancelada? Quem é o emitente? Quais são os produtos? Qual o valor? Qual o histórico de eventos? — tudo em até 5 segundos.
Por que você precisa validar a NF-e
A NF-e brasileira foi projetada para ser pública e verificável, mas apenas uma interface profissional permite fazer a validação em lote e de forma automatizada. O "custo de confiança" dos cenários a seguir define se você precisa dessa API:
- Conferência de recebimento (a mais comum): o fornecedor envia a NF-e junto com a mercadoria, e você precisa confirmar que a nota é verdadeira, confere com a mercadoria e com o valor antes de receber e dar entrada no estoque
- Conciliação financeira: no fechamento do mês, valide se todas as NF-e lançadas são verdadeiras e válidas, evitando notas falsas na contabilidade
- Fiscalização e prevenção de fraude: valide de forma proativa em auditorias internas, externas e fiscais, descobrindo problemas antes do Fisco
- Antifraude: identifique "NF-e adulteradas", "NF-e canceladas se passando por válidas" e "números de NF-e clonados"
- Atendimento ao cliente: se o cliente questionar o conteúdo da nota, você consegue puxar imediatamente a versão oficial para comparar
- Desembaraço aduaneiro transfronteiriço: o despachante aduaneiro precisa validar a autenticidade da NF-e antes de liberar
- Factoring / crédito financeiro: antes de financiar tendo a nota como garantia, é preciso validar que ela realmente existe
Principais recursos da API de Validação de NF-e da TF Fiscal
1. Consulta completa pela chave de 44 dígitos
Informe a chave de acesso, chame GET /v1/consulta/nfe/{chave} e receba em segundos:
- Situação de autorização: Autorizada / Cancelada / Denegada / Inexistente
- Emitente: CNPJ, Razão Social, Inscrição Estadual, endereço
- Destinatário: CNPJ ou CPF, nome, endereço
- Itens: por linha, o NCM, CFOP, quantidade, preço unitário, valor total e os impostos
- Resumo de impostos: total de ICMS, IPI, PIS, COFINS e valor total com impostos
- Data e número da nota, número de autorização da SEFAZ (protocolo), data e hora da autorização
- Histórico de eventos: todas as Cartas de Correção, cancelamentos e eventos de Manifestação de recebimento
2. Dois modos de retorno: resumido / completo
Versão resumida (Resumo): retorna apenas a situação de autenticidade + dados principais de emitente e destinatário + valor total. Resposta rápida e preço baixo, ideal para o cenário "só quero saber se a nota é verdadeira".
Versão completa (Completo): retorna todos os campos do XML completo da NF-e já interpretados, incluindo os itens e o histórico de eventos. Ideal para arquivamento, conciliação e validação aprofundada.
3. Decodificação e validação por QR Code
A DANFE da NF-e tem um QR Code. Escaneie com o celular ou envie a imagem, e a TF Fiscal decodifica automaticamente a chave de 44 dígitos e faz a validação, dispensando a digitação manual da longa sequência de 44 dígitos.
4. Validação em lote
Envie de uma vez uma lista de 100 a 1000 chaves e receba todos os resultados de forma assíncrona. Adequado tanto para a conciliação de fechamento de mês quanto para fiscalizações periódicas.
5. SEFAZ em tempo real + cache inteligente
Para cenários de "baixa sensibilidade", o cache padrão é de 24 horas (os dados de uma NF-e autorizada praticamente não mudam), economizando custos de chamada. Para cenários de "alta sensibilidade" (como financiamentos), é possível forçar a consulta em tempo real.
6. Alertas proativos de situações anômalas
Se você assinar o monitoramento de determinadas NF-e prioritárias, a TF Fiscal acompanha a situação delas continuamente. Ao detectar um "cancelamento", uma "rejeição" ou o surgimento de uma "Carta de Correção", um alerta é enviado imediatamente por Webhook, evitando que você conduza o negócio com base em uma nota já inválida.
Cenários de uso típicos
- Conferência de recebimento no WMS do armazém: escaneie o QR Code da NF-e que acompanha a carga, valide automaticamente + compare com a mercadoria → só dá entrada se aprovado
- Conciliação financeira mensal: valide em lote todas as NF-e lançadas no mês, sinalizando automaticamente as "canceladas" ou com "valor divergente"
- Controle de risco no e-commerce: valide a autenticidade quando o cliente enviar uma NF-e para solicitar reembolso / pós-venda
- Desembaraço na logística transfronteiriça: antes do despacho, valide que a NF-e de saída está em situação válida
- Factoring financeiro: antes de conceder o crédito tendo a NF-e como garantia, valide que a nota realmente existe
- Autofiscalização: na auditoria interna de fim de ano, valide em lote a situação de todas as NF-e emitidas no ano
Perguntas frequentes
P: Não tenho a chave de 44 dígitos, só o número da nota. E agora?
A TF Fiscal oferece uma interface de consulta combinada por "número da nota + CNPJ do emitente + modelo + série", montando a chave de acesso a partir desses campos para depois fazer a consulta.
P: Posso consultar NF-e emitidas por outras empresas (que não fui eu que emiti)?
Pode. A interface de validação de NF-e é uma API pública (qualquer pessoa pode validar) e não se limita às notas que você mesmo emitiu. É justamente por isso que a SEFAZ imprime o QR Code em cada DANFE — qualquer um pode escanear e validar.
P: Qual a diferença em relação à página de validação do site oficial?
O site oficial (Portal Nacional da NF-e) só permite a consulta manual, uma a uma, e tem limite por IP. A TF Fiscal disponibiliza uma API por canal autorizado, com suporte a lote, automação e cache.
P: Qual o tempo de resposta?
A versão resumida leva em média 800ms (cache atendido em < 100ms) e a completa, em média 2 a 3 segundos. No modo em lote assíncrono, a vazão total é de mais de 50 TPS.
P: O que significa uma NF-e "Cancelada"? Ela foi invalidada?
Sim. Cancelada significa que o emitente cancelou a nota junto à SEFAZ dentro de 24 horas. Essa NF-e deixa de ter validade legal. Uma NF-e com situação Cancelada deve ter o lançamento recusado.
Soluções relacionadas