# 创建免登票据

`POST` `/api/sso/createTicket`

在客户自有登录体系验密成功后调用，换取一次性免登地址 loginUrl，交给浏览器顶层跳转（新窗口或当前窗口）即可免登进入控制台。

**票据一次性有效且默认 60 秒过期**，请在用户点击进入时实时换票，不要缓存或复用 loginUrl；过期或已被使用的地址访问时会提示「登录链接已失效」，此时引导用户回到原系统重新点击入口即可。

externalUserId 必须是客户体系内稳定不可变的用户唯一标识（禁止手机号、邮箱等可变信息），且在租户内全局唯一；首次出现的标识平台会自动开户并创建独立身份主体，无需预先同步用户名单。

响应中的 principalId 建议留存：作为 OpenAPI 调用的 X-Principal-Id 传入，即可与用户页面操作共享同一主体、同一份会话与记忆。

注意：受「一个用户仅归属一个应用空间」的约束，若该 externalUserId 已归属本租户下的其他应用，接口返回 409 错误。

## 请求参数

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| externalUserId | string | 是 | 客户自有登录体系内的用户唯一标识。必须是稳定且不可变的标识（如自增ID、UUID），禁止使用手机号、邮箱等可变信息；需在租户内全局唯一。首次出现时平台自动为该用户开户，后续换票复用同一身份、同一份会话与记忆 |
| nickname | string | 否 | 用户昵称，选填。每次换票携带最新值即可覆盖平台侧昵称；首次开户不传时默认取 externalUserId |
| returnPath | string | 否 | 登录成功后跳转的站内相对路径，选填，不传则进入首页。必须以 / 开头的站内相对路径（不支持绝对 URL，也不能以 // 开头） |
| homeUrl | string | 否 | 客户系统首页地址，选填。用户在点金内点击「退出登录」后，会落到「已退出」提示页，该页展示一个指向本地址的「返回原系统」按钮；不传则展示「重新登录」。支持 http:// 与 https://（客户内网系统常为 http）。注意：点金侧登出只结束点金的会话，不会影响您自有系统的登录态，用户返回原系统后再次点击入口会立即免登进入 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | CreateSsoTicketResponse | 响应数据 |
|     loginUrl | string | 免登地址。直接交给浏览器顶层跳转（新窗口或当前窗口），访问后建立会话并进入控制台。该地址一次性有效，请勿缓存或重复使用 |
|     ticket | string | 免登票据原始值。通常无需单独使用，直接用 loginUrl 即可；仅在需要自行拼装跳转地址时使用 |
|     expiresIn | integer | 票据有效期（秒）。超过该时间未跳转则票据失效，需重新换票 |
|     principalId | integer | 该用户绑定的点金身份主体ID（principalId）。建议客户侧留存：作为 OpenAPI 调用的 X-Principal-Id 请求头传入，即可与用户在页面上的操作共享同一主体、同一份会话与记忆 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |