Primeiros passos

Ambientes

URL base da Open API da TF Fiscal e o modelo de ambiente de teste / produção por empresa.

URL base

Ambiente	URL base
Produção	`https://api.v2.tffiscal.com`

URL completa = URL base + caminho. O path usado na assinatura da requisição inclui o prefixo /openapi (sem host, sem query string), veja Autenticação. Todos os exemplos desta documentação usam essa URL base.

Ambiente da empresa (emissão)

A emissão de documentos fiscais no Brasil ocorre contra dois ambientes da SEFAZ, e a plataforma modela essa divisão por empresa, não por host da API:

Ambiente da empresa	Valor de `ambienteEmissao`	Finalidade	Validade fiscal
Teste	`Homologacao`	Testes de integração e homologação	Nenhuma, os documentos não têm valor fiscal
Produção	`Producao`	Emissão real de documentos fiscais	Total

Toda empresa cadastrada por Cadastrar empresa tem um ambiente atual. Empresas recém-cadastradas começam em teste; a mudança para produção é uma ação operacional da equipe TF Fiscal.
O ambienteEmissao de uma requisição de emissão deve corresponder ao ambiente atual da empresa. A divergência é rejeitada com codigo 10004030, uma proteção rígida contra documentos de teste emitidos em produção.
O mesmo app_secret, os mesmos endpoints e o mesmo esquema de assinatura são usados nos dois ambientes; só mudam o estado da empresa e o valor de ambienteEmissao.
A sequência numérica e a série enviadas no cadastro são as usadas na emissão; a partir daí a plataforma gerencia a sequência.

Endpoints de verificação e consulta cadastral

Os endpoints de Verificação de NF-e e de consulta cadastral não têm chave de ambiente: eles operam contra fontes de dados oficiais. Nas respostas de verificação, ambienteEmissao (Producao / Homologacao) descreve o documento enviado, não o chamador.

Caminho até a produção

Cadastre a empresa e vincule o certificado. A empresa entra na fila de aprovação; emitir antes da aprovação devolve 10004004.
Integre em teste: emita com ambienteEmissao=Homologacao, receba o callback de autorização, consulte o documento e baixe linkDanfe / linkDownloadXml. Percorra a lista de verificação de integração de cada tipo de documento, incluindo os casos negativos e um cancelamento.
Confirme o básico operacional: servidores sincronizados por NTP (a janela de ±300 s do timestamp vale em toda parte), URL de webhook acessível publicamente e respondendo 2xx, deduplicação implementada.
Peça à operação para mudar a empresa para produção e então emita com ambienteEmissao=Producao. Até a mudança, uma requisição Producao devolve 10004030.

Nota: todos os horários produzidos pela plataforma são UTC, independentemente do ambiente.

Observações operacionais

Enquanto a empresa está no ambiente de teste, a latência de emissão depende da disponibilidade do ambiente de teste da SEFAZ. Se um documento permanecer em AguardandoAutorizacao por mais de alguns minutos, contate a plataforma com o empresaId e o id do documento.
As entregas de webhook de documentos de teste seguem o mesmo contrato, assinatura e cronograma de tentativas da produção, veja Webhooks.