{ "openapi": "3.0.3", "info": { "title": "QQ 登录、白名单与纯 Go QSign 接口", "version": "1.1.0", "description": "可通过 Apifox 的 OpenAPI/Swagger 入口导入。本标准文件不包含真实 API key、密码、token、ticket 或冻结设备机密。QQ账号和密码在同一登录接口提交；验证续接也使用该接口。QSign是普通Go独立服务，QQ登录由真实icqq客户端完成，不依赖官方QQ常驻。当前预配账号3422540300，正式24小时在线验收尚未完成。所有业务均须同时检查HTTP状态与JSON code。" }, "servers": [ { "url": "https://qq.mylyk.cn", "description": "新服务器 HTTPS 入口；实际运行结果以本次验收为准" } ], "tags": [ { "name": "01 QQ 登录与退出" }, { "name": "02 聊天白名单" }, { "name": "03 消息收取" }, { "name": "04 QSign 纯算接口" }, { "name": "05 QSign Token 回灌" }, { "name": "06 服务信息" }, { "name": "07 自动回复状态" } ], "paths": { "/api/qq/health": { "get": { "operationId": "qqApiHealth", "summary": "账号 API 与真实客户端进程状态", "tags": [ "06 服务信息" ], "description": "worker_running 只表示客户端 worker 进程在运行，不能替代 QQ 账号 status=online 的真实在线状态。configured_accounts 是可登录的已预配置账号列表。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "type": "object", "required": [ "worker_running", "configured_accounts" ], "properties": { "worker_running": { "type": "boolean" }, "configured_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/QQ" } } } }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } } } }, "/api/qq/login": { "post": { "operationId": "qqLogin", "summary": "账号和密码登录（同一接口含验证续接）", "tags": [ "01 QQ 登录与退出" ], "description": "初次以同一 JSON body 提交 qq/password，action 省略或 login。服务使用真实 icqq 客户端，HTTP202 只表示受理；轮询 status，只有 online=true 才算登录成功。若返回 waiting_slider / waiting_sms / waiting_device，则在本接口用 action 续接，续接可不带 password。当前只预配原账号3422540300，其他账号须先预配真实设备 profile。不会为任意账号伪造设备或登录结果。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" } ], "responses": { "202": { "description": "已受理，尚不表示已登录在线。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/AccountState" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "200": { "description": "验证续接操作成功；实际在线状态仍以 status 查询为准。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/AccountState" }, "msg": { "type": "string" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "examples": { "login": { "summary": "账号密码同一请求；发送前填写自己的密码", "value": { "qq": "100000001", "password": "ENTER_PASSWORD_AT_SEND_TIME", "action": "login" } }, "slider": { "summary": "真实滑块验证续接", "value": { "qq": "100000001", "action": "submit_slider", "ticket": "REPLACE_WITH_REAL_TICKET", "randstr": "REPLACE_WITH_REAL_RANDSTR" } }, "sendSms": { "summary": "主动申请短信（会触发真实发码）", "value": { "qq": "100000001", "action": "send_sms" } }, "submitSms": { "summary": "提交自己收到的短信验证码", "value": { "qq": "100000001", "action": "submit_sms", "sms_code": "ENTER_REAL_SMS_CODE" } }, "continue": { "summary": "设备验证后续接", "value": { "qq": "100000001", "action": "continue" } } } } } } } }, "/api/qq/logout": { "post": { "operationId": "qqLogout", "summary": "退出 QQ 登录", "tags": [ "01 QQ 登录与退出" ], "description": "退出所选真实客户端并清理本地 session。查看 server_logout_confirmed 与 local_session_cleared，不能把仅本地断开当作已经取得服务端登出确认。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/AccountState" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountQQRequest" } } } } } }, "/api/qq/status": { "get": { "operationId": "qqStatus", "summary": "查询实际登录状态", "tags": [ "01 QQ 登录与退出" ], "description": "查询由真实 SDK 事件维护的状态，不以进程存在或登录请求受理冒充在线。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" }, { "$ref": "#/components/parameters/AccountQQQuery" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/AccountState" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } } } }, "/api/qq/whitelist": { "get": { "operationId": "qqWhitelistList", "summary": "查看私聊白名单", "tags": [ "02 聊天白名单" ], "description": "名单保存的是来信方 QQ。初始沿用3859085709；名单持久化，不自动加好友。模型回复配置启用且账号在线时，仅名单内好友的新纯文本私聊可触发自动回复。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/WhitelistList" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } } }, "post": { "operationId": "qqWhitelistAdd", "summary": "通过 QQ 号加入白名单", "tags": [ "02 聊天白名单" ], "description": "body.qq 是来信方 QQ，不是机器人账号。添加后允许记录该账号的私聊；模型启用且账号在线时，也允许其新纯文本私聊触发模型回复。重复添加幂等；此操作不会替代 QQ 好友关系。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/WhitelistMutation" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountQQRequest" } } } } } }, "/api/qq/whitelist/{qq}": { "delete": { "operationId": "qqWhitelistDelete", "summary": "移出私聊白名单", "tags": [ "02 聊天白名单" ], "description": "删除后不再记录该来信方的新私聊；重复删除幂等。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" }, { "$ref": "#/components/parameters/WhitelistQQPath" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/WhitelistMutation" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } } } }, "/api/qq/messages": { "get": { "operationId": "qqMessages", "summary": "读取白名单私聊消息", "tags": [ "03 消息收取" ], "description": "仅返回已配置机器人收到的白名单私聊。消息最多500条、仅保存在进程内存；重启后清空。将返回的 next_after 作为下一次 after，避免重复读取。该接口不发送 QQ 消息。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" }, { "$ref": "#/components/parameters/AccountQQQuery" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/MessageList" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } } } }, "/api/qq/reply/status": { "get": { "operationId": "qqReplyStatus", "summary": "查看模型自动回复真实运行状态", "tags": [ "07 自动回复状态" ], "description": "配置状态来自真实 worker 事件；未观测配置时不会声称已启用。active=enabled且QQ在线；worker故障后enabled/online/active均为false。counts为当前进程各执行阶段累计次数，不是已收到回复的人数。仅返回模型名称、固定错误码和统计，不暴露provider key或消息内容。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" }, { "$ref": "#/components/parameters/AccountQQQuery" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/ReplyStatus" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } } } }, "/api/qq/replies": { "get": { "operationId": "qqReplyEvents", "summary": "查询白名单自动回复阶段记录", "tags": [ "07 自动回复状态" ], "description": "只返回当前白名单来信方的回复元数据，最多保留500条内存阶段事件；一条来信可能有queued/generating/sending/sent等多条事件。删除白名单后历史记录也隐藏，进程重启后清空。sent要求SDK返回非空message_id，只证明SDK发送成功，不代表接收方已确认可见。此接口不发送或重试消息，不返回消息正文。", "parameters": [ { "$ref": "#/components/parameters/AccountApiKey" }, { "$ref": "#/components/parameters/AccountQQQuery" }, { "$ref": "#/components/parameters/After" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "业务操作成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/ReplyList" }, "msg": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "参数格式错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "401": { "description": "API key 缺失或不正确。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "404": { "description": "QQ 账号未预配置或资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "409": { "description": "当前账号状态与操作冲突。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "502": { "description": "真实客户端操作失败。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } }, "503": { "description": "真实客户端 worker 不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountError" } } } } } } }, "/qsign/": { "get": { "operationId": "qsignInfo", "summary": "QSign 协议版本", "tags": [ "06 服务信息" ], "description": "\n\n鉴权 key 只放查询参数且只能出现一次。业务失败也通常返回 HTTP 200，成功条件为 JSON code=0。", "parameters": [ { "$ref": "#/components/parameters/QSignApiKey" } ], "responses": { "200": { "description": "业务结果；请检查 JSON code，不要仅看 HTTP 状态。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "type": "object", "required": [ "protocol" ], "properties": { "protocol": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "string", "enum": [ "9.3.80" ] } } } } }, "msg": { "type": "string" } }, "additionalProperties": false }, { "$ref": "#/components/schemas/QSignError" } ] } } } } } } }, "/qsign/ver": { "get": { "operationId": "qsignVersions", "summary": "QSign 适配版本列表", "tags": [ "06 服务信息" ], "description": "\n\n鉴权 key 只放查询参数且只能出现一次。业务失败也通常返回 HTTP 200，成功条件为 JSON code=0。", "parameters": [ { "$ref": "#/components/parameters/QSignApiKey" } ], "responses": { "200": { "description": "业务结果；请检查 JSON code，不要仅看 HTTP 状态。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "type": "object", "required": [ "com.tencent.mobileqq" ], "properties": { "com.tencent.mobileqq": { "type": "array", "items": { "type": "string" } } } }, "msg": { "type": "string" } }, "additionalProperties": false }, { "$ref": "#/components/schemas/QSignError" } ] } } } } } } }, "/qsign/cmd_whitelist": { "get": { "operationId": "qsignCommandWhitelist", "summary": "QSign 签名命令列表", "tags": [ "06 服务信息" ], "description": "这是签名算法的命令列表，区别于上方的 QQ 来信方白名单。\n\n鉴权 key 只放查询参数且只能出现一次。业务失败也通常返回 HTTP 200，成功条件为 JSON code=0。", "parameters": [ { "$ref": "#/components/parameters/QSignApiKey" } ], "responses": { "200": { "description": "业务结果；请检查 JSON code，不要仅看 HTTP 状态。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "type": "object", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "type": "string" } } } }, "msg": { "type": "string" } }, "additionalProperties": false }, { "$ref": "#/components/schemas/QSignError" } ] } } } } } } }, "/qsign/energy": { "post": { "operationId": "qsignEnergy", "summary": "文档要求：计算 Energy", "tags": [ "04 QSign 纯算接口" ], "description": "对应 Dandelion.energy，返回真实普通 Go 计算的 hex。ver 是 QQ9.3.80；version 是 WTLogin SDK6.0.0.2591。标准文件中的设备字段为占位值，必须替换为原冻结设备资料。\n\n鉴权 key 只放查询参数且只能出现一次。业务失败也通常返回 HTTP 200，成功条件为 JSON code=0。", "parameters": [ { "$ref": "#/components/parameters/QSignApiKey" } ], "responses": { "200": { "description": "业务结果；请检查 JSON code，不要仅看 HTTP 状态。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "type": "string", "pattern": "^(?:[0-9a-f]{2})+$" }, "msg": { "type": "string" } }, "additionalProperties": false }, { "$ref": "#/components/schemas/QSignError" } ] } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/EnergyRequest" } } } } } }, "/qsign/sign": { "post": { "operationId": "qsignSign", "summary": "文档要求：获取 extra/sign/token", "tags": [ "04 QSign 纯算接口" ], "description": "对应 QQSecuritySign.getSign。sign/token/extra 均为 hex，fresh 流程中 token 可为空。cmd/seq/buffer 必须来自实际客户端，不能将空 body 示例当作真实登录协议包。\n\n鉴权 key 只放查询参数且只能出现一次。业务失败也通常返回 HTTP 200，成功条件为 JSON code=0。", "parameters": [ { "$ref": "#/components/parameters/QSignApiKey" } ], "responses": { "200": { "description": "业务结果；请检查 JSON code，不要仅看 HTTP 状态。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/SignResult" }, "msg": { "type": "string" } }, "additionalProperties": false }, { "$ref": "#/components/schemas/QSignError" } ] } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SignRequest" } } } } } }, "/qsign/request_token": { "post": { "operationId": "qsignRequestToken", "summary": "文档要求：获取认证 Token / 发起 icqq 回调", "tags": [ "05 QSign Token 回灌" ], "description": "留空 compat 时只返回当前已认证且未过期 token 的 hex；尚无真实 grant 会明确返回 code1。compat=icqq 返回需经 QQ 在线连接投递的 ssoPacketList，再将真实服务端回包提交 submit。单纯 HTTP 成功不代表 QQ 服务端已经签发 token。\n\n鉴权 key 只放查询参数且只能出现一次。业务失败也通常返回 HTTP 200，成功条件为 JSON code=0。", "parameters": [ { "$ref": "#/components/parameters/QSignApiKey" }, { "$ref": "#/components/parameters/Compat" } ], "responses": { "200": { "description": "业务结果；请检查 JSON code，不要仅看 HTTP 状态。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "oneOf": [ { "type": "string", "pattern": "^(?:[0-9a-f]{2})+$" }, { "$ref": "#/components/schemas/CallbackList" } ] }, "msg": { "type": "string" } }, "additionalProperties": false }, { "$ref": "#/components/schemas/QSignError" } ] } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/QSignIdentity" } } } } } }, "/qsign/register": { "post": { "operationId": "qsignRegister", "summary": "选择已预配置的 QSign 设备", "tags": [ "05 QSign Token 回灌" ], "description": "仅验证并选择已配置账号与冻结设备。此接口不是 QQ 密码登录，也不会通过 QQ 号自动生成新设备；账号密码登录使用 /api/qq/login。\n\n鉴权 key 只放查询参数且只能出现一次。业务失败也通常返回 HTTP 200，成功条件为 JSON code=0。", "parameters": [ { "$ref": "#/components/parameters/QSignApiKey" } ], "responses": { "200": { "description": "业务结果；请检查 JSON code，不要仅看 HTTP 状态。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "type": "object" }, "msg": { "type": "string" } }, "additionalProperties": false }, { "$ref": "#/components/schemas/QSignError" } ] } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/QSignIdentity" } } } } } }, "/qsign/submit": { "post": { "operationId": "qsignSubmit", "summary": "回灌真实 QQ Token 响应", "tags": [ "05 QSign Token 回灌" ], "description": "body 必须为真实在线客户端收到的服务端 bare-PB 回包。仅当传输层已证实有 WUP 四字节前缀时才由该层去除，不要盲删。callback_id 与申请包 callbackId 保持关联。\n\n鉴权 key 只放查询参数且只能出现一次。业务失败也通常返回 HTTP 200，成功条件为 JSON code=0。", "parameters": [ { "$ref": "#/components/parameters/QSignApiKey" } ], "responses": { "200": { "description": "业务结果；请检查 JSON code，不要仅看 HTTP 状态。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "code", "data" ], "properties": { "code": { "type": "integer", "enum": [ 0 ] }, "data": { "$ref": "#/components/schemas/CallbackList" }, "msg": { "type": "string" } }, "additionalProperties": false }, { "$ref": "#/components/schemas/QSignError" } ] } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SubmitRequest" } } } } } } }, "components": { "parameters": { "QSignApiKey": { "name": "key", "in": "query", "required": true, "description": "替换为本机私有配置中的 API key；不要再在鉴权面板重复添加同名 query 参数。", "schema": { "type": "string", "minLength": 16 }, "example": "REPLACE_WITH_PRIVATE_API_KEY" }, "AccountApiKey": { "name": "X-API-Key", "in": "header", "required": true, "description": "账号 API 鉴权。也接受单一 query key，二选一；导入文件统一用本 header。", "schema": { "type": "string", "minLength": 16 }, "example": "REPLACE_WITH_PRIVATE_API_KEY" }, "AccountQQQuery": { "name": "qq", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/QQ" }, "description": "已预配置的机器人 QQ。" }, "WhitelistQQPath": { "name": "qq", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/QQ" }, "description": "要移出白名单的来信方 QQ。" }, "Compat": { "name": "compat", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "icqq" ] }, "description": "留空为文档 hex 模式；填 icqq 返回回调包模式。" }, "After": { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$", "example": "0", "default": "0" }, "description": "上一次 next_after 数字游标；默认从当前保留的最早消息读取。" }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, "schemas": { "QQ": { "type": "string", "pattern": "^[1-9][0-9]{0,9}$", "description": "QQ 号，以字符串传入；必须是 uint32 范围内的有效 QQ 号。", "example": "100000001" }, "QSignError": { "type": "object", "required": [ "code", "msg" ], "properties": { "code": { "type": "integer", "enum": [ 1 ] }, "msg": { "type": "string" } }, "additionalProperties": false }, "AccountError": { "type": "object", "required": [ "code", "data", "msg" ], "properties": { "code": { "type": "integer", "enum": [ 400, 401, 404, 409, 502, 503 ] }, "data": { "type": "object", "required": [ "error_code" ], "properties": { "error_code": { "type": "string" } }, "additionalProperties": false }, "msg": { "type": "string", "description": "固定说明，不回显密码或 SDK 原始异常。" } }, "additionalProperties": false }, "Challenge": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "url": { "type": "string", "description": "需要人工操作时返回的验证网址。" }, "phone": { "type": "string", "description": "SDK 提供的接码手机号提示。" } } }, "AccountState": { "type": "object", "required": [ "qq", "status", "online", "updated_at" ], "properties": { "qq": { "$ref": "#/components/schemas/QQ" }, "status": { "type": "string", "enum": [ "offline", "logging_in", "online", "waiting_slider", "waiting_sms", "waiting_device", "error" ] }, "online": { "type": "boolean", "description": "仅真实 SDK 在线事件确认后为 true。" }, "updated_at": { "type": "string", "format": "date-time" }, "challenge": { "$ref": "#/components/schemas/Challenge" }, "error_code": { "type": "string" }, "server_logout_confirmed": { "type": "boolean", "description": "是否获得服务端登出确认，不能以本地断开冒充。" }, "local_session_cleared": { "type": "boolean", "description": "本地账号 session 是否已清理。" } } }, "AccountQQRequest": { "type": "object", "required": [ "qq" ], "properties": { "qq": { "$ref": "#/components/schemas/QQ" } }, "additionalProperties": false }, "LoginRequest": { "type": "object", "required": [ "qq" ], "properties": { "qq": { "$ref": "#/components/schemas/QQ" }, "password": { "type": "string", "minLength": 1, "writeOnly": true, "description": "初次登录必填，与 qq 在同一 JSON 请求体提交；不落盘、不出现在响应中。" }, "action": { "type": "string", "enum": [ "login", "submit_slider", "send_sms", "submit_sms", "continue" ], "default": "login" }, "ticket": { "type": "string", "description": "完成真实滑块验证后取得的 ticket。" }, "randstr": { "type": "string", "description": "完成真实滑块验证后取得的 randstr。" }, "sms_code": { "type": "string", "description": "真实短信验证码，不存入标准导入文件。" } }, "additionalProperties": false, "oneOf": [ { "required": [ "password" ], "properties": { "action": { "enum": [ "login" ] } } }, { "required": [ "action", "ticket" ], "properties": { "action": { "enum": [ "submit_slider" ] } } }, { "required": [ "action" ], "properties": { "action": { "enum": [ "send_sms", "continue" ] } } }, { "required": [ "action", "sms_code" ], "properties": { "action": { "enum": [ "submit_sms" ] } } } ] }, "WhitelistList": { "type": "object", "required": [ "qqs", "revision" ], "properties": { "qqs": { "type": "array", "items": { "$ref": "#/components/schemas/QQ" } }, "revision": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "WhitelistMutation": { "type": "object", "required": [ "qq", "allowed", "changed", "revision" ], "properties": { "qq": { "$ref": "#/components/schemas/QQ" }, "allowed": { "type": "boolean" }, "changed": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "PrivateMessage": { "type": "object", "required": [ "id", "qq", "sender_qq", "message_id", "text", "time_unix", "received_at" ], "properties": { "id": { "type": "string", "pattern": "^[0-9]+$", "example": "0" }, "qq": { "$ref": "#/components/schemas/QQ" }, "sender_qq": { "$ref": "#/components/schemas/QQ" }, "message_id": { "type": "string" }, "text": { "type": "string" }, "time_unix": { "type": "number", "description": "原消息 Unix 秒时间。" }, "received_at": { "type": "string", "format": "date-time" } } }, "MessageList": { "type": "object", "required": [ "items", "next_after" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrivateMessage" } }, "next_after": { "type": "string", "pattern": "^[0-9]+$", "example": "0" } }, "additionalProperties": false }, "ReplyMetadata": { "type": "object", "required": [ "id", "qq", "peer", "message_id", "stage", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^[0-9]+$", "example": "0" }, "qq": { "$ref": "#/components/schemas/QQ" }, "peer": { "$ref": "#/components/schemas/QQ" }, "message_id": { "type": "string" }, "stage": { "type": "string", "enum": [ "queued", "generating", "sending", "sent", "failed", "skipped" ] }, "model": { "type": "string", "maxLength": 128 }, "reply_chars": { "type": "integer", "minimum": 0, "maximum": 65536 }, "error_code": { "type": "string", "description": "固定错误码，不返回模型正文或 SDK 异常。" }, "sent_message_id": { "type": "string", "description": "SDK 返回的发送消息 ID，不等于接收方已确认可见。" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ReplyList": { "type": "object", "required": [ "items", "next_after" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReplyMetadata" } }, "next_after": { "type": "string", "pattern": "^[0-9]+$", "example": "0" } }, "additionalProperties": false }, "ReplyCounts": { "type": "object", "required": [ "queued", "generating", "sending", "sent", "failed", "skipped" ], "properties": { "queued": { "type": "integer", "minimum": 0 }, "generating": { "type": "integer", "minimum": 0 }, "sending": { "type": "integer", "minimum": 0 }, "sent": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ReplyStatus": { "type": "object", "required": [ "qq", "configuration_observed", "configured", "enabled", "model", "online", "active", "worker_running", "counts", "last_error", "updated_at" ], "properties": { "qq": { "$ref": "#/components/schemas/QQ" }, "configuration_observed": { "type": "boolean", "description": "是否已收到真实 worker 的模型配置事件。" }, "configured": { "type": "boolean", "description": "最近一次真实配置事件是否声明启用模型。" }, "enabled": { "type": "boolean", "description": "已观测启用配置且 worker 当前在运行。" }, "model": { "type": "string", "description": "模型名称；尚未观测时为空，不返回服务商 key。" }, "online": { "type": "boolean" }, "active": { "type": "boolean", "description": "enabled 且 QQ 当前真实在线。" }, "worker_running": { "type": "boolean" }, "counts": { "$ref": "#/components/schemas/ReplyCounts" }, "last_error": { "type": "string", "description": "最近固定错误码；没有时为空。" }, "updated_at": { "type": "string", "description": "最近配置或阶段事件的 UTC 时间；尚无事件时为空。" } }, "additionalProperties": false }, "QSignIdentity": { "type": "object", "required": [ "uin", "guid" ], "properties": { "uin": { "type": "string", "pattern": "^[0-9]+$", "example": "100000001", "description": "受控 QQ UIN，须与服务预配置资料及真实客户端一致。" }, "guid": { "type": "string", "pattern": "^[0-9a-fA-F]{32}$", "example": "00000000000000000000000000000000", "description": "16 原始字节的 32 位 hex；标准文件为占位值，必须换成原冻结设备值。" }, "android_id": { "type": "string", "pattern": "^[0-9a-fA-F]{16}$", "example": "0000000000000000", "description": "原冻结 AndroidID。也支持 androidId 别名，两个名字不要提交冲突值。" }, "qimei36": { "type": "string", "example": "REPLACE_WITH_FROZEN_QIMEI36", "description": "原冻结 QImei，不随机生成或截取。" }, "ver": { "type": "string", "enum": [ "9.3.80" ], "default": "9.3.80", "example": "9.3.80" }, "qua": { "type": "string", "example": "REPLACE_WITH_FROZEN_QUA", "description": "原冻结 APK QUA。" } }, "additionalProperties": false }, "EnergyRequest": { "type": "object", "required": [ "uin", "guid", "data", "version" ], "properties": { "uin": { "type": "string", "pattern": "^[0-9]+$", "example": "100000001", "description": "受控 QQ UIN，须与服务预配置资料及真实客户端一致。" }, "guid": { "type": "string", "pattern": "^[0-9a-fA-F]{32}$", "example": "00000000000000000000000000000000", "description": "16 原始字节的 32 位 hex；标准文件为占位值，必须换成原冻结设备值。" }, "android_id": { "type": "string", "pattern": "^[0-9a-fA-F]{16}$", "example": "0000000000000000", "description": "原冻结 AndroidID。也支持 androidId 别名，两个名字不要提交冲突值。" }, "qimei36": { "type": "string", "example": "REPLACE_WITH_FROZEN_QIMEI36", "description": "原冻结 QImei，不随机生成或截取。" }, "ver": { "type": "string", "enum": [ "9.3.80" ], "default": "9.3.80", "example": "9.3.80" }, "qua": { "type": "string", "example": "REPLACE_WITH_FROZEN_QUA", "description": "原冻结 APK QUA。" }, "data": { "type": "string", "enum": [ "810_2", "810_7", "810_9", "810_a", "810_f" ], "default": "810_f", "example": "810_f" }, "version": { "type": "string", "enum": [ "6.0.0.2591" ], "default": "6.0.0.2591", "example": "6.0.0.2591", "description": "WTLogin SDK 版本，不是 QQ APK ver。" } }, "additionalProperties": false }, "SignRequest": { "type": "object", "required": [ "uin", "guid", "cmd", "seq", "buffer" ], "properties": { "uin": { "type": "string", "pattern": "^[0-9]+$", "example": "100000001", "description": "受控 QQ UIN，须与服务预配置资料及真实客户端一致。" }, "guid": { "type": "string", "pattern": "^[0-9a-fA-F]{32}$", "example": "00000000000000000000000000000000", "description": "16 原始字节的 32 位 hex；标准文件为占位值，必须换成原冻结设备值。" }, "android_id": { "type": "string", "pattern": "^[0-9a-fA-F]{16}$", "example": "0000000000000000", "description": "原冻结 AndroidID。也支持 androidId 别名，两个名字不要提交冲突值。" }, "qimei36": { "type": "string", "example": "REPLACE_WITH_FROZEN_QIMEI36", "description": "原冻结 QImei，不随机生成或截取。" }, "ver": { "type": "string", "enum": [ "9.3.80" ], "default": "9.3.80", "example": "9.3.80" }, "qua": { "type": "string", "example": "REPLACE_WITH_FROZEN_QUA", "description": "原冻结 APK QUA。" }, "cmd": { "type": "string", "minLength": 1, "example": "wtlogin.login" }, "seq": { "type": "string", "pattern": "^-?[0-9]+$", "example": "1", "description": "真实协议序列号。" }, "buffer": { "type": "string", "pattern": "^(?:[0-9a-fA-F]{2})*$", "description": "真实协议 body 的 hex。空 body 示例只用于签名服务实算检查，不能拿来代替真实登录包。", "example": "" } }, "additionalProperties": false }, "SubmitRequest": { "type": "object", "required": [ "uin", "guid", "cmd", "callback_id", "buffer" ], "properties": { "uin": { "type": "string", "pattern": "^[0-9]+$", "example": "100000001", "description": "受控 QQ UIN，须与服务预配置资料及真实客户端一致。" }, "guid": { "type": "string", "pattern": "^[0-9a-fA-F]{32}$", "example": "00000000000000000000000000000000", "description": "16 原始字节的 32 位 hex；标准文件为占位值，必须换成原冻结设备值。" }, "android_id": { "type": "string", "pattern": "^[0-9a-fA-F]{16}$", "example": "0000000000000000", "description": "原冻结 AndroidID。也支持 androidId 别名，两个名字不要提交冲突值。" }, "qimei36": { "type": "string", "example": "REPLACE_WITH_FROZEN_QIMEI36", "description": "原冻结 QImei，不随机生成或截取。" }, "ver": { "type": "string", "enum": [ "9.3.80" ], "default": "9.3.80", "example": "9.3.80" }, "qua": { "type": "string", "example": "REPLACE_WITH_FROZEN_QUA", "description": "原冻结 APK QUA。" }, "cmd": { "type": "string", "minLength": 1, "example": "trpc.o3.ecdh_access.EcdhAccess.SsoEstablishShareKey" }, "callback_id": { "type": "string", "pattern": "^-?[0-9]+$", "description": "真实 callbackId 的十进制字符串；也支持 callbackId 别名。" }, "buffer": { "type": "string", "pattern": "^(?:[0-9a-fA-F]{2})*$", "description": "由真实 QQ 在线连接取得的服务端 bare-PB 回包 hex，不能用申请包替代。" } }, "additionalProperties": false }, "Callback": { "type": "object", "required": [ "cmd", "body", "callbackId" ], "properties": { "cmd": { "type": "string" }, "body": { "type": "string", "pattern": "^(?:[0-9a-fA-F]{2})*$", "description": "原始 bytes 的完整 hex；空值仅在原流程允许时使用。" }, "callbackId": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "CallbackList": { "type": "object", "required": [ "ssoPacketList" ], "properties": { "ssoPacketList": { "type": "array", "items": { "$ref": "#/components/schemas/Callback" } } }, "additionalProperties": false }, "SignResult": { "type": "object", "required": [ "extra", "sign", "token" ], "properties": { "extra": { "type": "string", "pattern": "^(?:[0-9a-fA-F]{2})*$", "description": "原始 bytes 的完整 hex；空值仅在原流程允许时使用。" }, "sign": { "type": "string", "pattern": "^(?:[0-9a-fA-F]{2})*$", "description": "原始 bytes 的完整 hex；空值仅在原流程允许时使用。", "minLength": 2 }, "token": { "type": "string", "pattern": "^(?:[0-9a-fA-F]{2})*$", "description": "原始 bytes 的完整 hex；空值仅在原流程允许时使用。" }, "ssoPacketList": { "type": "array", "items": { "$ref": "#/components/schemas/Callback" } } }, "additionalProperties": false } } }, "externalDocs": { "description": "Apifox 官方 OpenAPI/Swagger 导入说明", "url": "https://docs.apifox.com/import-openapi-swagger" } }