API 接口文档

{ "cardKey": "XXXX-XXXX-XXXX-XXXX-XXXX", "username": "user1", "password": "pass123456" }

• 用户名不存在 → 注册新账号，到期时间 = 当前时间 + 卡密时长
• 用户名已存在 → 续期（到期时间往后累加卡密时长）
• 卡密兑换后标记为已使用
• 防爆破：同一应用+用户名连续兑换失败（卡密已使用/已停用）5 次，锁定 15 分钟（返回 1004）

{ "username": "user1", "expireAt": "<ISO8601>" }

{
  "username": "user1",
  "password": "pass123456",
  "clientVer": "1.0.0",
  "machineCode": "<可选，机器码，最长 64>",
  "clientHash": "<可选，客户端哈希，最长 64>",
  "deviceType": "<可选，pc / mobile / other，缺省按 other>"
}

{
  "token": "<会话token>",
  "username": "user1",
  "expireAt": "2026-09-15T12:00:00.000Z",
  "announcement": "公告内容",
  "latestVersion": "1.2.0",
  "updateUrl": "https://...",
  "forceUpdate": false,
  "heartbeatIntervalSec": 60
}

• 应用开启「单点在线」时，新登录会顶掉旧会话（旧端下次心跳收到 4005；被顶信息不再通过事件下发，见第 3 章）
• 机器绑定（machineBind）：开启后登录必须携带 machineCode（未携带返回 4007 并提示升级客户端）。同一用户最多绑定 maxDevices 台设备；已有设备登录刷新活跃时间，新设备超限返回 4007。管理端可随时在「用户详情-设备」里解绑某台设备
• 客户端哈希白名单（requireClientHash）：开启后登录必须携带 clientHash，且须命中管理端配置的 allowedClientHashes（换行分隔的 SHA256 白名单），否则返回 4008
• 老 SDK 不传以上可选字段时：仅在应用开启对应开关时才受影响，否则行为不变

{ "machineCode": "<可选，机器码>" }

老 SDK 发 {} 或空 body 不受影响。当应用开启机器绑定、会话已绑定机器码、且请求携带的 machineCode 与会话不一致时，返回 4004。

{
  "serverTime": "...",
  "expireAt": "...",
  "remainSec": 3540,
  "events": [ { "type": "announcement", "payload": "...", "createdAt": "..." } ]
}

• events 为该会话待送达事件（最多 20 条/次，无事件为空数组），送达即消费，不会重复下发，详见第 3 章
• 客户端应按 heartbeatIntervalSec（服务端建议值）周期调用
• 超过应用配置的心跳超时未心跳，会话被清扫器删除，下次心跳返回 4004

{ "announcement": "...", "latestVersion": "...", "updateUrl": "...", "forceUpdate": false }

{ "events": [ { "type": "...", "payload": "...", "createdAt": "..." } ] }

与心跳下发同源：返回即标记已消费，二次拉取不会重复返回。供不方便等心跳周期的场景主动拉取。

{ "name": "license_flags" }

{ "value": "<管理端配置的变量值>" }

• mode = 0（免登录）：仅需签名通道
• mode = 1（需 Token）：另需 Authorization: Bearer <token>，token 无效返回 4004
• 变量不存在返回 4010；被管理员冻结返回 4009

{ "name": "sign_license", "payload": "<可选，最长 8192 的字符串>" }

• mode 鉴权与错误码同云变量（mode=1 需 token；4009 冻结 / 4010 不存在）
• HMAC_SIGN 的 secret 由管理端配置（为空时用 appSecret 派生 macKey），客户端永远拿不到密钥

• 基础：name / latestVersion / updateUrl / forceUpdate / announcement / heartbeatTimeoutSec / singleOnline / status
• 安全配置：machineBind（bool）、maxDevices（1-100）、requireClientHash（bool）、allowedClientHashes（换行分隔 SHA256 白名单）、encryptResponse（bool，响应加密开关）

{ "usernames": ["user1"], "type": "announcement", "message": "维护通知" }

usernames 缺省 = 推给该应用全部活跃用户；type 仅 announcement / custom。返回 { "pushed": <人数> }。事件由客户端心跳或 GET /api/v1/events 消费。

{ "appId": 1, "count": 100, "durationMinutes": 43200, "batchNo": "<可选>", "remark": "<可选>" }

count 1-1000；durationMinutes ≥ 1。