NF-e verification
Two-tier verification of third-party NF-e documents: XML verification, chave lookup, the final verdict delivered by webhook, DANFE (PDF) retrieval by chave, idempotency and the error model.
Overview
The platform performs two-tier verification of third-party NF-e documents (model 55):
| Tier | What it does | When |
|---|---|---|
| Tier 1 (synchronous) | Local validation of the XML: syntax, NF-e 4.00 XSD layout, digital signature and certificate ownership, 44-digit access key (chave) structure and consistency with document fields, authorization protocol integrity | Returned immediately in the API response |
| Tier 2 (asynchronous) | Real-time authenticity check against SEFAZ (the state tax authority): authorization status, cancellation events, protocol number and digest compared with official records | Runs after Tier 1 passes; the verdict is delivered via webhook (see Receiving the final verdict), and the chave lookup returns the current state as a polling fallback |
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.
For validated (or cancelled) invoices, DANFE retrieval returns the PDF directly by chave.
All three endpoints require the three signature headers, see Authentication. Calls are rate-limited per application and per endpoint group (XML verification and the chave lookup belong to the "invoice verification" group; DANFE retrieval has its own "DANFE retrieval" group, so fetching PDFs does not consume the former's quota); rules and headers are in Rate limiting and backoff. Responses are bare objects (no platform envelope; DANFE retrieval returns the PDF file itself); 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 (terminal, with reason)
| validationStatus | Meaning |
|---|---|
VALIDATED | SEFAZ confirms the invoice is authentic and effective (authorized, no cancellation, protocol matches) |
REJECTED | Verification failed: a Tier-1 blocking error, or SEFAZ reports the invoice is cancelled / denied / voided / not found / protocol mismatch. reason is provided |
VALIDATION_ERROR | Verification could not complete. Not a judgment on the invoice itself; reason is provided. Two kinds: (1) SEFAZ throttling, query failures after retries, or SEFAZ unavailable for a long time: resubmit later with forceRevalidate: true; (2) SEFAZ does not accept queries for this invoice (e.g. cStat 526, issued too long ago): status is Desconhecida and resubmitting will not change the verdict (see Troubleshooting) |
Onboarding
- Application credential: apply for an application and receive an
app_secret. It is displayed only once; store it securely. If leaked, request rotation. - API subscription: the platform enables your application for
POST /openapi/v3/consultas/nf-e/xmlandGET /openapi/v3/consultas/nf-e/{chave}; to fetch PDFs, additionally forGET /openapi/v3/consultas/danfe/{chave}(a separate scope, not included in the chave lookup). - 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 withevent_type=webhook.verify; your endpoint must return 2xx for the save to succeed (returning 200 without processing is fine for the test event).
Endpoints
| Endpoint | Purpose |
|---|---|
POST /openapi/v3/consultas/nf-e/xml | Submit the raw NF-e XML; returns the Tier-1 verdict and the parsed invoice, starts Tier 2 |
GET /openapi/v3/consultas/nf-e/{chave} | Lookup by access key; returns invoice data, plus the current validation block for chaves you submitted |
GET /openapi/v3/consultas/danfe/{chave} | DANFE by access key; returns the PDF of an invoice your account verified (its scope is enabled separately) |
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
| Header | Description |
|---|---|
X-Tffiscal-Event | invoice.verify.completed |
X-Tffiscal-Event-Id | Event id, the idempotency key: unchanged across retries; deduplicate on this |
X-Tffiscal-Delivery-Id | Delivery id, one per target URL; unchanged across retries to that target (deduplicate on the event id, not on this) |
X-Tffiscal-Timestamp | Unix seconds, regenerated on every attempt |
X-Tffiscal-Signature | hex( HMAC-SHA256( secret, timestamp + "." + body ) ), lowercase; secret = your app_secret for an application-level webhook URL (a tenant-level fallback URL is signed with the secret configured for it) |
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"}}
data when SEFAZ does not accept queries for the invoice (e.g. cStat 526):
{"chaveAcesso": "31241064962869000108550990001366171195929642","validationStatus": "VALIDATION_ERROR","status": "Desconhecida","cStat": "526","xMotivo": "Rejeição: Consulta a uma Chave de Acesso muito antiga","protocolo": null,"dataAutorizacao": null,"eventos": [],"verifiedAt": "2026-07-23T17:16:23Z","reason": "SEFAZ does not answer this chave (cStat=526: Rejeicao: Consulta a uma Chave de Acesso muito antiga), not retryable"}
Envelope fields:
| Field | Type | Presence | Description |
|---|---|---|---|
| version | string | always | Payload schema version, currently 1.0 |
| event_id | string | always | Event id, the idempotency key; identical across retries |
| event_type | string | always | invoice.verify.completed |
| occurred_at | string | always | Event time, ISO-8601 UTC |
| data | object | always | Verdict body, below |
data fields:
| Field | Type | Presence | Description |
|---|---|---|---|
| chaveAcesso | string | always | 44-digit access key of the verified invoice; join key back to your submission |
| validationStatus | string | always | Final verdict: VALIDATED / REJECTED / VALIDATION_ERROR (see Verification lifecycle) |
| status | string | null | nullable | SEFAZ fiscal status: Autorizada / Cancelada / Denegada / Inutilizada / NaoEncontrada / Desconhecida; null for VALIDATION_ERROR (no SEFAZ verdict was obtained), except Desconhecida when SEFAZ does not accept queries for the invoice (see the example above) |
| cStat | string | null | nullable | Raw SEFAZ return code (e.g. 100 = authorized, 101 = cancelled); null when SEFAZ was not reached |
| xMotivo | string | null | nullable | Raw SEFAZ return message (Portuguese, verbatim) |
| protocolo | object | null | nullable | Protocol object (numero, digestValue), as on the XML verification response; from the official record |
| dataAutorizacao | string | null | nullable | SEFAZ authorization time, ISO-8601 UTC |
| eventos[] | array | always (may be empty) | Fiscal events registered against the invoice (cancellation, correction letters); empty when none |
| verifiedAt | string | always | When Tier-2 verification completed, ISO-8601 UTC |
| reason | string | only on failure | Present only for REJECTED / VALIDATION_ERROR; stable English text explaining the verdict, meant for troubleshooting and logs; branch on validationStatus / status instead. When SEFAZ does not accept queries it reads SEFAZ does not answer this chave (cStat=…: …), not retryable (xMotivo with accents removed) |
Note: webhook payloads carry only language-independent enum values; there are no
*Descriptionfields here. Presentation text is up to the receiver.
Receiver requirements
- 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). - Return 2xx within 10 seconds. Anything else, including timeouts, counts as a failed delivery.
- Failed deliveries are retried with backoff 1m / 5m / 30m / 2h / 6h (5 attempts); manual re-push is available on request.
- Deduplicate on
event_id(retries and multi-target fan-out share the same event_id). - One chave can produce several events over time: a re-verification with
forceRevalidate: true, a resubmission with changed XML content, a resubmission after the reuse period, or a background re-check triggered by the chave lookup (see Idempotency and re-verification) each end in a new event with its ownevent_id. Keep the verdict from the event with the latestoccurred_at. Reusing an existing verdict sends no new event.
Verdict handling
| validationStatus | Terminal? | Action |
|---|---|---|
VALIDATED | Yes | Safe to proceed (release goods, settle, etc.) |
REJECTED | Yes | Do not proceed; reason explains the SEFAZ verdict (cancelled / denied / voided / not found / protocol mismatch) |
VALIDATION_ERROR (status null) | Yes, retryable | Platform-side verification failure, not an invoice judgment. Like any verdict it is reused for 24 hours, so resubmit later with forceRevalidate: true |
VALIDATION_ERROR (status Desconhecida) | Yes, retrying will not change it | SEFAZ does not accept queries for this invoice (e.g. cStat 526, issued too long ago). Not an invoice judgment; it does not mean the invoice is fake. The verdict is reused; there is no need to retry. Confirm by other means if needed |
Idempotency and re-verification
- XML verification is idempotent on the chave (the access key inside the submitted XML), and reuse applies only to resubmissions with identical content:
-
Changed content is re-verified automatically: if the XML you submit for a chave is not the same as the previous one (compared byte by byte, even a single character), nothing is reused and Tier 1 and Tier 2 run again in full; no
forceRevalidateneeded. Cancelled / denied / voided invoices are the exception: their verdict cannot change, so the earlier result is returned even for different content. The points below apply only to resubmissions with identical content. -
While Tier 2 is in progress (
PENDING_SEFAZ/VALIDATING), resubmitting returns the current progress and does not start another check.forceRevalidate: truedoes not restart or speed up a check that is already running. -
Terminal verdicts are reused as below. A reused verdict is returned as is, without contacting SEFAZ and without a new webhook event:
Existing verdict Plain resubmission With forceRevalidate: trueCancelled / denied / voided ( REJECTEDwithstatusCancelada/Denegada/Inutilizada)Reused for as long as the platform keeps the verification record Still reused: these statuses cannot change SEFAZ does not accept queries ( VALIDATION_ERRORwithstatusDesconhecida, e.g. cStat 526)Reused for as long as the platform keeps the verification record Full re-verification (Tier 1 + Tier 2) Any other verdict ( VALIDATED, otherREJECTEDandVALIDATION_ERROR)Reused for 24 hours from the moment it was reached, then fully re-verified Full re-verification (Tier 1 + Tier 2) -
Once the platform no longer keeps the verification record, a new submission is treated as a first submission.
-
A reused response reflects the originally submitted XML (parsed invoice data, Tier-1 checks, errors and warnings) together with the current
validationStatus. A corrected XML for the same chave is re-verified automatically, so you will not get the earlier result back (cancelled / denied / voided invoices excepted; their verdict cannot change).
-
- Forced re-verification: send the header
forceRevalidate: trueon the XML verification endpoint (not part of the signature). Following the table above 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, and never for the first two rows of the table (see chave lookup).
- A Tier-1 blocking
REJECTEDhas no Tier-2 record; to re-verify, resubmit the XML: a corrected XML is re-verified automatically; resubmitting the same XML inside the 24-hour window needsforceRevalidate: true. - 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 are returned as a bare object (HTTP 400 for XML verification and the chave lookup; DANFE retrieval also uses 404 / 409 / 500 / 503, see DANFE retrieval):
{ "code": 10015004, "message": "Invoice not found: 35260764962869000108550990001366171195929648" }
| Field | Type | Description |
|---|---|---|
| code | integer | Platform error code |
| message | string | Human-readable explanation, localized (see Response localization) |
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" }
| Field | Type | Description |
|---|---|---|
| success | boolean | false for every error |
| errorType | integer | Error class: 1 API error, 2 SEFAZ rejection, 3 system fault, 4 field validation failure |
| code | integer | Platform error code |
| message | string | Human-readable explanation, localized |
| data | object | null | Not populated on errors |
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
| HTTP | code | Meaning | Action |
|---|---|---|---|
| 401 | 10009000 | Missing signature headers (token / sign / timestamp) | Fix the client: send all three headers on every request |
| 401 | 10009001 | Timestamp invalid or clock skew beyond ±300 s | Sync your clock (NTP); regenerate timestamp per request, never reuse |
| 401 | 10009002 | Invalid token | Check the app_secret; if rotated, update your configuration |
| 401 | 10009003 | Signature mismatch | Re-derive the signature; see the checklist in Troubleshooting |
| 403 | 10009004 | Application disabled | Contact the platform |
| 403 | 10009015 | Application not effective (pending approval or rejected) | Wait for approval / contact the platform |
| 403 | 10009014 | Integrator account disabled | Contact the platform |
| 403 | 10009005 | API not subscribed | Request subscription for the endpoint being called |
| 429 | 10009006 | Rate limit exceeded, or the application is in a cooldown | Wait for Retry-After, then retry; smooth your call rate. Rules and headers: Rate limiting and backoff |
| 413 | 10009027 | Request body exceeds the gateway size limit | XML verification accepts at most 1 MB; make sure you send a single NF-e |
Retry guidance: 401 and 403 are configuration errors; retrying without a fix is pointless and may trip rate limits. 429 is retryable: wait for Retry-After first, and if still rejected back off exponentially (start at 1 s, double up to 30 s, add jitter); ignoring 429 and resending continuously leads to a cooldown (see Cooldown).
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_MALFORMEDtoXML_VERSION_UNSUPPORTED(HTTP 200, insidevalidation.errors[]). - Chave lookup: 10015104 (malformed chave) and 10015004 (invoice not found), HTTP 400, bare shape.
- DANFE retrieval: 10015104 (malformed chave, 400), 10015300 (no verification record for the invoice in your account, 404), 10015301 to 10015303 (verification not finished / verdict produces no PDF / original XML missing, 409), 10015304 and 10015305 (original XML still being archived / generation busy, 503 with
Retry-After), 10001000 (internal platform error, 500), bare shape; errors are JSON even when the request carriesAccept: application/pdf. - Tier-2 outcomes are not HTTP errors; see Verdict handling.
HTTP status quick reference
| HTTP | Scenario | Body shape |
|---|---|---|
| 200 | Request accepted, including failed validation (check the validation block); DANFE retrieval returns the PDF file | Bare data; application/pdf for DANFE retrieval |
| 400 | Request itself invalid (empty / oversized / DTD / encoding / malformed chave / not found) | Bare {code, message} |
| 404 | DANFE retrieval: your account has no verification record for the invoice | Bare {code, message} |
| 409 | DANFE retrieval: verification not finished / verdict produces no PDF / original XML missing | Bare {code, message} |
| 503 | DANFE retrieval: original XML still being archived / generation busy (carries Retry-After) | Bare {code, message} |
| 401 | Authentication failed (token / sign / timestamp) | Platform envelope |
| 413 | Body exceeds the gateway size limit | Platform envelope |
| 403 | Application disabled / not effective / integrator disabled / not subscribed | Platform envelope |
| 429 | Rate limit exceeded or application in a cooldown (carries Retry-After and X-RateLimit-*, see Rate limiting and backoff) | Platform envelope |
| Other 5xx | Platform-side fault | Retry with backoff; if persistent, contact the platform with the failing timestamp and path |
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
- 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). POST /openapi/v3/consultas/nf-e/xmlwith a genuine authorized nfeProc: HTTP 200, all five validation checks true,validationStatus=PENDING_SEFAZ.- Receive the
invoice.verify.completedwebhook: signature verifies, deduplicated byevent_id, verdictVALIDATED. - Chave lookup: a previously submitted chave returns 200 with invoice data and the
validationblock (samevalidationStatusas the webhook verdict); a nonexistent chave returns 400 + 10015004; a chave with a wrong check digit returns 400 + 10015104. - Negative cases: submit a tampered XML (
SIGNATURE_INVALID); submit an XML without protNFe (warning only, still accepted). - Idempotency: resubmit the same chave and get the reused verdict; submit with
forceRevalidate: trueand get a re-verification with a new verdict via webhook; submit a cancelled invoice withforceRevalidate: trueand get the original verdict back. - Failure paths: call with a wrong
sign(401, code 10009003); call an unsubscribed endpoint (403, code 10009005). - DANFE (requires its scope): fetch a
VALIDATEDinvoice and get 200application/pdfwithX-Tffiscal-Nfe-Status: Autorizada; fetch an invoice still being verified and get 409 + 10015301; fetch a chave your account never submitted and get 404 + 10015300; errors stay JSON withAccept: application/pdf.
Troubleshooting
Signature never matches (401, code 10009003)?
Check, in order of frequency:
- CR/LF not stripped from the body before concatenation;
- GET request concatenated
"null"instead of the empty string for the body; pathmissing the/openapiprefix, or including the query string;signsent in uppercase (must be lowercase hex);- the
timestampvalue used in concatenation differs from the header (regenerated between the two); - body bytes re-encoded (must hash the exact bytes sent on the wire, UTF-8).
HTTP 200 but the invoice is fake?
Tier 1 only judges whether the XML is internally consistent. Authenticity is decided by Tier 2 against SEFAZ and delivered via webhook; gate your business action (release, settlement) on the webhook VALIDATED, never on the synchronous response alone.
Is the status in the synchronous response the SEFAZ status?
No. In the first response status is read from the protocol inside the XML you sent; SEFAZ has not been consulted yet. The status confirmed by SEFAZ arrives with the Tier-2 verdict: the webhook status, or the chave lookup once Tier 2 has an answer.
REJECTED with status NaoEncontrada: is the invoice fake?
Not necessarily. SEFAZ answered "not found" (cStat 217). The platform does not conclude on the first 217: it queries SEFAZ again several times over a few minutes, because a just-authorized invoice can take a while to become queryable, and only a persistent 217 becomes REJECTED with NaoEncontrada. Common causes:
- the invoice was authorized moments ago and SEFAZ has not finished propagating it; re-verify later with
forceRevalidate: true; - the invoice was issued in the SEFAZ homologation environment (
ambienteEmissao=Homologacao): Tier 2 queries the production environment, where test invoices do not exist; - 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.
Webhook signature keeps failing?
The most common cause is deserializing the payload and re-serializing it before computing the HMAC, which changes field order or whitespace. Always hash the raw received bytes.
Is VALIDATION_ERROR a problem with the invoice?
No. It means the platform could not complete the check; the invoice itself was not judged. There are two kinds:
statusisDesconhecidaand the reason starts withSEFAZ does not answer this chave: SEFAZ does not accept queries for this invoice (currently cStat 526, invoices issued too long ago). The platform queries once and returns the verdict right away; querying again would not change it. It does not mean the invoice is fake; it just cannot be verified through SEFAZ, so confirm by other means if needed. The verdict is reused for as long as the platform keeps the verification record, so resubmissions and chave lookups do not contact SEFAZ again; if you really need one more query, resubmit withforceRevalidate: true.- Anything else means the verification channel failed (e.g. SEFAZ throttling or a long SEFAZ outage). Resubmit later with
forceRevalidate: true. For this kindstatusis null in webhooks, but in synchronous responses (the XML endpoint's reuse response and chave lookups) it still carries the status from the submitted XML, so do not use it to tell the kinds apart.
DANFE retrieval returns 409 + 10015303?
The platform is missing the original XML of this invoice (for example after an archive storage failure). As described under "When the original XML is missing" on DANFE retrieval, resubmit the same XML unchanged through XML verification (without forceRevalidate), then fetch again.
DANFE retrieval keeps returning 503?
Retry after Retry-After. 10015304 means the original XML is still being archived and is usually ready within seconds; 10015305 means generation is busy or temporarily unavailable; contact the platform if it lasts more than a few minutes.
DANFE retrieval returns 403 + 10009005?
Your application does not have the DANFE retrieval scope; it is enabled separately from the chave lookup.
Clock skew (401, code 10009001)?
Your server clock differs from ours by more than 300 seconds. Use NTP. Never cache or reuse timestamps across requests.
