Verificação de NF-e
Consultar por chave
Devolve os dados da nota para uma chave de acesso de 44 dígitos e, se você enviou a chave para verificação, o veredito atual.
/openapi/v3/consultas/nf-e/{chave}token, timestamp e sign, veja Autenticação.Devolve os dados da nota para uma chave de acesso de 44 dígitos. Para uma chave enviada pela verificação de XML, a resposta também traz o bloco validation com o validationStatus atual: use-o como alternativa de polling quando uma entrega do webhook invoice.verify.completed se perder (veja Verificação de NF-e). Notas encontradas só na emissão da plataforma ou na fonte oficial não foram verificadas e vêm sem esse bloco.
Parâmetros de caminho
chave* | string | Chave de acesso |
* Campo obrigatório
validation só vem para chaves enviadas por lá.tipo | string | Tipo de documento |
modelo | string | Modelo do documento |
status | string | Situação fiscal |
statusDescription | string | Descrição do status |
ambienteEmissao | string | Ambiente de emissão |
numero | string | Número da nota |
serie | string | Série |
dataEmissao | string | Data de emissão |
tipoOperacao | string | Tipo de operação (tpNF), o sentido da mercadoria visto pelo emitente |
chaveAcesso | string | Chave de acesso |
| object | Emitente |
| object | Destinatário |
| array | Itens |
dataAutorizacao | string | Data de autorização |
| object | Protocolo de autorização |
valorTotal | number | Valor líquido da nota |
| object | Veredito atual da verificação |
Com app_secret = sk_live_9f8e7d6c5b4a, a chave 35260764962869000108550990001366171195929648 e timestamp = 1784906308, a string assinada é (GET, corpo vazio; a chave está no caminho):
sign_input = "sk_live_9f8e7d6c5b4a"+ "/openapi/v3/consultas/nf-e/35260764962869000108550990001366171195929648"+ ""+ "1784906308"sign = md5Hex(sign_input)
A plataforma resolve a chave pelos níveis abaixo, nesta ordem; o primeiro acerto é devolvido.
Já enviada para verificação
A plataforma mantém o registro da verificação de XML e devolve os dados completos da nota mais o bloco validation com o validationStatus atual.
Nota emitida por esta plataforma
Dados completos interpretados do XML autorizado, sem bloco validation.
Chave desconhecida
Dados autorizados completos obtidos da fonte oficial, conforme a política da plataforma, sem bloco validation.
Nenhuma fonte com acerto
HTTP 400 com 10015004. Uma chave malformada devolve 10015104 sem consultar nenhuma fonte.
{ "code": 10015004, "message": "Invoice not found: 35260764962869000108550990001366171195929648" }
- Alternativa de polling: para uma chave enviada pela verificação de XML, o bloco
validationtraz ovalidationStatusatual (PENDING_SEFAZ,VALIDATINGou o veredito final). Use-o quando uma entrega do webhookinvoice.verify.completedse perder. - Rechecagem em segundo plano: quando a última resposta da SEFAZ para essa chave tem mais de 24 horas, a consulta agenda uma nova verificação de nível 2 (exceto notas já
Cancelada,DenegadaouInutilizada, cuja situação não muda mais). Essa resposta já mostravalidationStatus=VALIDATINGe o novo veredito chega pelo webhook como um novo evento. - Sem nova verificação forçada: este endpoint não força rechecagem. Para isso, reenvie o XML pela verificação de XML com o cabeçalho
forceRevalidate: true.
tipoTipo de documento
| Valores | Significado |
|---|---|
| NF-e | Nota fiscal eletrônica, usada entre empresas e em vendas com entrega |
| NFC-e | Nota fiscal de consumidor eletrônica, venda no balcão |
modeloModelo do documento
| Valores | Significado |
|---|---|
| 55 | NF-e |
| 65 | NFC-e |
statusSituação fiscal
| Valores | Significado |
|---|---|
| Autorizada | Autorizada pela SEFAZ e sem evento de cancelamento |
| Cancelada | Cancelada, inclusive por cancelamento substitutivo |
| Denegada | Denegada pela SEFAZ |
| Inutilizada | Numeração inutilizada |
| NaoEncontrada | Não encontrada na SEFAZ; pode ser atraso de sincronização |
| Desconhecida | Situação não classificável a partir da resposta da SEFAZ |
ambienteEmissaoAmbiente de emissão
| Valores | Significado |
|---|---|
| Producao | Ambiente oficial |
| Homologacao | Ambiente de teste da SEFAZ; a nota não tem validade |
tipoOperacaoTipo de operação
| Valores | Significado |
|---|---|
| Saida | Saída de mercadoria do emitente (tpNF=1), como uma venda |
| Entrada | Entrada de mercadoria no emitente (tpNF=0), como uma devolução de consumidor ou uma importação |
validation.validationStatusStatus da verificação
A primeira resposta síncrona traz só PENDING_SEFAZ ou REJECTED; os demais chegam pelo webhook invoice.verify.completed e também aparecem em respostas reutilizadas e na consulta por chave.
| Valores | Significado |
|---|---|
| PENDING_SEFAZ | Nível 1 aprovado, verificação na SEFAZ enfileirada |
| REJECTED | Reprovada; terminal. No nível 1 por erro bloqueante, no nível 2 pela situação na SEFAZ (cancelada, denegada, inutilizada, não encontrada, protocolo divergente); não prossiga |
| VALIDATING | Nível 2 em andamento, consultando a SEFAZ |
| VALIDATED | Nota autêntica e regular na SEFAZ; terminal, seguro prosseguir |
| VALIDATION_ERROR | Falha técnica do lado da plataforma, não é juízo sobre a nota; reutilizada por 24 horas como os demais vereditos, reenvie mais tarde com forceRevalidate: true |
validation.errors[].codeCódigos de problema de nível 1
Todos são bloqueantes e levam a REJECTED, exceto PROTOCOL_MISSING, que vai para warnings[]. O número entre parênteses é o código numérico equivalente.
| Valores | Significado |
|---|---|
| XML_MALFORMED | Sintaxe XML inválida (10015100) |
| XSD_INVALID | Não conforme ao layout oficial da NF-e 4.00 (10015101) |
| SIGNATURE_INVALID | Assinatura digital inválida: conteúdo alterado ou certificado vencido ao assinar (10015102) |
| SIGNATURE_CERT_MISMATCH | CNPJ do certificado de assinatura diferente do emitente (10015103) |
| ACCESS_KEY_INVALID | Estrutura ou dígito verificador da chave inválidos (10015104) |
| ACCESS_KEY_MISMATCH | Segmentos da chave diferentes dos campos do documento (10015105) |
| PROTOCOL_MISMATCH | Protocolo de autorização incoerente com a nota (10015106) |
| PROTOCOL_MISSING | Sem protocolo de autorização; aviso, não bloqueia (10015107) |
| XML_VERSION_UNSUPPORTED | Versão do layout diferente de 4.00 (10015108) |
| Código | HTTP | |
|---|---|---|
| 10015104 | 400 | Chave malformada (comprimento / caracteres / dígito verificador). Rejeitada localmente, nenhuma consulta é feita. |
| 10015004 | 400 | Nota não encontrada em nenhuma fonte. A chave é desconhecida para a plataforma e para a fonte oficial; confirme a chave com o emitente. Não confundir com o status NaoEncontrada do nível 2, que é a resposta 217 da SEFAZ. |