申请连接票据¶
请求参数¶
使用公共请求头,无查询参数或请求体。身份取自 Spring Security 的 Principal,不能通过参数指定其他用户。
匿名调用返回HTTP401。携带Bearer时使用真实账号会话与安装绑定,资料未完成返回403;资料完成但VIP门槛未满足时返回VIP_REQUIRED。当前dev固定码隔离身份可联调,真实身份和prod需要HTTPS;JWE开启后的传输要求仍按公共协议执行。账号退出/撤销与已建立连接的即时联动仍待接入。
请求示例¶
先按登录返回值完成资料及VIP准入,再通过统一客户端发送POST /api/v1/realtime/tickets;票据只在内存中处理。下面仅用于dev固定码隔离账号,正式使用HTTPS及对应加密封装:
base_url='https://api.budyoo.cn'
access_token='替换为实际accessToken'
curl --fail-with-body -X POST "$base_url/api/v1/realtime/tickets" \
-H 'Accept: application/json' -H 'Accept-Language: zh-CN' \
-H "Authorization: Bearer $access_token" \
-H 'X-Client-Type: app' -H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' -H 'X-App-Build: 1' -H 'X-Channel: dev' \
-H 'X-Device-Id: 4d4ae3ea-6a4a-4f34-a292-8e94551851d7' \
-H "X-Request-Id: $(uuidgen)" -H "X-Request-Timestamp: $(date +%s)000"
X-Device-Id须与本次登录的实际安装ID一致,示例UUID仅作占位。
成功响应¶
HTTP 200,Cache-Control: no-store。示例票据是占位符,不能直接使用:
{
"code": "SUCCESS",
"message": "连接票据已生成。",
"data": {
"ticket": "一次性43位随机票据",
"expiresAt": 1793636430000,
"websocketPath": "/ws/v1/realtime",
"authTimeoutSeconds": 5,
"heartbeatSeconds": 20
},
"errors": []
}
票据 30 秒有效、消费一次失效;服务端仅以摘要索引到 Redis,客户端只在内存保存,并通过 auth 消息发送。expiresAt 为 Unix 毫秒,握手成功后会话最长有效期另由 ready 帧返回。
失败响应¶
| HTTP | code | 原因 |
|---|---|---|
| 401 | UNAUTHORIZED |
未认证或无法取得服务端身份 |
| 403 | FORBIDDEN |
资料未完成或客户端类型不允许 |
| 403 | VIP_REQUIRED |
资料已完成,但当前会话渠道VIP门槛开启且没有有效VIP;返回VIP页处理 |
| 400 | INVALID_CLIENT_HEADERS |
必填客户端元数据缺失或格式错误 |
| 426 | HTTPS_REQUIRED |
当前身份或加密模式需要HTTPS |
| 429 | TOO_MANY_REQUESTS |
同身份每分钟超过 30 次签发请求 |
| 503 | SERVICE_UNAVAILABLE |
Redis 暂时不可用或超时 |
错误结构沿用公共响应,票据不进入 URL 和日志。握手后消费失败关闭连接,参见建立长连接。
接入说明¶
票据入口只接收服务端已认证且具有普通业务权限的身份,包含VIP第二层准入;后续通过首帧完成WebSocket认证,HTTP凭证和WebSocket票据不能互换。2026-11-20公网WSS已通过ESA接入并完成隔离票据连接验收。真实账号全流程、已建立连接与退出/撤销会话或VIP策略变化的即时联动,以及Flutter连接生命周期仍需独立完成,不能将基础连接测试作为这些能力已验收的依据。