TF Fiscal
Documentation

Getting started

General conventions

The two response shapes (bare responses vs. platform envelope), error shapes, error typing, HTTP status reference, idempotency, rate limits, localization, data types, the NF-e access key structure and file download links.

Conventions shared by the endpoints of the TF Fiscal Open API.

Response shapes

The API has two response shapes, and which one you receive depends on the endpoint and on which layer produced the response.

Bare responses (standard endpoints)

All standard endpoints (companies, NF-e, CT-e, DC-e, verification, identity, webhook registration) respond without an envelope:

Endpoint groupSuccess shape
Company registration, webhook registrationBare object ({ "empresaId": ... }, { "webHookId": ... })
Certificate association, NF-e / CT-e / DC-e issuance and cancellationHTTP 200 with no body; the result arrives asynchronously
NF-e / CT-e / DC-e query, correction letter and event registrationBare object: the document, the protocol or the event list
XML verification, chave lookupBare object: the parsed invoice (XML verification adds a validation block)
CNPJ lookup, CPF lookupBare object: the registry record

Business and request-level errors of the standard endpoints come in two error shapes, by endpoint family.

Issuing family (companies, NF-e, CT-e, DC-e, webhook registration; HTTP 400 / 404): an array of errors, each with codigo and mensagem. Request-body validation failures produce one entry per field:

json
[
{ "codigo": "10004001", "mensagem": "Nota fiscal não encontrada" }
]

codigo is a string carrying the platform error code as digits, for example 10003004 for an invalid city / state, 10003008 for a certificate password mismatch and 10004001 for an invoice not found.

Verification and identity families (HTTP 400, and 422 / 428 / 451 / 503 for identity): a bare object with code and message:

json
{ "code": 10015004, "message": "Invoice not found" }
FieldTypeDescription
codeintegerPlatform error code
messagestringHuman-readable explanation, localized

Platform envelope

Used by the echo endpoint (POST /openapi/demo/echo) for every response, by the Offline NFC-e open API endpoints (/openapi/v2/empresas/{empresaId}/nfce-offline and the paths below it) for every response, by the file download endpoint for its failures, and by the platform gateway for authentication-layer errors on every endpoint (HTTP 401 / 403 / 429), which are produced before the request reaches the endpoint:

json
{ "success": true, "message": "OK", "data": { } }
json
{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }
FieldTypePresenceDescription
successbooleanalwaysfalse for every error
errorTypeintegeron errorError class, see Error typing
codeintegeron errorPlatform error code, see Error codes
messagestringalwaysHuman-readable explanation, localized
dataobject | nullon successEndpoint payload; not populated on errors

The Offline NFC-e open API endpoints also return business errors with HTTP 200 and success = false; a missing resource returns 404 and field validation returns 400. When calling these endpoints always check success, not just the HTTP status.

Handling both shapes

Your error handler must accept the envelope and the bare error shapes. A robust rule:

  1. Treat HTTP 400 and above as failure, and additionally success: false when the body is an envelope.
  2. Parse the body as JSON. If it is an array, read codigo from each entry; if it is an object, read code.
  3. Branch on the code, never on message / mensagem text (they are localized).

Error typing (errorType)

Envelope errors carry an errorType field that classifies the failure source:

errorTypeClassMeaning
1API errorAuthentication, authorization or business rejection by TF Fiscal
2SEFAZ rejectionThe Brazilian tax authority rejected the operation
3System faultUnexpected platform failure; safe to retry with backoff
4Validation failureRequest field validation failed

HTTP status quick reference

HTTPScenarioBody shape
200Request accepted; for XML verification this includes a failed validation (check the validation block)Bare data, or no body
400Request invalid or business rule violated[{codigo, mensagem}] (issuing) or {code, message} (verification / identity)
404empresaId / document id not found (issuing family)[{codigo, mensagem}]
401Authentication failed (token / sign / timestamp), or an invalid or expired download linkPlatform envelope
403Application disabled / not effective / integrator disabled / not subscribedPlatform envelope
422 / 428 / 451CPF lookup withheld by law (holder aged 16 to 17 / age not verifiable / holder under 16); do not retry{code, message}, no personal fields
429Rate limit exceeded, or the application is in a cooldown; carries Retry-After and X-RateLimit-* headers, see Rate limiting and backoffPlatform envelope
503Upstream data source unavailable (identity, 10016020) or file not rendered yet (download, 10009037); retry after Retry-After{code, message} or platform envelope
5xxPlatform-side faultRetry with backoff; if persistent, contact the platform with the failing timestamp and path

Idempotency

  • NF-e issuance is idempotent on the request id you generate: re-submitting the same id reuses the original task. If the previous attempt was denied (Negada), resending the same id with corrected fields issues again with the new payload, no new id is needed. Changing key fields such as the recipient while the previous attempt is still processing or already authorized is rejected with codigo 10004032.
  • CT-e and DC-e issuance are idempotent on id as well: an identical message reuses the original task, a different message under the same id is rejected (10017030 for CT-e, 10019030 for DC-e), and a terminal failure (Falha) reopens the task with the new message.
  • XML verification is idempotent on the access key (chave): resubmitting while a verification is in progress returns the current progress, and terminal verdicts are reused by kind: cancelled / denied / voided verdicts and verdicts where SEFAZ does not accept queries for the invoice are reused for as long as the platform keeps the verification record, any other verdict for 24 hours from the moment it was reached; see Idempotency and re-verification. Reuse applies only to resubmissions with identical content: if the XML submitted for a chave differs from the previous one, it is fully re-verified automatically (cancelled / denied / voided verdicts excepted). To force a re-check, send the header forceRevalidate: true on the XML endpoint (the header is not part of the signature); cancelled / denied / voided verdicts are reused even with that header. The chave lookup is a fixed GET and has no re-verification channel; to force a re-check, resubmit through the XML endpoint. A Tier-1 REJECTED has no Tier-2 record; re-verification requires resubmitting the XML.
  • Webhook deliveries are idempotent by event_id: every retry and every fan-out target of one event carries the same value, so deduplicate on it. See Webhooks.

Rate limiting and backoff

Two-level quotas and token buckets

Quotas are set per application and per endpoint group. A request is accepted only when both levels allow it:

LevelScopeWhen not set
ApplicationEvery call made by the applicationUnlimited
Endpoint groupThe application's calls to one group of endpoints (for example, both NF-e verification endpoints belong to the "invoice verification" group)Only the application level applies

Both levels are token buckets:

  • rate: tokens added per second, i.e. the sustained number of requests accepted per second;
  • burst: bucket capacity, i.e. the largest number of requests you can send back to back (available again after a quiet period); defaults to 2 × rate when not set;
  • every accepted request consumes 1 token. When no token is left the request gets HTTP 429 (code 10009006); rejected requests do not consume tokens.

The actual quotas are agreed with the platform when the application is set up. File downloads count against the application throttle in their own group and are not billed.

Rate-limit headers

For an application with a quota, every response (both 200 and 429) carries:

HeaderMeaning
X-RateLimit-LimitThe rate of the level in effect (requests per second)
X-RateLimit-RemainingTokens currently left at that level (rounded down)
X-RateLimit-BurstThe burst (bucket capacity) of that level
X-RateLimit-ResetSeconds until the next token is available (rounded up, at least 1); during a cooldown, the seconds left in the cooldown
Retry-After429 only: the minimum number of seconds to wait. 1 when the bucket is empty; during a cooldown, the seconds left in the cooldown

When both levels have a quota, an accepted response reports the level with fewer tokens left, and a 429 reports the level that rejected it. Applications without any quota get none of these headers.

Cooldown

An application that ignores 429 and keeps resending at a high rate is put on a temporary cooldown:

  • Rule: when the application's rejections in the last 10 seconds reach the threshold, it enters a 30-second cooldown. The threshold is max(100, 10 × rate), where rate is the smaller of the application and endpoint-group rates. For example, an application with a quota of 100/s enters a cooldown after 1,000 rejections in 10 seconds, the same as calling at more than twice the quota for 10 seconds straight. An occasional overshoot does not trigger it.
  • During the cooldown, every call of the application that is subject to a quota is answered with 429 (code 10009006) right away and is not processed. Retry-After and X-RateLimit-Reset carry the seconds left in the cooldown and count down.
  • The cooldown ends by itself and token-bucket checks resume; sustained overshooting triggers another cooldown.
  • These are the default parameters; the platform may adjust them.

What your client should do

  1. On 429, wait for Retry-After seconds, then retry;
  2. If the retry still gets 429, back off exponentially on top of Retry-After (e.g. 1, 2, 4 seconds… capped at 30 seconds) and add random jitter, so that parallel workers do not wake up and collide again;
  3. Pace your calls: use X-RateLimit-Remaining to regulate your sending rate, and do not keep sending above your quota;
  4. A request answered with 429 was not processed and must be submitted again (with a fresh timestamp and sign).

429 is not billed: rate-limited calls (including those during a cooldown) are not charged.

Other limits

  • Per-CNPJ anti-flood: if a company accumulates too many pending issuance tasks, new submissions are rejected with codigo 10004002; retry later.
  • Timestamp window: requests with a timestamp beyond ±300 s of the server clock are rejected (10009001).
  • 401 and 403 are configuration errors; retrying them without a fix only consumes quota.

Response localization

message, mensagem and *Description fields follow the request language: the Language header (zh / en / pt / es) takes precedence, then Accept-Language (supports pt-BR and q-values). Without a language header, responses default to Portuguese (pt). The language headers are not part of the signature.

ValueLanguageNotes
ptPortugueseDefault language; subtags such as pt-BR are accepted too
enEnglishSubtags such as en-US are accepted too
zhChineseSubtags such as zh-CN are accepted too
esSpanishSubtags such as es-ES and spa are accepted too

Case-insensitive. An unrecognized Language value falls through to Accept-Language; if that is unrecognized as well, the response is in Portuguese, with no error.

Webhook payloads carry only language-independent enum values; there are no *Description fields there. For programmatic decisions always use codes and enum fields (code, codigo, status, validationStatus, errors[].code, situacao.codigo), never description text.

Timestamps and data types

  • Times produced by the platform (dataCriacao, dataAutorizacao of issued documents, webhook occurred_at, verifiedAt, echo serverTime) are ISO-8601 UTC with the Z suffix, in every environment.
  • Times parsed from a third-party document by the verification API (dataEmissao, dataAutorizacao) are returned verbatim with the document's UTC offset, for example 2026-07-23T11:20:05-03:00.
  • The timestamp request header is Unix time in seconds, not milliseconds.
  • Identifiers are strings even when numeric (empresaId, webHookId, event_id), to avoid JavaScript number precision loss. Treat all ids as opaque strings; the document id you generate is a string as well.
  • Document numbers (numero) and series (serie) are strings. Amounts and quantities are JSON numbers.
  • Path variables such as cnpj, cpf and chave are digit-only strings without formatting characters; the CPF date of birth (nascimento) is DDMMYYYY.

The NF-e access key (chave)

The chave de acesso is the nationally unique, 44-digit identifier of an NF-e. It appears as chaveAcesso in query and verification responses and as the path variable of the chave lookup. Its structure:

PositionsLengthFieldMeaning
1 to 22cUFIBGE code of the issuing state (e.g. 35 = SP)
3 to 64AAMMYear and month of issue (YYMM)
7 to 2014CNPJIssuer CNPJ
21 to 222modFiscal document model (55 = NF-e)
23 to 253serieInvoice series
26 to 349nNFInvoice number
351tpEmisEmission type
36 to 438cNFRandom numeric code
441cDVCheck digit (modulo 11)

Notes:

  • Always store and transmit the chave as a 44-character string (leading zeros are significant).
  • The chave lookup validates length, characters and the check digit locally before any lookup is attempted; a malformed chave returns HTTP 400 with code 10015104.
  • CT-e (model 57) and DC-e (model 99) keys share the same 44-digit layout with their own mod value.

Download links in query responses and callback payloads (linkDanfe, linkDownloadXml, linkDacce and their CT-e / DC-e counterparts) look like https://api.v2.tffiscal.com/openapi/files/{kind}/{ref}?token=.... They need no signature headers: a plain GET that follows the 302 redirect is enough. The token is bound to the path, the integrator and the application, so use the link exactly as returned. Links are valid for 7 days by default and every query issues fresh ones; an expired link returns 401 with 10009036. Details: File download.