Verification API

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

Two endpoints:

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

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 — an app_secret, displayed only once.
2. API subscription — the platform enables your application for both endpoints above.
3. Webhook endpoint — configure your application-level webhook URL 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). See Webhooks.

XML verification

Submits the raw NF-e XML. Returns the Tier-1 verdict and the parsed invoice data synchronously; on Tier-1 pass, Tier-2 SEFAZ verification starts automatically (verdict via webhook).

Request

POST /openapi/v3/consultas/nf-e/xml
Content-Type: application/xml            (or text/xml)
token / timestamp / sign                 see Authentication & Signing
forceRevalidate: true                    (optional header, NOT signed, default false)

<request body: raw NF-e XML>

Body requirements:

• Preferred: the full nfeProc authorized document (including the protNFe protocol node). A bare NFe without the protocol node is also accepted — it produces a warning but is processed normally.
• Hard limits: max 1 MB, UTF-8 only, DTD forbidden (any <!DOCTYPE is rejected outright).

Signing: the body participates in the signature after stripping every CR and LF, while the request body itself is sent unchanged: sign = md5Hex(app_secret + "/openapi/v3/consultas/nf-e/xml" + xmlWithoutCrLf + timestamp).

Complete worked example:

POST /openapi/v3/consultas/nf-e/xml HTTP/1.1
Host: api.v2.tffiscal.com
Content-Type: application/xml
token: sk_live_9f8e7d6c5b4a
timestamp: 1784906308
sign: 7c1b2a3d4e5f60718293a4b5c6d7e8f9
Language: en
 
<?xml version="1.0" encoding="UTF-8"?><nfeProc xmlns="http://www.portalfiscal.inf.br/nfe" versao="4.00"><NFe>...</NFe><protNFe versao="4.00">...</protNFe></nfeProc>

Equivalent curl:

APP_SECRET="sk_live_9f8e7d6c5b4a"
PATH_SIGNED="/openapi/v3/consultas/nf-e/xml"
BODY=$(tr -d '\r\n' < invoice.xml)
TS=$(date +%s)
SIGN=$(printf '%s' "${APP_SECRET}${PATH_SIGNED}${BODY}${TS}" | md5sum | cut -d' ' -f1)
 
curl -X POST "https://api.v2.tffiscal.com${PATH_SIGNED}" \
  -H "Content-Type: application/xml" \
  -H "token: ${APP_SECRET}" \
  -H "timestamp: ${TS}" \
  -H "sign: ${SIGN}" \
  -H "Language: en" \
  --data-binary @invoice.xml

Success response (HTTP 200)

HTTP 200 means the request was accepted — not that the invoice passed. A well-formed XML that fails validation still returns 200; the verdict is in the validation block. Never branch on the HTTP status to decide validity.

{
  "tipo": "NF-e",
  "modelo": "55",
  "status": "Autorizada",
  "statusDescription": "Invoice authorized",
  "ambienteEmissao": "Producao",
  "numero": "1006122",
  "serie": "2",
  "dataEmissao": "2024-11-22T11:20:05-03:00",
  "chaveAcesso": "35260764962869000108550990001366171195929648",
  "emitente": {
    "nome": "EMPRESA EXEMPLO LTDA",
    "cpfCnpj": "64962869000108",
    "inscricaoEstadual": "123456789012",
    "telefone": "1133334444",
    "endereco": {
      "uf": "SP", "cidade": "SAO PAULO", "logradouro": "RUA EXEMPLO",
      "numero": "100", "complemento": null, "bairro": "CENTRO", "cep": "01001000"
    }
  },
  "destinatario": { "...": "same structure as emitente, plus email" },
  "itens": [
    {
      "cfop": "5102",
      "codigo": "SKU-001",
      "descricao": "PRODUTO EXEMPLO",
      "quantidade": 2.0,
      "valorUnitario": 50.00,
      "descontos": 0.00,
      "valorTotal": 100.00
    }
  ],
  "dataAutorizacao": "2024-11-22T11:20:31-03:00",
  "protocolo": { "numero": "135240001234567", "digestValue": "oAEE...HwY=" },
  "valorTotal": 100.00,
  "validation": {
    "fileAccessible": true,
    "xmlWellFormed": true,
    "schemaValid": true,
    "signatureValid": true,
    "accessKeyValid": true,
    "protocolPresent": true,
    "protocolValid": true,
    "xmlVersion": "4.00",
    "validationStatus": "PENDING_SEFAZ",
    "validationStatusDescription": "Tier-1 validation passed, awaiting tax authority verification",
    "errors": [],
    "warnings": []
  }
}

Field reference (top level):

Party object (emitente / destinatario):

Address object (endereco):

Line item object (itens[] element):

Protocol object (protocolo):

Amount semantics: line-level itens[].valorTotal is the gross line amount (vProd, before discount); root-level valorTotal is the net invoice total (vNF, after discount). The difference equals the total discount.

The validation block

Issue object (errors[] / warnings[] element):

Chave lookup

Returns invoice data for a 44-digit access key. Pure query endpoint: the response carries no validation block; verification verdicts are delivered exclusively via webhook.

Request

GET /openapi/v3/consultas/nf-e/{chave}
token / timestamp / sign        (GET → body is the empty string; the chave is part of the signed path)

Complete worked example. Given:

app_secret = sk_live_9f8e7d6c5b4a
chave      = 35260764962869000108550990001366171195929648
timestamp  = 1784906308

Step 1 — build the signing string:

sign_input = "sk_live_9f8e7d6c5b4a"
           + "/openapi/v3/consultas/nf-e/35260764962869000108550990001366171195929648"
           + ""
           + "1784906308"

sign = md5Hex(sign_input)        e.g. → 3f2a9c1d8b7e6f5a4c3d2e1f0a9b8c7d

Step 2 — send the request:

GET /openapi/v3/consultas/nf-e/35260764962869000108550990001366171195929648 HTTP/1.1
Host: api.v2.tffiscal.com
token: sk_live_9f8e7d6c5b4a
timestamp: 1784906308
sign: 3f2a9c1d8b7e6f5a4c3d2e1f0a9b8c7d
Language: en

Equivalent curl:

APP_SECRET="sk_live_9f8e7d6c5b4a"
CHAVE="35260764962869000108550990001366171195929648"
TS=$(date +%s)
SIGN=$(printf '%s' "${APP_SECRET}/openapi/v3/consultas/nf-e/${CHAVE}${TS}" | md5sum | cut -d' ' -f1)
 
curl -X GET \
  "https://api.v2.tffiscal.com/openapi/v3/consultas/nf-e/${CHAVE}" \
  -H "token: ${APP_SECRET}" \
  -H "timestamp: ${TS}" \
  -H "sign: ${SIGN}" \
  -H "Language: en"

Data sources and outcomes

The platform resolves the chave through the following tiers; the first hit is returned:

Success response (HTTP 200)

{
  "tipo": "NF-e",
  "modelo": "55",
  "status": "Autorizada",
  "statusDescription": "Invoice authorized",
  "ambienteEmissao": "Producao",
  "numero": "136617",
  "serie": "99",
  "dataEmissao": "2026-07-23T11:20:05-03:00",
  "chaveAcesso": "35260764962869000108550990001366171195929648",
  "emitente": {
    "nome": "EMPRESA EXEMPLO LTDA",
    "email": null,
    "cpfCnpj": "64962869000108",
    "inscricaoMunicipal": null,
    "inscricaoEstadual": "123456789012",
    "telefone": "1133334444",
    "endereco": {
      "uf": "SP",
      "cidade": "SAO PAULO",
      "logradouro": "RUA EXEMPLO",
      "numero": "100",
      "complemento": null,
      "bairro": "CENTRO",
      "cep": "01001000"
    }
  },
  "destinatario": {
    "nome": "COMPRADOR EXEMPLO",
    "email": "buyer@example.com",
    "cpfCnpj": "39053344705",
    "inscricaoMunicipal": null,
    "inscricaoEstadual": null,
    "telefone": null,
    "endereco": {
      "uf": "RJ",
      "cidade": "RIO DE JANEIRO",
      "logradouro": "AV RIO BRANCO",
      "numero": "156",
      "complemento": "APT 501",
      "bairro": "CENTRO",
      "cep": "20040030"
    }
  },
  "itens": [
    {
      "cfop": "6102",
      "codigo": "SKU-001",
      "descricao": "PRODUTO EXEMPLO",
      "quantidade": 2.0,
      "valorUnitario": 50.00,
      "descontos": 0.00,
      "valorTotal": 100.00
    }
  ],
  "dataAutorizacao": "2026-07-23T11:20:31-03:00",
  "protocolo": {
    "numero": "135260001234567",
    "digestValue": "oAEEuC3tGmb2W7ZJxWkNVWuBHwY="
  },
  "valorTotal": 100.00
}

The top-level fields are the same as for XML verification, minus the validation block; chaveAcesso echoes the path variable. The nested Party / Address / Line item / Protocol objects are defined once under XML verification and are identical here.

Error responses

Unknown chave (no source hit):

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

Malformed chave (wrong length / character / check digit — rejected locally, no lookup attempted):

{ "code": 10015104, "message": "Access key structure or check digit invalid" }

Authentication failures (401 / 403 / 429) use the platform envelope — see Authentication & Signing.

Receiving the final verdict

When Tier-2 SEFAZ verification settles, the platform POSTs the invoice.verify.completed event to your configured webhook URL. This is the only push channel for final verdicts; the chave lookup can serve as a polling fallback. Headers, payload and receiver requirements are documented in Webhooks — Verification verdict event.

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 header forceRevalidate: true on the XML 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 reference

Request-level errors — XML endpoint (HTTP 400, bare shape)

The request never enters validation.

Request-level errors — chave lookup (HTTP 400, bare shape)

Tier-1 validation errors

Returned with HTTP 200 inside validation.errors[]. These are not transport errors: the request succeeded, the document failed. All are blocking (terminal REJECTED) except PROTOCOL_MISSING, which is a warning.

HTTP status quick reference

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 → 200 with invoice data; a nonexistent chave → 400 + 10015004; a chave with a wrong check digit → 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 → reused verdict; submit with forceRevalidate: true → re-verification, new verdict via webhook.
7. Failure paths: call with a wrong sign → 401 (code 10009003); call an unsubscribed endpoint → 403 (code 10009005).

Troubleshooting

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 VALIDATION_ERROR a problem with the invoice? No. It means the platform’s verification channel failed (e.g. SEFAZ throttling); the invoice itself was not judged. Resubmit later with forceRevalidate: true.

Signature never matches (401, code 10009003)? The most frequent cause on this endpoint is CR/LF not stripped from the XML before concatenation, followed by a GET that concatenated "null" instead of the empty string. The full checklist is in Authentication & Signing.