平台与集成
SSO 单点登录
2 个接口
基础 URL（生产）
https://api.tffiscal.com
认证
Headers: sign, timestamp, token票据有效期
60 秒 — 一次性使用SSO（单点登录）允许您的 ERP 为用户生成直接访问 TFiscal 的链接，用户无需输入凭据即可以所选语言自动登录到相应的公司。
工作原理：
- ERP 调用
POST /api/sso/create_ticket并发送公司令牌。 - TFiscal 返回一个包含一次性不透明票据的
redirectUrl。 - ERP 将用户浏览器重定向到该 URL。
- 页面消费票据后，用户自动登录到公司面板。
⚠️ 安全： 真实的公司令牌永远不会出现在 URL 中。仅将短期票据（有效期 60 秒，一次性）暴露给浏览器。
POST
/api/sso/create_ticket生成自动登录链接
生成一个一次性票据，可在 60 秒内使用，将用户自动登录到与该令牌对应的公司面板。
必需的 Headers
| Header | 类型 | 描述 |
|---|---|---|
| token | string | 公司令牌（与开具 NF-e 使用的相同） |
| sign | string | MD5 签名：MD5(token + path + body + timestamp) |
| timestamp | string | Unix 秒级时间戳（5 分钟窗口） |
字段
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| token | 是 | string | 公司令牌（w_company.token）— 与 /api/invoice/create 使用的相同 |
| language | 否 | string | 界面语言：br、en、zh、es、ja、ko。默认：br |
| page | 否 | string | 登录后的着陆页。接受的值：emitir_nfe。为空或缺失时打开默认面板（/company/kanban）。 |
响应字段
| 字段 | 类型 | 描述 |
|---|---|---|
| success | boolean | 成功生成票据时为 true |
| ticket | string | 不透明票据（随机，32 字节 base64url） |
| redirectUrl | string | ERP 应将用户浏览器重定向到的完整 URL |
| expiresInSeconds | number | 有效期秒数（始终为 60） |
| expiresAt | string | UTC 过期时间（ISO 8601） |
错误响应
| 消息 | 原因 |
|---|---|
Token 为必填项 | body 中未发送 token 字段 |
无效的 Token | 令牌与任何已注册的公司不匹配 |
此令牌绑定了多家公司。请发送您要访问的特定公司令牌。 | 集成商令牌绑定了多家公司 — 请发送具体公司的令牌 |
Rate limit exceeded | 同一令牌每分钟调用超过 30 次 |
POST
/api/sso/consume_ticket兑换登录票据
将 /api/sso/create_ticket 生成的票据兑换为 TFiscal 会话 JWT。此端点由前端(路由 /sso)调用,不需要 sign/timestamp 请求头 — 不透明的票据本身就是凭证。每个票据只能消费一次,60 秒后过期。
Body
| 字段 | 类型 | 说明 |
|---|---|---|
| ticket * | string | create_ticket 返回的票据 |
* 必填字段。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| access_token | string | 会话 JWT(有效期 365 天)。在 TFiscal 调用的 Authorization 请求头中使用 |
| type | string | 用户类型(user、admin 等) |
| uid | int | 内部用户 ID |
| company_id | int | create_ticket 中选择的企业 ID |
| language | string | create_ticket 中选择的语言(始终规范化) |
| page | string | 目标页面(未设置时为空字符串) |
错误响应
| 消息 | 原因 |
|---|---|
Ticket inválido | Body 中没有 ticket 字段 |
Ticket inválido ou expirado | 票据不存在、已被消费或超过 60 秒过期时间 |
Rate limit exceeded | 同一 IP 每分钟消费超过 60 次 |
Sessão inválida | 关联到该票据的用户不再存在 |
说明
限制与安全
票据特性
| 特性 | 值 |
|---|---|
| 有效期 | 生成后 60 秒 |
| 使用 | 一次性 — 消费后无法重用 |
| 速率限制 | 每个令牌每分钟 30 个票据 · 每个 IP 每分钟 60 次消费 |
| 存储 | 具有自动 TTL 的 MongoDB — 过期票据自动删除 |
导航限制
通过 SSO 认证的用户仅有权访问相应公司的页面（/invoice/company/*）。尝试访问其他区域（分销商面板、综合报表、管理）将自动重定向到公司面板。
登录后的会话
在将票据交换为 JWT 后，用户拥有 TFiscal 的正常会话（JWT 有效期 365 天，与传统登录相同）。60 秒仅是生成票据和打开链接之间的时间窗口 — 之后用户将保持正常登录直到注销。
⚠️ 重要：
create_ticket 必须由 ERP 仅在服务器端调用。切勿直接从浏览器调用此端点 — 这会在前端暴露公司令牌。