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. It is a pure query endpoint and carries no verification verdict.

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; the chave lookup can serve as a 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), then parked in a dead-letter queue (manual re-push available on request).
4. Deduplicate on event_id (retries and multi-target fan-out share the same event_id).

Verdict handling

Idempotency and re-verification

• XML verification is idempotent on the chave: resubmitting while a verification is in progress returns the current progress; terminal verdicts are reused for 24 hours (no duplicate verification cost).
• Forced re-verification: send the header forceRevalidate: true on the XML verification endpoint (not part of the signature). The chave lookup has a fixed GET shape with no re-verification channel; to force a re-check, resubmit through the XML endpoint.
• A Tier-1 blocking REJECTED has no Tier-2 record; re-verification requires resubmitting the XML.

Error model

Two error shapes

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

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

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