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. É um endpoint de consulta pura e não traz veredito de verificação.

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; a consulta por chave pode servir 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) e depois estacionadas em uma fila de mensagens mortas (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).

Tratamento do veredito

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 no endpoint de verificação de XML (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 pelo endpoint de XML.
• Um REJECTED bloqueante de nível 1 não tem registro de nível 2; a nova verificação exige reenviar o XML.

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": "Invoice not found" }

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; 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).