Verificação de NF-e

Visão geral

A plataforma executa uma verificação em dois níveis de NF-e de terceiros (modelo 55):

Uma consulta por chave independente devolve os dados da nota pela chave de acesso. Para uma chave que você enviou pela verificação de XML, ela também devolve o bloco validation atual e serve como alternativa de polling quando uma entrega de webhook se perde.

Os dois endpoints exigem os três cabeçalhos de assinatura, veja Autenticação. As respostas são objetos simples (sem envelope da plataforma); erros de requisição são um objeto simples {code, message}.

Ciclo de vida da verificação

envio do XML ──► Nível 1
                  ├─ erro bloqueante ────────────► REJECTED          (terminal)
                  └─ aprovado ──► PENDING_SEFAZ ──► VALIDATING (Nível 2)
                                                    ├──► VALIDATED       (terminal)
                                                    ├──► REJECTED        (terminal, com reason)
                                                    └──► VALIDATION_ERROR (repetível, com reason)

Pré-requisitos (uma única vez)

1. Credencial da aplicação: solicite uma aplicação e receba o app_secret. Ele é exibido apenas uma vez; guarde-o com segurança. Em caso de vazamento, solicite a rotação.
2. Assinatura da API: a plataforma habilita sua aplicação para POST /openapi/v3/consultas/nf-e/xml e GET /openapi/v3/consultas/nf-e/{chave}.
3. Endpoint de webhook: registre a URL de callback em Registrar webhook e assine o evento invoice.verify.completed (o único canal de envio dos vereditos de nível 2). Ao salvar a URL, a plataforma envia imediatamente uma entrega de teste com event_type=webhook.verify; seu endpoint deve responder 2xx para que o salvamento tenha êxito (responder 200 sem processar é suficiente para o evento de teste).

Endpoints

Recebendo o veredito final

Quando a verificação de nível 2 na SEFAZ é concluída, a plataforma faz um POST para a URL de webhook registrada. Este é o único canal de envio dos vereditos finais; se uma entrega se perder, a consulta por chave devolve o validationStatus atual e serve como alternativa de polling.

Cabeçalhos da requisição

Carga

{
  "version": "1.0",
  "event_id": "1950000000000001",
  "event_type": "invoice.verify.completed",
  "occurred_at": "2026-07-23T17:16:23Z",
  "data": {
    "chaveAcesso": "35260764962869000108550990001366171195929648",
    "validationStatus": "VALIDATED",
    "status": "Autorizada",
    "cStat": "100",
    "xMotivo": "Autorizado o uso da NF-e",
    "protocolo": { "numero": "135262955451772", "digestValue": "oAEEuC3tGmb2W7ZJxWkNVWuBHwY=" },
    "dataAutorizacao": "2026-07-23T14:30:09Z",
    "eventos": [],
    "verifiedAt": "2026-07-23T17:16:23Z"
  }
}

Campos do envelope:

Campos de data:

Nota: as cargas de webhook trazem apenas valores enumerados independentes de idioma; não há campos *Description aqui. O texto de apresentação fica a cargo do receptor.

Requisitos do receptor

1. Verifique a assinatura: recalcule HMAC-SHA256(secret, timestamp + "." + rawBody) e compare com o cabeçalho. Use os bytes brutos recebidos; não desserialize e serialize de novo antes (a reordenação de campos quebra a assinatura).
2. Responda 2xx em até 10 segundos. Qualquer outra coisa, incluindo timeouts, conta como entrega falha.
3. Entregas falhas são repetidas com backoff 1m / 5m / 30m / 2h / 6h (5 tentativas); reenvio manual disponível sob solicitação.
4. Deduplique por event_id (tentativas e fan-out para múltiplos destinos compartilham o mesmo event_id).
5. Uma mesma chave pode gerar vários eventos ao longo do tempo: uma nova verificação com forceRevalidate: true, um reenvio após a janela de 24 horas ou uma rechecagem em segundo plano disparada pela consulta por chave terminam, cada um, em um novo evento com seu próprio event_id. Fique com o veredito do evento com o occurred_at mais recente.

Tratamento do veredito

Idempotência e nova verificação

• A verificação de XML é idempotente pela chave (a chave de acesso dentro do XML enviado):
  • Enquanto o nível 2 está em andamento (PENDING_SEFAZ / VALIDATING), reenviar devolve o progresso atual e não inicia outra checagem. forceRevalidate: true não reinicia nem acelera uma checagem já em curso.
  • Um veredito terminal (VALIDATED / REJECTED / VALIDATION_ERROR) é reutilizado por 24 horas a partir do momento em que foi obtido: reenviar dentro dessa janela o devolve sem consultar a SEFAZ de novo. Depois de 24 horas, um reenvio simples executa a verificação completa (nível 1 + nível 2) outra vez.
  • Uma resposta reutilizada reflete o XML enviado originalmente (dados da nota, checagens de nível 1, erros e avisos) junto com o validationStatus atual. Se você reenviar um XML corrigido para a mesma chave dentro da janela, envie forceRevalidate: true; caso contrário, recebe o resultado anterior.
• Nova verificação forçada: envie o cabeçalho forceRevalidate: true no endpoint de verificação de XML (não faz parte da assinatura). Ele ignora a reutilização e executa o nível 1 e o nível 2 de novo; o novo veredito chega como um novo evento de webhook.
• Consulta por chave: não força uma rechecagem. Ela agenda uma por conta própria somente quando a última resposta da SEFAZ tem mais de 24 horas (veja consulta por chave).
• Um REJECTED bloqueante de nível 1 não tem registro de nível 2; para verificar de novo, reenvie o XML (com forceRevalidate: true dentro da janela de 24 horas).
• As verificações pertencem à sua conta de integrador: a reutilização, a consulta por chave e os webhooks só enxergam os envios da sua conta. Outro integrador verificando a mesma nota não afeta a sua; cada conta é verificada de forma independente e recebe o próprio veredito.

Modelo de erros

Duas formas de erro

Erros de negócio e de requisição (HTTP 400) são devolvidos como objeto simples:

{ "code": 10015004, "message": "Nota fiscal não encontrada: 35260764962869000108550990001366171195929648" }

Erros da camada de autenticação (HTTP 401 / 403 / 429) são produzidos pelo gateway da plataforma antes de a requisição chegar à API e usam o envelope da plataforma:

{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }

Seu tratamento de erros precisa aceitar as duas formas. Uma regra robusta: interprete o corpo como JSON, leia code de qualquer uma das formas e trate success=false ou HTTP >= 400 como falha.

Erros de autenticação e autorização

Orientação de repetição: 401 e 403 são erros de configuração; repetir sem corrigir é inútil e pode disparar o limite de taxa. 429 pode ser repetido com backoff exponencial (inicie em 1 s, dobre até 30 s, adicione jitter).

Erros de requisição e de validação

Documentados em cada página de endpoint:

• Verificar XML: erros de requisição 10015000 a 10015003 (HTTP 400, forma simples, a requisição nunca entra na validação) e o catálogo de validação de nível 1 de XML_MALFORMED a XML_VERSION_UNSUPPORTED (HTTP 200, dentro de validation.errors[]).
• Consultar por chave: 10015104 (chave malformada) e 10015004 (nota não encontrada), HTTP 400, forma simples.
• Os resultados de nível 2 não são erros HTTP; veja Tratamento do veredito.

Referência rápida de status HTTP

Localização das respostas

Os campos message e *Description seguem o idioma da requisição: o cabeçalho Language (en / pt / es / zh) tem precedência, depois Accept-Language (aceita pt-BR e valores q). Sem cabeçalho de idioma, as respostas usam português (pt) por padrão.

Para decisões programáticas use sempre os campos enumerados independentes de idioma (validationStatus, status, errors[].code); nunca compare textos descritivos.

Checklist de integração

1. Obtenha o app_secret; confira sua implementação de assinatura com a saída do assistente de assinatura (uma vez para POST com corpo XML, uma vez para GET com corpo vazio).
2. POST /openapi/v3/consultas/nf-e/xml com um nfeProc autorizado genuíno: HTTP 200, as cinco verificações de validação true, validationStatus=PENDING_SEFAZ.
3. Receba o webhook invoice.verify.completed: assinatura confere, deduplicado por event_id, veredito VALIDATED.
4. Consulta por chave: uma chave já enviada devolve 200 com os dados da nota e o bloco validation (mesmo validationStatus do veredito do webhook); uma chave inexistente devolve 400 + 10015004; uma chave com dígito verificador errado devolve 400 + 10015104.
5. Casos negativos: envie um XML adulterado (SIGNATURE_INVALID); envie um XML sem protNFe (apenas aviso, ainda aceito).
6. Idempotência: reenvie a mesma chave e receba o veredito reutilizado; envie com forceRevalidate: true e receba uma nova verificação com novo veredito via webhook.
7. Caminhos de falha: chame com sign errado (401, código 10009003); chame um endpoint não assinado (403, código 10009005).

Solução de problemas

1. CR/LF não removidos do corpo antes da concatenação;
2. requisição GET concatenou "null" em vez da string vazia como corpo;
3. path sem o prefixo /openapi, ou incluindo a query string;
4. sign enviado em maiúsculas (deve ser hex minúsculo);
5. o valor de timestamp usado na concatenação difere do cabeçalho (gerado de novo entre os dois);
6. bytes do corpo recodificados (é preciso fazer o hash exatamente dos bytes enviados na rede, UTF-8).

1. a nota foi autorizada há instantes e a SEFAZ ainda não terminou de propagá-la; verifique de novo mais tarde com forceRevalidate: true;
2. a nota foi emitida no ambiente de homologação da SEFAZ (ambienteEmissao=Homologacao): o nível 2 consulta o ambiente de produção, onde notas de teste não existem;
3. a nota nunca foi autorizada com essa chave.

Isso é diferente do 10015004 da consulta por chave, que significa que nenhuma fonte de dados da plataforma conhece a chave.