API 接口文档

用 API 把 Clever VPN 与你的 CRM 打通，编程化管理你的客户（用户）：创建、查询、更新、删除。当前 API 开放 客户（customers） 数据。

🔑 快速开始

登录后台，进入账户 → API 访问。
点击「启用 API」，系统生成一个 cv_api_… Token；之后可随时「重新生成」或「停用」。
在所有请求的 Authorization 请求头携带该 Token（见下）。

认证

每个请求都需携带 API Token：

Authorization: Bearer cv_api_<your-token>

Token 格式为 cv_api_<blob>。网关根据 Token 定位到你的租户，后端再校验 Token 是否有效（已启用且与服务器端存储的 Token 完全匹配）。校验失败返回 401。

基础地址

https://api.clever-vpn.org/api/v2

以下端点均基于此地址，例如列表为 https://api.clever-vpn.org/api/v2/customers。

客户（customers）端点

操作	Method	URL	说明
列表	GET	/customers	返回数组；支持过滤、排序、分页
详情	GET	/customers/:id	单条记录；不存在返回 404
创建	POST	/customers	201 + 记录；激活码自动生成
更新	PATCH	/customers/:id	部分字段更新
删除	DELETE	/customers/:id	软删除，返回 `{"success":true}`

列表：过滤 / 排序 / 分页

过滤

按字段精确 / 模糊匹配，多个条件为 AND 关系。

?filters[name][$contains]=ali
?filters[email][$eq]=alice@example.com
?filters[frozen][$eq]=0
?filters[_fsm_status][$eq]=active
?filters[expire_date][$lte]=2026-12-31
?filters[id][$in][]=1&filters[id][$in][]=2

排序

?sort=name:asc
?sort=_created_at:desc   （默认：按创建时间倒序）

分页

列表返回纯数组（不含 total）。用 pagination[page] 与 pagination[pageSize] 翻页；判断是否还有下一页：本页返回条数 ≥ pageSize 时继续取下一页。

?pagination[page]=2&pagination[pageSize]=100

可写字段

字段	类型	说明
name	string	客户名称
email	string	邮箱
phone	string	手机号
memo	string	备注
licence_limit	number	设备数上限
frozen	number	冻结（0 / 1）
expire_date	string	到期时间（ISO 时间）
traffic_balance	number	流量额度（GB）
monthly_cost	number	月费（分）
up_mbps / down_mbps	number	限速（Mbps）

内部字段（下划线开头，如 _fsm_status / _created_at / _is_deleted）为系统管理，创建 / 更新时会被忽略或自动生成，不可由 API 写入。code（激活码）由系统自动生成。

示例（curl）

创建客户

curl -X POST "https://api.clever-vpn.org/api/v2/customers" \
  -H "Authorization: Bearer cv_api_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com","phone":"+8613800000000"}'

响应（201）：

{"id":1,"code":"1234567890123456","name":"Alice",
 "email":"alice@example.com","_created_at":"2026-08-26T00:00:00.000Z"}

列出客户（按名称模糊搜索）

curl -G "https://api.clever-vpn.org/api/v2/customers" \
  -H "Authorization: Bearer cv_api_xxx" \
  --data-urlencode "filters[name][$contains]=ali"

更新客户

curl -X PATCH "https://api.clever-vpn.org/api/v2/customers/1" \
  -H "Authorization: Bearer cv_api_xxx" \
  -H "Content-Type: application/json" \
  -d '{"memo":"VIP","frozen":1}'

删除客户（软删除）

curl -X DELETE "https://api.clever-vpn.org/api/v2/customers/1" \
  -H "Authorization: Bearer cv_api_xxx"

错误

状态码	说明
401	Token 缺失 / 格式错误 / 无效（已停用或已被重新生成）
400	请求体非法 / 参数不合法
404	资源不存在

错误响应格式：{"error":"错误描述"}

范围与安全

API Token 仅开放 customers（客户 / 用户）数据；服务器、线路、设备、计费等资源对 API 不可见。
删除为软删除：客户在列表中被隐藏，数据保留可恢复。
「重新生成」或「停用」后，旧 Token 立即失效。
Token 是 bearer 凭据，请存入 CRM 的密钥库，勿写入前端代码、日志或分享。
API 权限与你在后台一致（管理你自己的客户），不包含任何管理员能力。

在后台管理 API Token →