SSO · TF Fiscal API

Note

SSO — Automatic Login via Token

Base URL (Production)

https://api.tffiscal.com

Authentication

Headers: sign, timestamp, token

Ticket Validity

60 seconds — single use

SSO (Single Sign-On) allows your ERP to generate a direct access link to TFiscal for the user, already authenticated in the corresponding company and in the desired language — without requiring them to enter credentials.

How it works:

The ERP calls POST /api/sso/create_ticket sending the company token.
TFiscal returns a redirectUrl containing a single-use opaque ticket.
The ERP redirects the user's browser to that URL.
The page consumes the ticket and the user logs in automatically on the company panel.

⚠️ Security: the actual company token never appears in the URL. Only the ephemeral ticket (valid for 60 seconds and single use) is exposed to the browser.

POST/api/sso/create_ticket

Generate automatic login link

Generates a single-use ticket that can be used within 60 seconds to automatically log the user into the company panel matching the token.

Required Headers

Header	Type	Description
token	string	Company token (same as used to issue NF-e)
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Fields

Field	Required	Type	Description
token	Yes	string	Company token (`w_company.token`) — same one used in `/api/invoice/create`
language	No	string	UI language: `br`, `en`, `zh`, `es`, `ja`, `ko`. Default: `br`
page	No	string	Landing page after login. Accepted values: `emitir_nfe`. Empty or missing opens the default panel (`/company/kanban`).

Response Fields

Field	Type	Description
success	boolean	`true` when the ticket was successfully generated
ticket	string	Opaque ticket (random, 32 bytes base64url)
redirectUrl	string	Full URL where the ERP should redirect the user's browser
expiresInSeconds	number	Validity in seconds (always 60)
expiresAt	string	UTC expiration date/time (ISO 8601)

Error Responses

Message	Cause
`Token is required`	The `token` field was not sent in the body
`Invalid token`	Token does not match any registered company
`This token is linked to multiple companies. Send the specific company token you want to access.`	Integrator token with more than one company — send the specific company token
`Rate limit exceeded`	More than 30 calls per minute for the same token

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

Consume SSO ticket

Exchanges the ticket generated by /api/sso/create_ticket for the TFiscal session JWT. This endpoint is called by the frontend (route /sso) and does not require sign/timestamp headers — the opaque ticket itself is the credential. Each ticket can be consumed only once and expires in 60 seconds.

Body

Field	Type	Description
ticket *	string	Ticket returned by `create_ticket`

* Required field.

Response fields

Field	Type	Description
access_token	string	Session JWT (365-day validity). Use in the `Authorization` header of TFiscal calls
type	string	User type (`user`, `admin`, etc.)
uid	int	Internal user ID
company_id	int	ID of the company selected in `create_ticket`
language	string	Language chosen in `create_ticket` (always normalized)
page	string	Target page (or empty string if not set)

Error responses

Message	Cause
`Ticket inválido`	Body without `ticket` field
`Ticket inválido ou expirado`	Ticket does not exist, has already been consumed, or is past the 60-second limit
`Rate limit exceeded`	More than 60 consumes per minute from the same IP
`Sessão inválida`	The user linked to the ticket no longer exists

Note

Restrictions and Security

Ticket characteristics

Characteristic	Value
Validity	60 seconds after generation
Usage	Single use — once consumed, cannot be reused
Rate limit	30 tickets/minute per token · 60 consumptions/minute per IP
Storage	MongoDB with automatic TTL — expired tickets are removed

Navigation restrictions

Users logged in via SSO have access only to the corresponding company screens (/invoice/company/*). Attempts to access other areas (reseller panels, general reports, administration) are automatically redirected to the company panel.

Session after login

After exchanging the ticket for a JWT, the user has a normal TFiscal session (JWT valid for 365 days, same as traditional login). The 60 seconds are only the window between generating the ticket and opening the link — afterwards the user remains logged in normally until they sign out.

⚠️ Important: the create_ticket must be called exclusively server-side by the ERP. Never call this endpoint directly from the browser — that would expose the company token in the front-end.