NF-e verification

Overview

The platform performs two-tier verification of third-party NF-e documents (model 55):

A standalone chave lookup returns invoice data by access key. For a chave you submitted through XML verification it also returns the current validation block, so it doubles as the polling fallback when a webhook delivery is missed.

Both endpoints require the three signature headers, see Authentication. Responses are bare objects (no platform envelope); request-level errors are a bare {code, message} object.

Verification lifecycle

submit XML ──► Tier 1
                ├─ blocking error ──────────────► REJECTED          (terminal)
                └─ pass ──► PENDING_SEFAZ ──► VALIDATING (Tier 2)
                                               ├──► VALIDATED       (terminal)
                                               ├──► REJECTED        (terminal, with reason)
                                               └──► VALIDATION_ERROR (retryable, with reason)

Onboarding

1. Application credential: apply for an application and receive an app_secret. It is displayed only once; store it securely. If leaked, request rotation.
2. API subscription: the platform enables your application for POST /openapi/v3/consultas/nf-e/xml and GET /openapi/v3/consultas/nf-e/{chave}.
3. Webhook endpoint: register your callback URL through Register webhook and subscribe to the event invoice.verify.completed (the only push channel for Tier-2 verdicts). When the URL is saved, the platform immediately sends a test delivery with event_type=webhook.verify; your endpoint must return 2xx for the save to succeed (returning 200 without processing is fine for the test event).

Endpoints

Receiving the final verdict

When Tier-2 SEFAZ verification settles, the platform POSTs to your registered webhook URL. This is the only push channel for final verdicts; if a delivery is missed, the chave lookup returns the current validationStatus and serves as the polling fallback.

Request headers

Payload

{
  "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"
  }
}

Envelope fields:

data fields:

Note: webhook payloads carry only language-independent enum values; there are no *Description fields here. Presentation text is up to the receiver.

Receiver requirements

1. Verify the signature: recompute HMAC-SHA256(secret, timestamp + "." + rawBody) and compare with the header. Use the raw received bytes; do not deserialize and re-serialize first (field reordering breaks the signature).
2. Return 2xx within 10 seconds. Anything else, including timeouts, counts as a failed delivery.
3. Failed deliveries are retried with backoff 1m / 5m / 30m / 2h / 6h (5 attempts); manual re-push is available on request.
4. Deduplicate on event_id (retries and multi-target fan-out share the same event_id).
5. One chave can produce several events over time: a re-verification with forceRevalidate: true, a resubmission after the 24-hour window, or a background re-check triggered by the chave lookup each end in a new event with its own event_id. Keep the verdict from the event with the latest occurred_at.

Verdict handling

Idempotency and re-verification

• XML verification is idempotent on the chave (the access key inside the submitted XML):
  • While Tier 2 is in progress (PENDING_SEFAZ / VALIDATING), resubmitting returns the current progress and does not start another check. forceRevalidate: true does not restart or speed up a check that is already running.
  • A terminal verdict (VALIDATED / REJECTED / VALIDATION_ERROR) is reused for 24 hours from the moment it was reached: resubmitting within that window returns it without contacting SEFAZ again. After 24 hours, a plain resubmission runs the full verification (Tier 1 + Tier 2) again.
  • A reused response reflects the originally submitted XML (parsed invoice data, Tier-1 checks, errors and warnings) together with the current validationStatus. If you resubmit a corrected XML for the same chave within the window, send forceRevalidate: true; otherwise you get the earlier result back.
• Forced re-verification: send the header forceRevalidate: true on the XML verification endpoint (not part of the signature). It skips reuse and runs Tier 1 and Tier 2 again; the new verdict arrives as a new webhook event.
• Chave lookup: it cannot force a re-check. It schedules one by itself only when the latest SEFAZ answer is older than 24 hours (see chave lookup).
• A Tier-1 blocking REJECTED has no Tier-2 record; to re-verify, resubmit the XML (with forceRevalidate: true inside the 24-hour window).
• Verifications belong to your integrator account: reuse, chave lookups and webhooks only see your own submissions. Another integrator verifying the same invoice does not affect yours; each account is verified independently and gets its own verdict.

Error model

Two error shapes

Business and request-level errors (HTTP 400) are returned as a bare object:

{ "code": 10015004, "message": "Invoice not found: 35260764962869000108550990001366171195929648" }

Authentication-layer errors (HTTP 401 / 403 / 429) are produced by the platform gateway before your request reaches the API, and use the platform envelope:

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

Your error handler must accept both shapes. A robust rule: parse the body as JSON, read code from either shape, and treat success=false or HTTP >= 400 as failure.

Authentication and authorization errors

Retry guidance: 401 and 403 are configuration errors; retrying without a fix is pointless and may trip rate limits. 429 is retryable with exponential backoff (start at 1 s, double up to 30 s, add jitter).

Request-level and validation errors

Documented on each endpoint page:

• XML verification: request-level errors 10015000 to 10015003 (HTTP 400, bare shape, the request never enters validation) and the Tier-1 validation catalog XML_MALFORMED to XML_VERSION_UNSUPPORTED (HTTP 200, inside validation.errors[]).
• Chave lookup: 10015104 (malformed chave) and 10015004 (invoice not found), HTTP 400, bare shape.
• Tier-2 outcomes are not HTTP errors; see Verdict handling.

HTTP status quick reference

Response localization

message and *Description fields follow the request language: the Language header (en / pt / es / zh) takes precedence, then Accept-Language (supports pt-BR and q-values). Without a language header, responses default to Portuguese (pt).

For programmatic decisions always use the language-independent enum fields (validationStatus, status, errors[].code); never match on description text.

Integration checklist

1. Obtain the app_secret; cross-check your signing implementation against the sign-helper output (once for POST with an XML body, once for GET with an empty body).
2. POST /openapi/v3/consultas/nf-e/xml with a genuine authorized nfeProc: HTTP 200, all five validation checks true, validationStatus=PENDING_SEFAZ.
3. Receive the invoice.verify.completed webhook: signature verifies, deduplicated by event_id, verdict VALIDATED.
4. Chave lookup: a previously submitted chave returns 200 with invoice data and the validation block (same validationStatus as the webhook verdict); a nonexistent chave returns 400 + 10015004; a chave with a wrong check digit returns 400 + 10015104.
5. Negative cases: submit a tampered XML (SIGNATURE_INVALID); submit an XML without protNFe (warning only, still accepted).
6. Idempotency: resubmit the same chave and get the reused verdict; submit with forceRevalidate: true and get a re-verification with a new verdict via webhook.
7. Failure paths: call with a wrong sign (401, code 10009003); call an unsubscribed endpoint (403, code 10009005).

Troubleshooting

1. CR/LF not stripped from the body before concatenation;
2. GET request concatenated "null" instead of the empty string for the body;
3. path missing the /openapi prefix, or including the query string;
4. sign sent in uppercase (must be lowercase hex);
5. the timestamp value used in concatenation differs from the header (regenerated between the two);
6. body bytes re-encoded (must hash the exact bytes sent on the wire, UTF-8).

1. the invoice was authorized moments ago and SEFAZ has not finished propagating it; re-verify later with forceRevalidate: true;
2. the invoice was issued in the SEFAZ homologation environment (ambienteEmissao=Homologacao): Tier 2 queries the production environment, where test invoices do not exist;
3. the invoice was never authorized under that chave.

This is different from the chave lookup's 10015004, which means none of the platform's data sources knows the chave.