TF Fiscal
Documentação

Primeiros passos

Convenções gerais

Os dois formatos de resposta (respostas simples vs. envelope da plataforma), formatos de erro, tipificação de erros, referência de status HTTP, idempotência, limites de taxa, localização, tipos de dados, a estrutura da chave de acesso da NF-e e os links de download de arquivos.

Convenções compartilhadas pelos endpoints da Open API da TF Fiscal.

Formatos de resposta

A API tem dois formatos de resposta, e qual deles você recebe depende do endpoint e da camada que produziu a resposta.

Respostas simples (endpoints padrão)

Todos os endpoints padrão (empresas, NF-e, CT-e, DC-e, verificação, consulta cadastral, registro de webhook) respondem sem envelope:

Grupo de endpointsFormato de sucesso
Cadastro de empresa, registro de webhookObjeto simples ({ "empresaId": ... }, { "webHookId": ... })
Vinculação de certificado, emissão e cancelamento de NF-e / CT-e / DC-eHTTP 200 sem corpo; o resultado chega de forma assíncrona
Consulta de NF-e / CT-e / DC-e, registro de carta de correção e de eventosObjeto simples: o documento, o protocolo ou a lista de eventos
Verificação por XML, consulta por chaveObjeto simples: a nota interpretada (a verificação por XML acrescenta o bloco validation)
Consulta de CNPJ, consulta de CPFObjeto simples: o registro cadastral

Os erros de negócio e de requisição dos endpoints padrão vêm em dois formatos de erro, conforme a família do endpoint.

Família de emissão (empresas, NF-e, CT-e, DC-e, registro de webhook; HTTP 400 / 404): um array de erros, cada um com codigo e mensagem. Falhas de validação do corpo produzem uma entrada por campo:

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

codigo é uma string com o código de erro da plataforma em dígitos, por exemplo 10003004 para cidade / estado inválido, 10003008 para senha do certificado incorreta e 10004001 para nota não encontrada.

Famílias de verificação e consulta cadastral (HTTP 400, e 422 / 428 / 451 / 503 na consulta cadastral): um objeto simples com code e message:

json
{ "code": 10015004, "message": "Invoice not found" }
CampoTipoDescrição
codeintegerCódigo de erro da plataforma
messagestringExplicação legível, localizada

Envelope da plataforma

Usado pelo endpoint de echo (POST /openapi/demo/echo) em toda resposta, pelos endpoints da NFC-e offline (/openapi/v2/empresas/{empresaId}/nfce-offline e caminhos abaixo dele) em toda resposta, pelo endpoint de download de arquivos nas suas falhas e pelo gateway da plataforma para os erros da camada de autenticação em todo endpoint (HTTP 401 / 403 / 429), produzidos antes de a requisição chegar ao endpoint:

json
{ "success": true, "message": "OK", "data": { } }
json
{ "success": false, "errorType": 1, "code": 10009003, "message": "Signature error" }
CampoTipoPresençaDescrição
successbooleansemprefalse em todo erro
errorTypeintegerem erroClasse do erro, veja Tipificação de erros
codeintegerem erroCódigo de erro da plataforma, veja Códigos de erro
messagestringsempreExplicação legível, localizada
dataobject | nullem sucessoCarga do endpoint; não preenchida em erros

Nos endpoints da NFC-e offline, os erros de negócio também voltam com HTTP 200 e success = false; recurso inexistente volta com 404 e validação de campo com 400. Ao chamar essas operações verifique success, não só o status HTTP.

Tratando os dois formatos

O seu tratador de erros deve aceitar o envelope e os formatos de erro simples. Uma regra robusta:

  1. Trate HTTP 400 ou superior como falha e, adicionalmente, success: false quando o corpo for um envelope.
  2. Interprete o corpo como JSON. Se for um array, leia codigo de cada entrada; se for um objeto, leia code.
  3. Ramifique pelo código, nunca pelo texto de message / mensagem (eles são localizados).

Tipificação de erros (errorType)

Os erros em envelope carregam um campo errorType que classifica a origem da falha:

errorTypeClasseSignificado
1Erro de APIRejeição de autenticação, autorização ou de negócio pela TF Fiscal
2Rejeição da SEFAZA autoridade fiscal brasileira rejeitou a operação
3Falha de sistemaFalha inesperada da plataforma; seguro repetir com backoff
4Falha de validaçãoA validação dos campos da requisição falhou

Referência rápida de status HTTP

HTTPCenárioFormato do corpo
200Requisição aceita; na verificação por XML isso inclui uma validação reprovada (verifique o bloco validation)Dados simples, ou sem corpo
400Requisição inválida ou regra de negócio violada[{codigo, mensagem}] (emissão) ou {code, message} (verificação / consulta cadastral)
404empresaId / id do documento não encontrado (família de emissão)[{codigo, mensagem}]
401Falha de autenticação (token / sign / timestamp), ou link de download inválido ou vencidoEnvelope da plataforma
403Aplicação desativada / não vigente / integrador desativado / não subscritoEnvelope da plataforma
422 / 428 / 451Consulta de CPF retida por lei (titular de 16 a 17 anos / idade não verificável / titular menor de 16); não repita{code, message}, sem campos pessoais
429Limite de taxa excedido, ou aplicação em bloqueio temporário; traz os cabeçalhos Retry-After e X-RateLimit-*, veja Limite de taxa e backoffEnvelope da plataforma
503Fonte de dados upstream indisponível (consulta cadastral, 10016020) ou arquivo ainda não renderizado (download, 10009037); repita após Retry-After{code, message} ou envelope da plataforma
5xxFalha do lado da plataformaRepita com backoff; se persistir, contate a plataforma com o timestamp e o caminho da falha

Idempotência

  • A emissão de NF-e é idempotente pelo id da requisição que você gera: reenviar o mesmo id reutiliza a tarefa original. Se a tentativa anterior foi negada (Negada), reenviar o mesmo id com os campos corrigidos emite de novo com a nova carga, sem necessidade de novo id. Alterar campos-chave como o destinatário enquanto a tentativa anterior ainda está em processamento ou já foi autorizada é rejeitado com codigo 10004032.
  • A emissão de CT-e e DC-e também é idempotente pelo id: uma mensagem idêntica reutiliza a tarefa original, uma mensagem diferente sob o mesmo id é rejeitada (10017030 para CT-e, 10019030 para DC-e), e uma falha terminal (Falha) reabre a tarefa com a nova mensagem.
  • A verificação por XML é idempotente pela chave de acesso (chave): reenviar enquanto uma verificação está em andamento devolve o progresso atual, e vereditos terminais são reutilizados conforme o tipo: vereditos de nota cancelada / denegada / inutilizada e vereditos em que a SEFAZ não aceita consultas da nota são reutilizados enquanto a plataforma mantiver o registro da verificação, e os demais por 24 horas a partir do momento em que foram obtidos; veja Idempotência e nova verificação. A reutilização vale apenas para reenvios com conteúdo idêntico: se o XML enviado para uma chave for diferente do anterior, ele é verificado de novo por completo automaticamente (exceto vereditos de nota cancelada / denegada / inutilizada). Para forçar uma nova verificação, envie o cabeçalho forceRevalidate: true no endpoint de XML (o cabeçalho não faz parte da assinatura); vereditos de nota cancelada / denegada / inutilizada são reutilizados mesmo com esse cabeçalho. A consulta por chave é um GET fixo e não tem canal de reverificação; para forçar uma nova verificação, reenvie pelo endpoint de XML. Um REJECTED da camada 1 não tem registro de camada 2; a reverificação exige reenviar o XML.
  • As entregas de webhook são idempotentes por event_id: toda tentativa e todo destino de um mesmo evento carregam o mesmo valor, então deduplique por ele. Veja Webhooks.

Limite de taxa e backoff

Cotas em dois níveis e token bucket

As cotas são definidas por aplicação e por grupo de endpoints. Uma requisição só é aceita quando os dois níveis permitem:

NívelAbrangênciaQuando não definido
AplicaçãoTodas as chamadas feitas pela aplicaçãoSem limite
Grupo de endpointsAs chamadas da aplicação a um grupo de endpoints (por exemplo, os dois endpoints de verificação de NF-e pertencem ao grupo "verificação de notas")Vale só o nível da aplicação

Os dois níveis são token buckets (baldes de tokens):

  • rate: tokens adicionados por segundo, ou seja, o número sustentado de requisições aceitas por segundo;
  • burst: capacidade do balde, ou seja, o maior número de requisições que você pode enviar em sequência (disponível de novo após um período ocioso); quando não definido, vale 2 × rate;
  • toda requisição aceita consome 1 token. Quando não sobra token, a requisição recebe HTTP 429 (código 10009006); requisições rejeitadas não consomem tokens.

As cotas efetivas são combinadas com a plataforma quando a aplicação é configurada. Downloads de arquivos contam no limite da aplicação em grupo próprio e não são cobrados.

Cabeçalhos de limite de taxa

Para uma aplicação com cota, toda resposta (200 e 429) traz:

CabeçalhoSignificado
X-RateLimit-LimitO rate do nível em vigor (requisições por segundo)
X-RateLimit-RemainingTokens restantes nesse nível (arredondado para baixo)
X-RateLimit-BurstO burst (capacidade do balde) desse nível
X-RateLimit-ResetSegundos até o próximo token ficar disponível (arredondado para cima, no mínimo 1); durante um bloqueio temporário, os segundos que faltam para ele terminar
Retry-AfterSó no 429: o número mínimo de segundos a esperar. 1 quando o balde está vazio; durante um bloqueio temporário, os segundos que faltam para ele terminar

Quando os dois níveis têm cota, uma resposta aceita informa o nível com menos tokens restantes, e um 429 informa o nível que o rejeitou. Aplicações sem nenhuma cota não recebem esses cabeçalhos.

Bloqueio temporário

Uma aplicação que ignora o 429 e continua reenviando em ritmo alto entra em bloqueio temporário (cooldown):

  • Regra: quando as rejeições da aplicação nos últimos 10 segundos atingem o limiar, ela entra em um bloqueio de 30 segundos. O limiar é max(100, 10 × rate), em que rate é o menor entre o da aplicação e o do grupo de endpoints. Por exemplo, uma aplicação com cota de 100/s entra em bloqueio após 1.000 rejeições em 10 segundos, o mesmo que chamar a mais do que o dobro da cota por 10 segundos seguidos. Um excesso ocasional não o dispara.
  • Durante o bloqueio, toda chamada da aplicação sujeita a cota recebe 429 (código 10009006) imediatamente e não é processada. Retry-After e X-RateLimit-Reset trazem os segundos que faltam para o bloqueio terminar e vão diminuindo.
  • O bloqueio termina sozinho e as checagens de token bucket voltam; excesso sustentado dispara um novo bloqueio.
  • Esses são os parâmetros padrão; a plataforma pode ajustá-los.

O que o seu cliente deve fazer

  1. Ao receber 429, espere Retry-After segundos e repita;
  2. Se a repetição ainda receber 429, faça backoff exponencial sobre o Retry-After (por exemplo 1, 2, 4 segundos… até 30 segundos) e adicione jitter aleatório, para que workers paralelos não acordem juntos e colidam de novo;
  3. Controle o ritmo: use X-RateLimit-Remaining para regular a sua taxa de envio e não continue enviando acima da cota;
  4. Uma requisição respondida com 429 não foi processada e precisa ser enviada de novo (com timestamp e sign novos).

429 não é cobrado: chamadas limitadas (inclusive durante um bloqueio temporário) não são cobradas.

Outros limites

  • Anti-flood por CNPJ: se uma empresa acumular tarefas de emissão pendentes demais, novos envios são rejeitados com codigo 10004002; repita mais tarde.
  • Janela do timestamp: requisições com timestamp fora de ±300 s do relógio do servidor são rejeitadas (10009001).
  • 401 e 403 são erros de configuração; repeti-los sem corrigir só consome cota.

Localização das respostas

Os campos message, mensagem e *Description seguem o idioma da requisição: o cabeçalho Language (zh / en / pt / es) tem precedência, depois Accept-Language (aceita pt-BR e valores q). Sem cabeçalho de idioma, as respostas usam por padrão português (pt). Os cabeçalhos de idioma não fazem parte da assinatura.

ValorIdiomaObservação
ptPortuguêsIdioma padrão; subtags como pt-BR também são aceitas
enInglêsSubtags como en-US também são aceitas
zhChinêsSubtags como zh-CN também são aceitas
esEspanholSubtags como es-ES e spa também são aceitas

Sem diferenciar maiúsculas. Um valor de Language não reconhecido passa para Accept-Language; se este também não for reconhecido, a resposta sai em português, sem erro.

As cargas de webhook carregam apenas valores de enumeração independentes de idioma; não há campos *Description nelas. Para decisões programáticas, use sempre códigos e campos de enumeração (code, codigo, status, validationStatus, errors[].code, situacao.codigo), nunca texto descritivo.

Horários e tipos de dados

  • Horários produzidos pela plataforma (dataCriacao, dataAutorizacao dos documentos emitidos, occurred_at de webhook, verifiedAt, serverTime do echo) são ISO-8601 UTC com o sufixo Z, em todo ambiente.
  • Horários extraídos de um documento de terceiros pela API de verificação (dataEmissao, dataAutorizacao) são devolvidos sem alteração, com o fuso do documento, por exemplo 2026-07-23T11:20:05-03:00.
  • O cabeçalho timestamp da requisição é tempo Unix em segundos, não milissegundos.
  • Identificadores são strings mesmo quando numéricos (empresaId, webHookId, event_id), para evitar perda de precisão numérica em JavaScript. Trate todos os ids como strings opacas; o id de documento que você gera também é uma string.
  • Números de documento (numero) e séries (serie) são strings. Valores e quantidades são números JSON.
  • Variáveis de caminho como cnpj, cpf e chave são strings só de dígitos, sem caracteres de formatação; a data de nascimento do CPF (nascimento) é DDMMYYYY.

A chave de acesso da NF-e (chave)

A chave de acesso é o identificador nacionalmente único de 44 dígitos de uma NF-e. Ela aparece como chaveAcesso nas respostas de consulta e verificação e como variável de caminho da consulta por chave. Sua estrutura:

PosiçõesTamanhoCampoSignificado
1 a 22cUFCódigo IBGE do estado emissor (ex.: 35 = SP)
3 a 64AAMMAno e mês de emissão (AAMM)
7 a 2014CNPJCNPJ do emitente
21 a 222modModelo do documento fiscal (55 = NF-e)
23 a 253serieSérie da nota
26 a 349nNFNúmero da nota
351tpEmisTipo de emissão
36 a 438cNFCódigo numérico aleatório
441cDVDígito verificador (módulo 11)

Observações:

  • Armazene e transmita sempre a chave como uma string de 44 caracteres (zeros à esquerda são significativos).
  • A consulta por chave valida tamanho, caracteres e dígito verificador localmente antes de qualquer consulta; uma chave malformada devolve HTTP 400 com o código 10015104.
  • As chaves de CT-e (modelo 57) e DC-e (modelo 99) compartilham o mesmo layout de 44 dígitos com o seu próprio valor de mod.

Os links de download nas respostas de consulta e nas cargas de callback (linkDanfe, linkDownloadXml, linkDacce e seus equivalentes de CT-e / DC-e) têm o formato https://api.v2.tffiscal.com/openapi/files/{kind}/{ref}?token=.... Eles não precisam de cabeçalhos de assinatura: basta um GET simples que siga o redirecionamento 302. O token é vinculado ao caminho, ao integrador e à aplicação, então use o link exatamente como devolvido. Os links valem por 7 dias por padrão e toda consulta emite links novos; um link vencido devolve 401 com 10009036. Detalhes: Download de arquivos.