POST
/api/client/auth/register
客户端注册账号并直接创建在线会话
用于客户端首次创建用户账号。注册成功后会自动绑定当前设备并创建在线会话，返回客户端 token。
请求头
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
X-App-Id | string | 是 | 当前软件的 APPID。每个软件独立，不能跨软件混用。 | "" |
X-Timestamp | int string | 是 | 当前秒级时间戳，用于防止请求被长期重放。 | "" |
X-Nonce | string | 是 | 每次请求唯一随机串，服务端会记录并拒绝重复 nonce。 | "" |
X-Signature | string | 是 | HMAC-SHA256(appId + timestamp + nonce + body, appSecret) 的十六进制结果。 | "" |
X-Encrypt-Mode | string | 是 | 通讯方式。sign 表示只签名；sign_aes 表示 AES-256-GCM 加密请求体后再签名。 | "" |
请求参数
| Body 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
agentCode | string | 否 | 代理推广码。传入后会尽量建立当前软件下的代理客户归属。 | A1234567 |
clientVersion | string | 否 | 客户端当前版本号，用于版本检查、日志排查和工单定位。 | 1.0.0 |
deviceFingerprint | string | 是 | 设备唯一指纹。建议由机器码、硬件信息或安装实例 ID 生成，并保持稳定。 | machine-guid-or-hardware-fingerprint |
deviceName | string | 否 | 设备名称，会显示在后台设备管理中。 | Windows PC |
email | string | 否 | 用户邮箱，可选，用于后台识别或联系用户。 | demo@example.com |
password | string | 是 | 用户密码。服务端只保存哈希，不保存明文。 | 123456 |
phone | string | 否 | 手机号，可选。 | "" |
username | string | 是 | 用户账号。账号全局唯一，但会员、点数、设备、订单等权益按软件隔离。 | demo |
请求示例
{
"agentCode": "A1234567",
"clientVersion": "1.0.0",
"deviceFingerprint": "machine-guid-or-hardware-fingerprint",
"deviceName": "Windows PC",
"email": "demo@example.com",
"password": "123456",
"phone": "",
"username": "demo"
}成功响应
{
"code": "OK",
"data": {
"activationReason": "membership required",
"activationRequired": true,
"app": {
"appId": "8828",
"billingMode": "time",
"bindDeviceEnabled": true,
"bindIpEnabled": false,
"maxDevices": 1
},
"entitlement": {
"expiredAt": null,
"membership": null,
"membershipActive": false,
"membershipLevelId": null,
"membershipStatus": "none",
"points": 0,
"startedAt": null
},
"heartbeat": {
"interval": 60
},
"loginAvailable": true,
"sessionId": "sess_xxx",
"token": "client-jwt",
"user": {
"avatar": "https://thirdqq.qlogo.cn/...",
"id": 1,
"nickname": "大白",
"provider": "qq",
"status": "active",
"username": "demo"
}
},
"message": "success"
}失败响应
{
"code": "BAD_REQUEST",
"data": null,
"message": "请求参数错误"
}对接注意事项
- 注册成功后会自动绑定当前设备并返回客户端 token。
- 时长收费软件即使没有会员也允许登录，客户端应根据 activationRequired 和 entitlement 决定是否拦截功能。
- 如果软件开启设备绑定或 IP 绑定，更换硬件/IP 后会拒绝登录，需要后台解绑。