Verificação de NF-e

Verificar XML

Envia o XML da NF-e; devolve o veredito de nível 1 e os dados da nota e inicia a verificação na SEFAZ.

POST/openapi/v3/consultas/nf-e/xml

Requer os cabeçalhos de assinatura token, timestamp e sign, veja Autenticação.

Envia o XML bruto da NF-e. Devolve de forma síncrona o veredito de nível 1 e os dados da nota já interpretados; se o nível 1 for aprovado, a verificação de nível 2 na SEFAZ começa automaticamente e o veredito final chega pelo webhook invoice.verify.completed (veja Verificação de NF-e).

HTTP 200 significa que a requisição foi aceita, não que a nota foi aprovada. Um XML bem formado que reprova na validação também devolve 200; o veredito está no bloco validation. Nunca decida a validade pelo status HTTP.

Parâmetros

Cabeçalhos

Content-Typestringobrigatório
application/xml ou text/xml.
forceRevalidatebooleanopcional
Opcional, padrão false. Envie true para forçar uma nova verificação mesmo existindo um veredito terminal reutilizável. Não participa da assinatura. Veja Idempotência e nova verificação abaixo.

Respostas

200

Requisição aceita. Dados da nota interpretados mais o bloco validation com o veredito de nível 1. Inclui os casos em que a validação reprovou: verifique validation.validationStatus e validation.errors.

tipostring
Tipo do documento.
Valores:NF-eNFC-e
modelostring
Modelo do documento.
Valores:5565
statusstring
Situação fiscal na SEFAZ.
Valores:AutorizadaCanceladaDenegadaInutilizadaNaoEncontradaDesconhecida
statusDescriptionstring
Descrição localizada de status, conforme o idioma da requisição (veja Localização das respostas em Verificação de NF-e).
ambienteEmissaostring
Ambiente em que o documento foi emitido.
Valores:ProducaoHomologacao
numerostring
Número da nota nNF, sem zeros à esquerda.
seriestring
Número da série.
dataEmissaostring
Data e hora de emissão dhEmi, ISO-8601 com deslocamento UTC, tal como no documento (ex.: 2026-07-23T11:20:05-03:00).
chaveAcessostring
Chave de acesso de 44 dígitos.
emitenteobject
Emitente.
destinatarioobject
Destinatário.
itensarray
Itens da nota.
dataAutorizacaostring | null
Data e hora de autorização na SEFAZ dhRecbto (ISO-8601); nulo quando o XML enviado não traz nó de protocolo.
protocoloobject | null
Protocolo de autorização; nulo quando não há nó de protocolo.
valorTotalnumber
Valor líquido total da nota vNF (após descontos), 2 casas decimais.
validationobject
Bloco do veredito de nível 1. Presente apenas neste endpoint.

Erros

Código	HTTP
10015000	400	Corpo da requisição vazio. Envie o XML no corpo.
10015001	400	Corpo maior que 1 MB. Uma NF-e autêntica nunca ultrapassa esse limite; verifique se não está encapsulando ou codificando duas vezes.
10015002	400	DTD detectado (`<!DOCTYPE`). Remova DTDs; são rejeitados como proteção contra XXE.
10015003	400	Codificação diferente de UTF-8. Converta para UTF-8 antes de enviar.

Corpo da requisição e assinatura

Preferível: o documento autorizado nfeProc completo (incluindo o nó de protocolo protNFe). Uma NFe sem o nó de protocolo também é aceita: gera um aviso, mas é processada normalmente.
Limites rígidos: máximo de 1 MB, somente UTF-8, DTD proibido (qualquer <!DOCTYPE é rejeitado de imediato).
Assinatura: o corpo entra na assinatura depois de remover todos os CR e LF, enquanto o corpo enviado permanece inalterado:

text

sign = md5Hex(app_secret + "/openapi/v3/consultas/nf-e/xml" + xmlSemCrLf + timestamp)

O cabeçalho forceRevalidate não participa da assinatura. Veja as regras completas em Autenticação.

Semântica dos valores

O itens[].valorTotal de cada linha é o valor bruto da linha (vProd, antes do desconto); o valorTotal da raiz é o total líquido da nota (vNF, após desconto). A diferença é o desconto total.

Erros de validação de nível 1

Devolvidos com HTTP 200 dentro de validation.errors[]. Não são erros de transporte: a requisição teve êxito, o documento reprovou. Todos são bloqueantes (REJECTED terminal), exceto PROTOCOL_MISSING, que é um aviso.

errors[].code	Código numérico	Significado
`XML_MALFORMED`	10015100	Sintaxe XML inválida
`XSD_INVALID`	10015101	Não conforme ao layout XSD da NF-e 4.00
`SIGNATURE_INVALID`	10015102	Falha na verificação da assinatura digital (conteúdo adulterado ou certificado vencido no momento da assinatura)
`SIGNATURE_CERT_MISMATCH`	10015103	O CNPJ do certificado de assinatura não corresponde ao emitente
`ACCESS_KEY_INVALID`	10015104	Estrutura ou dígito verificador da chave inválidos
`ACCESS_KEY_MISMATCH`	10015105	Os segmentos da chave não correspondem aos campos do documento
`PROTOCOL_MISMATCH`	10015106	Bloco de protocolo incoerente com o documento
`PROTOCOL_MISSING`	10015107	Sem nó de protocolo (aviso, não bloqueante)
`XML_VERSION_UNSUPPORTED`	10015108	Versão do layout diferente de 4.00

Resultados de nível 2 (webhook)

Quando o nível 1 é aprovado, o veredito final chega somente pelo webhook invoice.verify.completed; cabeçalhos, carga e requisitos do receptor estão em Verificação de NF-e. Não são erros HTTP.

validationStatus	Terminal?	Ação
`VALIDATED`	Sim	Seguro prosseguir (liberar mercadoria, liquidar etc.)
`REJECTED`	Sim	Não prosseguir; `reason` explica o veredito da SEFAZ (cancelada / denegada / inutilizada / não encontrada / protocolo divergente)
`VALIDATION_ERROR`	Não	Falha de verificação do lado da plataforma, não é um juízo sobre a nota; reenvie mais tarde com `forceRevalidate: true`

Idempotência e nova verificação

A verificação de XML é idempotente pela chave: reenviar enquanto uma verificação está em andamento devolve o progresso atual; vereditos terminais são reutilizados por 24 horas (sem custo de verificação duplicado).
Nova verificação forçada: envie o cabeçalho forceRevalidate: true (não faz parte da assinatura). A consulta por chave tem forma GET fixa e não possui canal de nova verificação; para forçar uma nova checagem, reenvie por este endpoint.
Um REJECTED bloqueante de nível 1 não tem registro de nível 2; a nova verificação exige reenviar o XML.