快速开始
POST /api/v1/user/login
{ "appkey": "nkxxxx", "time": "1727700000", "nonce": "xyz1",
"username": "tom", "password": "123456", "machine": "PC-01",
"sign": "按签名算法计算" }
生产环境务必使用 HTTPS 域名，防止 Secret 与卡密被截获。
签名算法
sign = md5( 参数按名升序 k=v&… &key=AppSecret )
① 取除 sign 外的全部参数（值按字符串处理）→ ② 参数名升序拼成 k1=v1&k2=v2 → ③ 末尾拼 &key=AppSecret → ④ 取 32 位小写 MD5。
参数: appkey=nk01ab, time=1727700000, nonce=xyz, username=tom 拼串: appkey=nk01ab&nonce=xyz&time=1727700000&username=tom&key=abc123 sign = md5(拼串) // 32 位小写
公共参数
| 参数 | 必填 | 说明 |
|---|---|---|
appkey | 是 | 软件标识，控制台创建软件后获得 |
time | 是 | Unix 时间戳（秒），允许 ±300 秒误差 |
nonce | 是 | 随机字符串，每次请求必须更换（防重放） |
sign | 是 | 请求签名，见上方算法 |
统一响应：{"code":200,"msg":"ok","data":{}}，code=200 即成功，失败时直接向用户展示 msg。
错误码
| code | 含义 | code | 含义 |
|---|---|---|---|
| 200 | 成功 | 412 | 账号已过期 |
| 400 | 参数错误 | 413 | 卡密无效或已使用 |
| 401 | 签名/时间戳/重放错误 | 414 | 机器码超上限 |
| 403 | 软件已停用 | 415 | 登录态失效 |
| 404 | 软件不存在 | 416 | 账号已封禁 |
| 410 | 账号或密码错误 | 429 | 请求过于频繁 |
| 411 | 账号已存在 |
软件信息 POST/app/info
客户端启动时调用，获取公告 / 版本 / 强更标记。仅需公共参数。
{ "code": 200, "data": {
"name": "示例软件", "version": "1.0.0",
"force_update": false, "notice": "欢迎使用",
"server_time": 1727700000 } }
注册 POST/user/register
| 参数 | 必填 | 说明 |
|---|---|---|
username | 是 | 3~32 位字母/数字/_/@/- |
password | 是 | 6~64 位 |
后台可按软件关闭「允许注册」。
登录 POST/user/login
| 参数 | 必填 | 说明 |
|---|---|---|
username / password | 是 | 账号密码 |
machine | 否 | 机器码，传入自动绑定，超上限返回 414 |
{ "code": 200, "data": {
"token": "64位十六进制…",
"expire_at": 1730000000, // 0 = 永久
"machines": ["PC-01"], "max_machines": 1 } }
重复登录顶号下线；token 有效 24 小时，凭心跳滑动续期。
心跳 POST/user/heartbeat
每 3~5 分钟调用一次，校验登录态/封禁/到期并续期 token。参数：token；返回 data.remaining 剩余秒数（-1 = 永久）。收到 412/415/416 应立即退出并提示。
卡密充值 POST/user/recharge
参数：username、password、card_key。账号过期后也可充值；未到期在现有到期时间上累加，已过期从当前时间起算。
云变量 POST/var/get · /var/set
需登录态（token）+ key，写入另需 value（≤8192 字符）。远程开关、公告、配置下发；把关键数据放服务端，验证不过就拿不到。
接入建议
- 心跳线程：登录后后台线程定时心跳，收到 412/415/416 立即退出并提示。
- token 保管：只放内存不落盘，程序重启重新登录。
- 机器码：取机器名 + 硬件序列号做哈希；用户换机由作者在后台一键重置。
- 防破解：关键数据放服务端下发（拿不到，而不是判空），配合 VMProtect 保护校验逻辑。
- 宽限策略：网络抖动允许本地宽限 1~2 次心跳失败，避免误杀正常用户。
SDK 示例
官方 Python 示例（零依赖，含完整签名实现）见项目 examples/client.py，其他语言照抄签名算法即可。
def sign(params: dict, secret: str) -> str:
items = '&'.join(f'{k}={params[k]}' for k in sorted(params) if k != 'sign')
return hashlib.md5((items + '&key=' + secret).encode()).hexdigest()