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