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. That response already shows
validationStatus=VALIDATING, and the new verdict arrives through the webhook as a new event. Two kinds of verdicts are never re-checked: invoices alreadyCancelada,DenegadaorInutilizada(their status cannot change), and verdicts where SEFAZ does not accept queries for the invoice (VALIDATION_ERRORwithstatusDesconhecida, e.g. cStat 526; re-checking would not change them). - No forced re-verification: this endpoint cannot force a re-check. To do that, resubmit the XML through XML verification with the
forceRevalidate: trueheader (see Idempotency and re-verification).
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; also when SEFAZ does not accept queries for the invoice (e.g. cStat 526) |
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 |
emitente.endereco.uf / destinatario.endereco.ufState
Copied from the invoice without conversion.
| Values | Meaning |
|---|---|
| AC | Acre |
| AL | Alagoas |
| AP | Amapá |
| AM | Amazonas |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MT | Mato Grosso |
| MS | Mato Grosso do Sul |
| MG | Minas Gerais |
| PA | Pará |
| PB | Paraíba |
| PR | Paraná |
| PE | Pernambuco |
| PI | Piauí |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RS | Rio Grande do Sul |
| RO | Rondônia |
| RR | Roraima |
| SC | Santa Catarina |
| SP | São Paulo |
| SE | Sergipe |
| TO | Tocantins |
| EX | Abroad; recipient only |
itens[].cfopItem fiscal operation code
4 digits, copied from the invoice. The first digit gives direction and reach; the full list is the CFOP table of Convênio s/nº of 1970, published on the NF-e Portal.
| Values | Meaning |
|---|---|
| 1xxx | Inbound within the state |
| 2xxx | Inbound from another state |
| 3xxx | Inbound from abroad |
| 5xxx | Outbound within the state |
| 6xxx | Outbound to another state |
| 7xxx | Outbound abroad |
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 | Verification could not complete; terminal, not a judgment on the invoice. Two kinds: SEFAZ throttling, query failures after retries or SEFAZ unavailable for a long time, reused for 24 hours, resubmit later with forceRevalidate: true; SEFAZ does not accept queries for the invoice (e.g. cStat 526), status Desconhecida, reused for as long as the platform keeps the record and resubmitting will not change it |
validation.errors[].code / validation.warnings[].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) |
validation.xmlVersionLayout version
Other versions are rejected with XML_VERSION_UNSUPPORTED.
| Values | Meaning |
|---|---|
| 4.00 | Current NF-e and NFC-e layout |
| 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. |
