# v5 API

客户端 API 使用 JSON 请求体，机器码要求为 32 个字符。成功验证返回 `licenseTicket`，票据绑定当前机器码。

| 方法 | 路径 | 作用 |
| --- | --- | --- |
| POST | `/api/card/verify` | 激活或登录卡密 |
| POST | `/api/card/heartbeat` | 更新设备心跳 |
| POST | `/api/card/unbind` | 当前机器自助解绑 |
| POST | `/api/card/devices` | 查询本卡设备池 |
| GET | `/api/admin/account` | 查询当前管理员账户 |
| PUT | `/api/admin/account` | 修改管理员账户和密码 |
| POST | `/api/admin/ticket` | 根据有效卡密和机器码申请 RSA 票据 |
| GET | `/api/admin/packages` | 查询套餐 |
| POST | `/api/admin/packages` | 创建卡类型和套餐策略 |
| POST | `/api/admin/cards/batch` | 按软件名称和卡类型批量生成卡密 |
| POST | `/api/admin/cards/batch-delete` | 批量删除未激活卡密 |
| GET | `/api/admin/cards` | 分页查询卡密 |
| POST | `/api/admin/cards/{id}/freeze` | 冻结卡密 |
| POST | `/api/admin/cards/{id}/unfreeze` | 解冻卡密 |
| PUT | `/api/admin/packages/{id}` | 修改套餐设备策略 |
| PUT | `/api/admin/cards/{id}/device-limit` | 修改单卡覆盖策略 |
| GET | `/api/admin/cards/{id}/devices` | 查询卡密设备池 |
| POST | `/api/admin/devices/{id}/kick` | 后台解绑设备 |
| GET | `/api/admin/dashboard/online` | 查询在线设备 |

管理 API 可使用 `X-Admin-Key` 配置密钥进行服务端调用；管理后台登录后使用 PHP Session，并为写操作携带 `X-CSRF-Token`。批量出卡接口支持 `packageId`，也支持通过 `softwareName` 与 `packageName` 自动匹配套餐。接口只在响应中返回一次明文卡密，数据库仅保存 SHA-256 哈希。

`POST /api/admin/cards/batch-delete` 请求体为 `{"ids": [1,2,3]}`（单次最多 200 个）。仅删除 `ActivatedAt` 为空（未激活）的卡密，并连带清理其绑定日志与设备记录；只要批次中包含已激活卡密则整批拒绝，不删除任何记录。该接口需登录 Session 且携带 `X-CSRF-Token`。

创建或更新套餐时，`durationDays` 范围为 1-36500，`maxDevices` 范围为 1-100，`rebindDeductDays` 和 `extraPenaltyDays` 范围为 0-30，`overflowPolicy` 取值为 0、1 或 2。

账户更新请求字段为 `username`、`currentPassword`、`newPassword` 和 `confirmPassword`。账户名允许 3-50 个 ASCII 字母、数字、下划线、点号或连字符；新密码可留空以仅修改账户名，填写时长度为 8-128 个字符。

## RSA 票据申请

请求头：Session 登录请求需要 `X-CSRF-Token`；服务端调用可使用 `X-Admin-Key`。

请求体：

```json
{
  "cardKey": "<卡密明文>",
  "machineCode": "<32位机器码>"
}
```

成功响应包含 `licenseTicket`、`expireUnix`、`remainDays` 和 `packageName`。卡密必须处于已激活、有效且未过期状态。服务端仅返回签名票据，私钥保留在服务端。