快速开始
接入流程分四步：创建应用拿到密钥 → 签发授权码 → 客户端调用验证接口 → 用心跳维持在线状态。下面按顺序说明每个环节需要做什么。
- 所有接口均为
POST，请求体application/json或表单均可。 - 响应统一为
{"code": 200, "msg": "..."}，code != 200即为失败，msg可直接展示给用户。 - 时间戳与 nonce 用于防重放，服务端会校验有效期与一次性。
1. 准备密钥
在控制台创建应用后会得到两个值：
appid— 应用标识，请求时放在请求体里。app_secret— 签名密钥，只能放在客户端本地且需要做代码混淆，不要明文写进前端网页。
密钥泄露可以在控制台一键重置，重置后旧密钥立即失效，已签发的会话不受影响。
2. 签名规则
签名串由「时间戳 + nonce + 请求体的紧凑 JSON」拼成，用 app_secret 做 HMAC-SHA256，输出小写十六进制：
// 伪代码
payload = timestamp + nonce + JSON.stringify(body)
sign = hmac_sha256(payload, app_secret).toLowerCase()
// 放进请求头
X-Timestamp = timestamp
X-Nonce = nonce
X-Request-Signature = sign
timestamp 为秒级时间戳，与服务器时间偏差超过 5 分钟会被拒绝；nonce 为一次性随机串，重复使用会被判定为重放。
3. 验证授权码
接口：POST /api/verify_key
{
"key": "A1B2C3D4E5F6",
"machine_id": "设备唯一标识",
"appid": "你的应用ID",
"platform": "all"
}
成功后返回 code: 200，同时下发会话令牌，客户端后续心跳与业务接口都带这个令牌。失败时按 msg 提示用户即可，不需要自己猜原因。
几个常见分支：
- 授权码不存在或格式非法 →
400，提示用户检查输入。 - 已过期、已冻结、被强制下线 →
403，提示具体原因。 - 剩余次数不足 →
402，提示续费。
4. 保持在线
客户端登录成功后，按固定间隔调用 POST /heartbeat 上报在线状态。服务端据此维护在线设备列表、窗口占用和超时回收。
- 建议间隔 30–60 秒，过短会增加无谓请求。
- 连续多个周期没有心跳，服务端会释放该设备占用的窗口，其他设备可以顶上。
- 心跳返回
403时说明授权已失效，客户端应退出登录并提示用户。
错误码
| code | 含义 | 客户端处理建议 |
|---|---|---|
| 200 | 成功 | 继续业务流程 |
| 400 | 参数错误 / 格式非法 | 提示用户检查授权码与设备信息 |
| 401 | 签名无效或会话过期 | 重新签名或重新登录 |
| 402 | 次数不足 | 引导续费 |
| 403 | 无权限 / 已冻结 / 强制下线 | 退出登录并展示 msg |
| 429 | 请求过于频繁 | 退避后重试 |
| 500 | 服务端异常 | 稍后重试，持续出现请联系客服 |
常见问题
- 能同时登录多台设备吗？看授权码绑定的设备数上限，超限时新设备会被拒绝，可在控制台主动解绑。
- 换了电脑怎么办？支持自助解绑或联系管理员解绑，解绑次数按策略限制。
- 错误码 401 一直出现？先确认客户端时间是否准确，时间偏差过大会导致签名校验失败。
- 接口有并发限制吗？有，按应用和 IP 双重限流，超限返回 429，建议客户端做退避重试。