公开 API 文档
激活码服务接入工作区
面向插件开发者、客户端、测试同学与合作方统一展示正式接口、授权模型、多语言示例与联调路径。
无需登录即可查阅
推荐先看概览，再按 activate → status → consume 的正式流程完成接入；旧插件仅在兼容场景下继续使用 /api/verify。
正式接口
3 个
推荐插件或客户端正式接入时使用 activate / status / consume 三段式流程。
兼容入口
1 个
旧接口 /api/verify 仍可使用，但新业务不建议继续把它当正式扣次入口。
建议调研路径
6 步
从 projectKey、设备绑定、幂等消费到后台日志核对，形成完整联调闭环。
推荐调研路径
建议把接口调研理解为一个业务闭环：先准备 projectKey，再绑定、查询、扣次，最后用后台日志和 smoke 脚本回证。
01
先确认项目与授权模型
在项目管理里确认当前插件对应的 projectKey，并区分是时间型还是次数型激活码。
你会得到： 避免把错误项目的激活码带入联调，也能提前判断是否需要 requestId。
02
先调 activate 绑定设备
用户首次输入激活码时调用 /api/license/activate，让系统先绑定 machineId。
你会得到： 时间型会从此刻开始计算有效期；次数型只绑定设备，不会立即扣次。
03
再调 status 观察返回字段
拿同一组 code + machineId 调用 /api/license/status，确认 expiresAt / remainingCount / valid 等字段。
你会得到： 可以快速验证当前激活码是否处于正确状态，便于插件前端显示授权信息。
04
真实业务再调 consume
只有发生真实业务动作时才调用 /api/license/consume，并且推荐始终带上 requestId。
你会得到： 同一 requestId 会幂等返回，不会因为客户端重试或网络抖动重复扣次。
05
去后台消费日志按 requestId 反查
联调时把 requestId、machineId 带到“消费日志”页搜索，核对每次扣次是否正确落库。
你会得到： 可以把接口行为与后台日志一一对应，快速定位重复请求、错误设备或项目混用问题。
06
最后跑 smoke 脚本做回归
本地启动后执行 smoke:license-api，让项目自动走完登录、建项目、生成卡、激活、状态、幂等扣次。
你会得到： 把接口调研从人工验证升级为可重复的联调回归流程。
TIME
时间型激活码
适合按天/月/年计费的授权模式，首次激活后开始计算有效期。
首次 activate 时写入 usedBy / usedAt / expiresAt。
后续 status / consume 只做有效性校验，不扣减次数。
插件展示剩余有效期时，优先使用 expiresAt / expires_at。
COUNT
次数型激活码
适合浏览器插件、桌面工具等按次数消耗的场景。
activate 只绑定设备，不扣减 remainingCount。
consume 每次成功调用扣减 1 次，且支持 requestId 幂等。
status 可用于展示剩余次数、是否已激活与当前是否仍有效。
PROJECT
多项目隔离
同一个服务端可同时给多个产品、插件或客户提供独立授权空间。
每张激活码都归属于某个 projectKey。
同一台设备可以在不同 projectKey 下分别绑定激活码。
项目停用后，正式接口会直接返回“项目已停用”。
通用请求字段
正式接口支持 camelCase / snake_case 双写法，便于不同语言和历史客户端接入。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| projectKey / project_key | string | 否 | 项目标识；不传时默认走 default 项目。 |
| code | string | 是 | 激活码正文。 |
| machineId / machine_id | string | 是 | 设备唯一标识，建议插件本地持久化一个稳定 UUID。 |
| requestId / request_id | string | 仅 consume 推荐 | 请求幂等键；同一 requestId 的 consume 只会成功扣减一次。 |
统一响应字段
正式接口会同时返回 camelCase 与 snake_case，便于浏览器插件、桌面端和脚本工具统一接入。
| 字段 | 类型 | 返回时机 | 说明 |
|---|---|---|---|
| success | boolean | 总是返回 | 业务层是否成功。 |
| message | string | 总是返回 | 提示信息或失败原因。 |
| licenseMode / license_mode | TIME | COUNT | null | 按场景返回 | 授权类型。 |
| expiresAt / expires_at | string | null | 时间型常用 | 时间型过期时间。 |
| remainingCount / remaining_count | number | null | 次数型常用 | 次数型剩余次数。 |
| isActivated / is_activated | boolean | null | 按场景返回 | 当前激活码是否已绑定到设备。 |
| valid | boolean | null | 按场景返回 | 当前是否仍有效。 |
| idempotent | boolean | null | consume 常用 | 本次是否命中了 requestId 幂等重放。 |