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 group | Success shape |
|---|---|
| Company registration, webhook registration | Bare object ({ "empresaId": ... }, { "webHookId": ... }) |
| Certificate association, NF-e / CT-e / DC-e issuance and cancellation | HTTP 200 with no body; the result arrives asynchronously |
| NF-e / CT-e / DC-e query, correction letter and event registration | Bare object: the document, the protocol or the event list |
| XML verification, chave lookup | Bare object: the parsed invoice (XML verification adds a validation block) |
| CNPJ lookup, CPF lookup | Bare 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:
[{ "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:
{ "code": 10015004, "message": "Invoice not found" }
| Field | Type | Description |
|---|---|---|
code | integer | Platform error code |
message | string | Human-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:
{ "success": true, "message": "OK", "data": { } }
{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }
| Field | Type | Presence | Description |
|---|---|---|---|
success | boolean | always | false for every error |
errorType | integer | on error | Error class, see Error typing |
code | integer | on error | Platform error code, see Error codes |
message | string | always | Human-readable explanation, localized |
data | object | null | on success | Endpoint 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:
- Treat HTTP 400 and above as failure, and additionally
success: falsewhen the body is an envelope. - Parse the body as JSON. If it is an array, read
codigofrom each entry; if it is an object, readcode. - Branch on the code, never on
message/mensagemtext (they are localized).
Error typing (errorType)
Envelope errors carry an errorType field that classifies the failure source:
| errorType | Class | Meaning |
|---|---|---|
| 1 | API error | Authentication, authorization or business rejection by TF Fiscal |
| 2 | SEFAZ rejection | The Brazilian tax authority rejected the operation |
| 3 | System fault | Unexpected platform failure; safe to retry with backoff |
| 4 | Validation failure | Request field validation failed |
HTTP status quick reference
| HTTP | Scenario | Body shape |
|---|---|---|
| 200 | Request accepted; for XML verification this includes a failed validation (check the validation block) | Bare data, or no body |
| 400 | Request invalid or business rule violated | [{codigo, mensagem}] (issuing) or {code, message} (verification / identity) |
| 404 | empresaId / document id not found (issuing family) | [{codigo, mensagem}] |
| 401 | Authentication failed (token / sign / timestamp), or an invalid or expired download link | Platform envelope |
| 403 | Application disabled / not effective / integrator disabled / not subscribed | Platform envelope |
| 422 / 428 / 451 | CPF lookup withheld by law (holder aged 16 to 17 / age not verifiable / holder under 16); do not retry | {code, message}, no personal fields |
| 429 | Rate limit exceeded, or the application is in a cooldown; carries Retry-After and X-RateLimit-* headers, see Rate limiting and backoff | Platform envelope |
| 503 | Upstream data source unavailable (identity, 10016020) or file not rendered yet (download, 10009037); retry after Retry-After | {code, message} or platform envelope |
| 5xx | Platform-side fault | Retry with backoff; if persistent, contact the platform with the failing timestamp and path |
Idempotency
- NF-e issuance is idempotent on the request
idyou generate: re-submitting the sameidreuses the original task. If the previous attempt was denied (Negada), resending the sameidwith 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 withcodigo10004032. - CT-e and DC-e issuance are idempotent on
idas well: an identical message reuses the original task, a different message under the sameidis rejected (10017030for CT-e,10019030for 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 headerforceRevalidate: trueon 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-1REJECTEDhas 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:
| Level | Scope | When not set |
|---|---|---|
| Application | Every call made by the application | Unlimited |
| Endpoint group | The 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 to2 × ratewhen 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:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | The rate of the level in effect (requests per second) |
X-RateLimit-Remaining | Tokens currently left at that level (rounded down) |
X-RateLimit-Burst | The burst (bucket capacity) of that level |
X-RateLimit-Reset | Seconds until the next token is available (rounded up, at least 1); during a cooldown, the seconds left in the cooldown |
Retry-After | 429 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), whererateis 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-AfterandX-RateLimit-Resetcarry 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
- On 429, wait for
Retry-Afterseconds, then retry; - 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; - Pace your calls: use
X-RateLimit-Remainingto regulate your sending rate, and do not keep sending above your quota; - A request answered with 429 was not processed and must be submitted again (with a fresh
timestampandsign).
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
codigo10004002; retry later. - Timestamp window: requests with a
timestampbeyond ±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.
| Value | Language | Notes |
|---|---|---|
pt | Portuguese | Default language; subtags such as pt-BR are accepted too |
en | English | Subtags such as en-US are accepted too |
zh | Chinese | Subtags such as zh-CN are accepted too |
es | Spanish | Subtags 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,dataAutorizacaoof issued documents, webhookoccurred_at,verifiedAt, echoserverTime) are ISO-8601 UTC with theZsuffix, 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 example2026-07-23T11:20:05-03:00. - The
timestamprequest 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 documentidyou 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,cpfandchaveare digit-only strings without formatting characters; the CPF date of birth (nascimento) isDDMMYYYY.
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:
| Positions | Length | Field | Meaning |
|---|---|---|---|
| 1 to 2 | 2 | cUF | IBGE code of the issuing state (e.g. 35 = SP) |
| 3 to 6 | 4 | AAMM | Year and month of issue (YYMM) |
| 7 to 20 | 14 | CNPJ | Issuer CNPJ |
| 21 to 22 | 2 | mod | Fiscal document model (55 = NF-e) |
| 23 to 25 | 3 | serie | Invoice series |
| 26 to 34 | 9 | nNF | Invoice number |
| 35 | 1 | tpEmis | Emission type |
| 36 to 43 | 8 | cNF | Random numeric code |
| 44 | 1 | cDV | Check 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
modvalue.
File download links
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.
