NF-e verification
Chave lookup
Returns invoice data for a 44-digit access key and, if you submitted that chave for verification, the current verdict.
/openapi/v3/consultas/nf-e/{chave}token, timestamp and sign signature headers, see Authentication.Returns invoice data for a 44-digit access key. For a chave submitted through XML verification, the response also carries the validation block with the current validationStatus: use it as the polling fallback when an invoice.verify.completed webhook delivery is missed (see NF-e verification). Invoices that were only issued through this platform or only found in the official data source were never verified and come without that block.
Path parameters
chave* | string | Access key |
* Required field
validation block is present only for chaves submitted there.tipo | string | Document type |
modelo | string | Document model |
status | string | Fiscal status |
statusDescription | string | Status description |
ambienteEmissao | string | Issue environment |
numero | string | Invoice number |
serie | string | Series |
dataEmissao | string | Issue time |
tipoOperacao | string | Operation type (tpNF), the direction of goods as seen by the issuer |
chaveAcesso | string | Access key |
| object | Issuer |
| object | Recipient |
| array | Items |
dataAutorizacao | string | Authorization time |
| object | Authorization protocol |
valorTotal | number | Invoice net total |
| object | Current verification verdict |
Given app_secret = sk_live_9f8e7d6c5b4a, the chave 35260764962869000108550990001366171195929648 and timestamp = 1784906308, the signing string is (GET, empty body; the chave is part of the path):
sign_input = "sk_live_9f8e7d6c5b4a"+ "/openapi/v3/consultas/nf-e/35260764962869000108550990001366171195929648"+ ""+ "1784906308"sign = md5Hex(sign_input)
The platform resolves the chave through the tiers below, in this order; the first hit is returned.
Previously submitted for verification
The platform keeps the record from XML verification and returns the full invoice data plus the validation block with the current validationStatus.
Invoice issued through this platform
Full invoice data parsed from the authorized XML, without a validation block.
Unknown chave
Full authorized data fetched from the official data source, per platform policy, without a validation block.
No source hit
HTTP 400 with 10015004. A malformed chave returns 10015104 without querying any source.
{ "code": 10015004, "message": "Invoice not found: 35260764962869000108550990001366171195929648" }
- Polling fallback: for a chave submitted through XML verification, the
validationblock carries the currentvalidationStatus(PENDING_SEFAZ,VALIDATINGor the final verdict). Use it when aninvoice.verify.completedwebhook delivery is missed. - Background re-check: when the latest SEFAZ answer for that chave is more than 24 hours old, the lookup schedules a new Tier-2 check (except invoices already
Cancelada,DenegadaorInutilizada, whose status cannot change). That response already showsvalidationStatus=VALIDATING, and the new verdict arrives through the webhook as a new event. - No forced re-verification: this endpoint cannot force a re-check. To do that, resubmit the XML through XML verification with the
forceRevalidate: trueheader.
tipoDocument type
| Values | Meaning |
|---|---|
| NF-e | Electronic invoice used between companies and on delivered sales |
| NFC-e | Electronic consumer invoice, over-the-counter sales |
modeloDocument model
| Values | Meaning |
|---|---|
| 55 | NF-e |
| 65 | NFC-e |
statusFiscal status
| Values | Meaning |
|---|---|
| Autorizada | Authorized by SEFAZ with no cancellation event |
| Cancelada | Cancelled, including by substitute cancellation |
| Denegada | Denied by SEFAZ |
| Inutilizada | Invoice number voided |
| NaoEncontrada | Not found at SEFAZ; may be a synchronization delay |
| Desconhecida | Status not classifiable from the SEFAZ reply |
ambienteEmissaoIssue environment
| Values | Meaning |
|---|---|
| Producao | Official environment |
| Homologacao | SEFAZ test environment; the invoice has no legal effect |
tipoOperacaoOperation type
| Values | Meaning |
|---|---|
| Saida | Goods leaving the issuer (tpNF=1), such as a sale |
| Entrada | Goods entering the issuer (tpNF=0), such as a consumer return or an import |
validation.validationStatusVerification status
The first synchronous response carries only PENDING_SEFAZ or REJECTED; the others arrive through the invoice.verify.completed webhook and also show up in reused responses and the chave lookup.
| Values | Meaning |
|---|---|
| PENDING_SEFAZ | Tier 1 passed, SEFAZ verification queued |
| REJECTED | Rejected; terminal. At Tier 1 by a blocking error, at Tier 2 by the SEFAZ status (cancelled, denied, voided, not found, protocol mismatch); do not proceed |
| VALIDATING | Tier 2 in progress, querying SEFAZ |
| VALIDATED | Invoice authentic and regular at SEFAZ; terminal, safe to proceed |
| VALIDATION_ERROR | Platform-side technical failure, not a judgment on the invoice; reused for 24 hours like any verdict, resubmit later with forceRevalidate: true |
validation.errors[].codeTier-1 issue codes
All are blocking and lead to REJECTED, except PROTOCOL_MISSING, which goes to warnings[]. The number in parentheses is the equivalent numeric code.
| Values | Meaning |
|---|---|
| XML_MALFORMED | XML syntax invalid (10015100) |
| XSD_INVALID | Does not conform to the official NF-e 4.00 layout (10015101) |
| SIGNATURE_INVALID | Digital signature invalid: content tampered or certificate expired at signing time (10015102) |
| SIGNATURE_CERT_MISMATCH | Signing certificate CNPJ differs from the issuer (10015103) |
| ACCESS_KEY_INVALID | Access key structure or check digit invalid (10015104) |
| ACCESS_KEY_MISMATCH | Access key segments differ from the document fields (10015105) |
| PROTOCOL_MISMATCH | Authorization protocol inconsistent with the invoice (10015106) |
| PROTOCOL_MISSING | No authorization protocol; warning, non-blocking (10015107) |
| XML_VERSION_UNSUPPORTED | Layout version is not 4.00 (10015108) |
| Code | HTTP | |
|---|---|---|
| 10015104 | 400 | Malformed chave (length / characters / check digit). Rejected locally, no lookup attempted. |
| 10015004 | 400 | Invoice not found in any source. The chave is unknown to the platform and the official data source; verify the chave with its issuer. Not to be confused with the Tier-2 status NaoEncontrada, which is the SEFAZ 217 answer. |