外观
卡密相关
卡密是 NullVerify 的核心授权方式。卡密具有完整的生命周期：激活 → 登录 → 心跳保活 → 退出/过期。
卡密登录
卡密首次登录，获取会话 Token。
POST /api/client/v1/card/login
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 卡密 |
| device_id | string | 是 | 设备唯一标识 |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串（≤36 位） |
| sign | string | 是 | 请求签名 |
成功响应
json
{
"code": 0,
"message": "ok",
"result": {
"card_type": "月卡",
"token": "abc123...",
"expires": "2024-12-31 23:59:59",
"expires_ts": 1735689599,
"config": "{}",
"server_time": 1703001600,
"hg": 30
}
}| 字段 | 类型 | 说明 |
|---|---|---|
| card_type | string | 卡密类型名称 |
| token | string | 会话令牌，后续接口需携带 |
| expires | string | 到期时间 |
| expires_ts | int | 到期时间戳 |
| config | string | 卡密配置信息 |
| server_time | int | 服务器当前时间戳 |
| hg | int | 建议心跳间隔（秒） |
相关错误码
| 错误码 | 说明 |
|---|---|
| 10218 | 卡密不可用（不存在） |
| 10210 | 卡密已过期 |
| 10212 | 卡密已被冻结 |
| 10213 | 卡密超过多开上限 |
| 10217 | 超出可绑定设备上限 |
| 10230 | 软件不存在，检查 app_key |
卡密心跳
保持卡密会话活跃，需要定时调用。
POST /api/client/v1/card/heartbeat
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 卡密 |
| token | string | 是 | 登录返回的会话令牌 |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串 |
| sign | string | 是 | 请求签名 |
成功响应
json
{
"code": 0,
"message": "ok",
"result": {
"expires": "2024-12-31 23:59:59",
"expires_ts": 1735689599,
"server_time": 1703001600
}
}相关错误码
| 错误码 | 说明 |
|---|---|
| 10214 | 登录状态已失效（超时/被踢/冻结） |
| 10210 | 卡密已过期 |
提示
建议使用登录返回的 hg 值作为心跳间隔。服务端实际超时时间由应用的 heartbeat_timeout_sec 配置决定，默认值为 1800 秒。
卡密退出
主动退出卡密会话。
POST /api/client/v1/card/logout
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 卡密 |
| token | string | 是 | 会话令牌 |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串 |
| sign | string | 是 | 请求签名 |
成功响应
json
{
"code": 0,
"message": "ok"
}注意
退出接口非幂等，对已失效的 token 重复调用会返回 10214。
解绑设备
将卡密从指定设备上解绑。
POST /api/client/v1/card/unbind-device
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 卡密 |
| device_id | string | 是 | 要解绑的设备标识 |
| token | string | 是 | 会话令牌 |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串 |
| sign | string | 是 | 请求签名 |
成功响应
json
{
"code": 0,
"message": "ok"
}解绑策略
开发者可在管理后台为每个应用配置解绑策略，解绑时除了清除设备绑定外，还会根据策略执行额外操作：
| 策略 | 行为 |
|---|---|
| 仅解除绑定 (默认) | 仅清除设备绑定，不影响卡密状态和有效期 |
| 重置为未使用 | 解绑后卡密恢复为未使用状态，可重新激活 |
| 扣减有效期 | 解绑后扣减指定小时数的有效期 |
| 增加有效期 | 解绑后增加指定小时数的有效期（鼓励解绑） |
注意
当策略为"扣减有效期"且卡密剩余时间不足以扣除时，接口返回错误码 10257（卡密剩余时间不足以解绑扣除）。此时解绑不会执行，需先充值续费再解绑。
相关错误码
| 错误码 | 说明 |
|---|---|
| 10218 | 卡密不可用 |
| 10255 | 该卡密不可解绑设备（解绑次数耗尽） |
| 10257 | 卡密剩余时间不足以解绑扣除 |
设置解绑密码
为卡密设置解绑密码，设置后可通过密码解绑设备。
POST /api/client/v1/card/unbind-password
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 卡密 |
| password | string | 是 | 解绑密码（6-10 位） |
| token | string | 是 | 会话令牌 |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串 |
| sign | string | 是 | 请求签名 |
密码解绑
使用解绑密码解绑设备，无需登录状态。
POST /api/client/v1/card/unbind-by-password
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 卡密 |
| password | string | 是 | 解绑密码（6-10 位） |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串 |
| sign | string | 是 | 请求签名 |
相关错误码
| 错误码 | 说明 |
|---|---|
| 10254 | 解绑密码不正确 |
| 10255 | 该卡密不可解绑设备 |
| 10257 | 卡密剩余时间不足以解绑扣除 |
卡密充值
使用未激活的卡密为已激活的卡密充值续费。
POST /api/client/v1/card/recharge
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 目标卡密（已激活） |
| use_card | string | 是 | 充值卡密（未使用） |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串 |
| sign | string | 是 | 请求签名 |
相关错误码
| 错误码 | 说明 |
|---|---|
| 10244 | 不能对未使用的卡密进行充值 |
| 10240 | 充值卡密不存在或已被使用 |
| 10241 | 充值卡密已被使用 |
| 10256 | 卡密多开配置不相等，不能充值 |
获取卡密配置
获取卡密的自定义配置信息。
GET /api/client/v1/card/config
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 卡密 |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串 |
| sign | string | 是 | 请求签名 |
成功响应
json
{
"code": 0,
"message": "ok",
"result": {
"config": "{\"vip_level\": 1}"
}
}修改卡密配置
修改卡密的自定义配置信息。
POST /api/client/v1/card/config
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_key | string | 是 | 应用标识 |
| card | string | 是 | 卡密 |
| config | string | 否 | 配置内容（JSON 字符串） |
| timestamp | int | 是 | 当前时间戳（秒） |
| nonce | string | 是 | 随机字符串 |
| sign | string | 是 | 请求签名 |
对应实现
- Handler:
internal/module/card/handler_client.go - DTO:
internal/module/card/dto_client.go