SSO · TF Fiscal API

Nota

SSO — Login Automático via Token

Base URL (Produção)

https://api.tffiscal.com

Autenticação

Headers: sign, timestamp, token

Validade do Ticket

60 segundos — uso único

O SSO (Single Sign-On) permite que seu ERP gere um link de acesso direto ao TFiscal para o usuário, já autenticado na empresa correspondente e no idioma desejado — sem que ele precise digitar credenciais.

Como funciona:

O ERP chama POST /api/sso/create_ticket enviando o token da empresa.
A TFiscal devolve um redirectUrl contendo um ticket opaco de uso único.
O ERP redireciona o navegador do usuário para essa URL.
A página consome o ticket e o usuário entra logado no painel da empresa.

⚠️ Segurança: o token real da empresa nunca aparece na URL. Apenas o ticket efêmero (válido por 60 segundos e de uso único) transita pelo navegador.

POST/api/sso/create_ticket

Gerar link de login automático

Gera um ticket de uso único que pode ser usado em até 60 segundos para logar automaticamente o usuário no painel da empresa correspondente ao token.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa (o mesmo usado para emitir NF-e)
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Campos

Campo	Obrigatório	Tipo	Descrição
token	Sim	string	Token da empresa (`w_company.token`) — o mesmo usado em `/api/invoice/create`
language	Não	string	Idioma da interface: `br`, `en`, `zh`, `es`, `ja`, `ko`. Default: `br`
page	Não	string	Página de destino após o login. Valores aceitos: `emitir_nfe`. Vazio ou ausente abre o painel padrão (`/company/kanban`).

Campos da Resposta

Campo	Tipo	Descrição
success	boolean	`true` quando o ticket foi gerado com sucesso
ticket	string	Ticket opaco (aleatório, 32 bytes base64url)
redirectUrl	string	URL completa para onde o ERP deve redirecionar o navegador do usuário
expiresInSeconds	number	Tempo de validade em segundos (sempre 60)
expiresAt	string	Data/hora UTC de expiração (ISO 8601)

Respostas de erro

Mensagem	Causa
`Token é obrigatório`	Campo `token` não foi enviado no body
`Token inválido`	Token não corresponde a nenhuma empresa cadastrada
`Este token está vinculado a múltiplas empresas. Envie o token da empresa que deseja acessar.`	Token de integrador com mais de uma empresa — envie o token específico da empresa desejada
`Rate limit exceeded`	Mais de 30 chamadas por minuto para o mesmo token

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/sso/create_ticket" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "token": "TOKEN_DA_EMPRESA",
          "language": "br",
          "page": "emitir_nfe"
        }

        {
          "success": true,
          "message": "ticket",
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
          "redirectUrl": "https://www.tffiscal.com/sso#ticket=nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
          "expiresInSeconds": 60,
          "expiresAt": "2026-04-24T18:34:56.0000000Z"
        }

POST/api/sso/consume_ticket

Consumir ticket SSO

Troca o ticket gerado por /api/sso/create_ticket pelo JWT de sessão da TFiscal. Endpoint chamado pelo frontend (rota /sso) e não requer headers sign/timestamp — o próprio ticket opaco é a credencial. Cada ticket pode ser consumido apenas uma vez e expira em 60 segundos.

Body

Campo	Tipo	Descrição
ticket *	string	Ticket retornado por `create_ticket`

* Campo obrigatório.

Campos da Resposta

Campo	Tipo	Descrição
access_token	string	JWT de sessão (validade de 365 dias). Use no header `Authorization` das chamadas TFiscal
type	string	Tipo do usuário (`user`, `admin`, etc.)
uid	int	ID interno do usuário
company_id	int	ID da empresa selecionada no `create_ticket`
language	string	Idioma escolhido no `create_ticket` (sempre normalizado)
page	string	Página de destino (ou string vazia se não definida)

Respostas de erro

Mensagem	Causa
`Ticket inválido`	Body sem campo `ticket`
`Ticket inválido ou expirado`	Ticket não existe, já foi consumido ou passou dos 60 segundos
`Rate limit exceeded`	Mais de 60 consumos por minuto a partir do mesmo IP
`Sessão inválida`	Usuário vinculado ao ticket não existe mais

Nota

Restrições e Segurança

Características do ticket

Característica	Valor
Validade	60 segundos após geração
Uso	Único — após consumido, não pode ser reutilizado
Rate limit	30 tickets/minuto por token · 60 consumos/minuto por IP
Armazenamento	MongoDB com TTL automático — tickets expirados são removidos

Restrições de navegação

Usuários autenticados via SSO têm acesso apenas às telas da empresa correspondente (/invoice/company/*). Tentativas de acessar outras áreas (painéis de revendedor, relatórios gerais, administração) são redirecionadas automaticamente para o painel da empresa.

Sessão após o login

Após a troca do ticket por JWT, o usuário possui uma sessão normal na TFiscal (JWT com validade de 365 dias, igual ao login tradicional). Os 60 segundos são apenas a janela entre gerar o ticket e abrir o link — depois disso o usuário fica logado normalmente até sair.

⚠️ Importante: o create_ticket deve ser chamado exclusivamente server-side pelo ERP. Nunca chame esse endpoint diretamente do navegador — isso exporia o token da empresa no front-end.