SSO · TF Fiscal API

Nota

SSO — Inicio Automático vía Token

Base URL (Producción)

https://api.tffiscal.com

Autenticación

Headers: sign, timestamp, token

Validez del Ticket

60 segundos — uso único

SSO (Single Sign-On) permite que su ERP genere un enlace de acceso directo a TFiscal para el usuario, ya autenticado en la empresa correspondiente y en el idioma deseado, sin que tenga que ingresar credenciales.

Cómo funciona:

El ERP llama a POST /api/sso/create_ticket enviando el token de la empresa.
TFiscal devuelve un redirectUrl con un ticket opaco de uso único.
El ERP redirige el navegador del usuario a esa URL.
La página consume el ticket y el usuario entra al panel de la empresa.

⚠️ Seguridad: el token real de la empresa nunca aparece en la URL. Sólo el ticket efímero (válido por 60 segundos y de uso único) se expone al navegador.

POST/api/sso/create_ticket

Generar enlace de inicio automático

Genera un ticket de uso único válido por 60 segundos para iniciar sesión automáticamente al usuario en el panel de la empresa correspondiente al token.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa (el mismo usado para emitir NF-e)
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Campos

Campo	Obligatorio	Tipo	Descripción
token	Sí	string	Token de la empresa (`w_company.token`) — el mismo usado en `/api/invoice/create`
language	No	string	Idioma de la interfaz: `br`, `en`, `zh`, `es`, `ja`, `ko`. Default: `br`
page	No	string	Página de destino después del login. Valores aceptados: `emitir_nfe`. Vacío o ausente abre el panel por defecto (`/company/kanban`).

Campos de la respuesta

Campo	Tipo	Descripción
success	boolean	`true` cuando el ticket se generó con éxito
ticket	string	Ticket opaco (aleatorio, 32 bytes base64url)
redirectUrl	string	URL completa a la que el ERP debe redirigir el navegador
expiresInSeconds	number	Validez en segundos (siempre 60)
expiresAt	string	Fecha/hora UTC de expiración (ISO 8601)

Respuestas de error

Mensaje	Causa
`Token es obligatorio`	El campo `token` no fue enviado en el body
`Token inválido`	El token no corresponde a ninguna empresa registrada
`Este token está vinculado a múltiples empresas. Envíe el token de la empresa a la que desea acceder.`	Token de integrador con más de una empresa — envíe el token específico de la empresa
`Rate limit exceeded`	Más de 30 llamadas por minuto para el mismo token

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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

Intercambia el ticket generado por /api/sso/create_ticket por el JWT de sesión de TFiscal. Este endpoint es llamado por el frontend (ruta /sso) y no requiere headers sign/timestamp — el propio ticket opaco es la credencial. Cada ticket puede consumirse solo una vez y expira en 60 segundos.

Body

Campo	Tipo	Descripción
ticket *	string	Ticket devuelto por `create_ticket`

* Campo obligatorio.

Campos de la respuesta

Campo	Tipo	Descripción
access_token	string	JWT de sesión (validez de 365 días). Úselo en el header `Authorization` de las llamadas TFiscal
type	string	Tipo de usuario (`user`, `admin`, etc.)
uid	int	ID interno del usuario
company_id	int	ID de la empresa seleccionada en `create_ticket`
language	string	Idioma elegido en `create_ticket` (siempre normalizado)
page	string	Página de destino (o string vacío si no se define)

Respuestas de error

Mensaje	Causa
`Ticket inválido`	Body sin campo `ticket`
`Ticket inválido ou expirado`	El ticket no existe, ya fue consumido o pasó los 60 segundos
`Rate limit exceeded`	Más de 60 consumos por minuto desde la misma IP
`Sessão inválida`	El usuario vinculado al ticket ya no existe

Nota

Restricciones y Seguridad

Características del ticket

Característica	Valor
Validez	60 segundos después de generado
Uso	Único — una vez consumido no se puede reutilizar
Rate limit	30 tickets/minuto por token · 60 consumos/minuto por IP
Almacenamiento	MongoDB con TTL automático — tickets expirados se eliminan

Restricciones de navegación

Los usuarios autenticados vía SSO tienen acceso solamente a las pantallas de la empresa correspondiente (/invoice/company/*). Los intentos de acceder a otras áreas (paneles de distribuidor, reportes generales, administración) son redirigidos automáticamente al panel de la empresa.

Sesión después del login

Después de intercambiar el ticket por un JWT, el usuario tiene una sesión normal en TFiscal (JWT válido por 365 días, igual que el login tradicional). Los 60 segundos son sólo la ventana entre generar el ticket y abrir el enlace — después el usuario permanece conectado normalmente hasta cerrar sesión.

⚠️ Importante: el create_ticket debe ser llamado exclusivamente server-side por el ERP. Nunca llame a este endpoint directamente desde el navegador — expondría el token de la empresa en el front-end.