admin/verify

Fork 0

Files

T

Admin afe67d704e Initial commit: 网络验证平台

2026-04-27 17:22:56 +08:00

11 KiB

Raw Blame History

应用对接 API 文档

概述

本文档描述了开发者应用程序对接网络验证平台的 API 接口。所有 API 请求的基础路径为：

http://your-domain:8080/api/v1/app/{appKey}

其中 {appKey} 为开发者在后台创建应用时获取的应用密钥。

通用说明

请求格式

所有请求使用 JSON 格式
Content-Type: application/json

响应格式

{
  "code": 200,
  "message": "success",
  "data": {}
}

错误码

错误码	说明
200	成功
400	参数错误
404	资源不存在
500	服务器错误

应用信息接口

获取应用信息

获取应用的基本信息。

请求

GET /api/v1/app/{appKey}/info

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "应用名称",
    "description": "应用描述",
    "status": "active"
  }
}

检查更新

检查应用是否有新版本。

请求

GET /api/v1/app/{appKey}/check-update?version=1.0.0

参数

参数名	类型	必填	说明
version	string	否	当前客户端版本号

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "has_update": true,
    "latest_version": "1.0.1",
    "download_url": "https://example.com/download/1.0.1",
    "update_notes": "修复若干bug",
    "update_strategy": "optional",
    "update_method": "manual"
  }
}

响应字段说明

字段名	类型	说明
has_update	boolean	是否有更新
latest_version	string	最新版本号
download_url	string	下载地址
update_notes	string	更新说明
update_strategy	string	更新策略：`optional`(可选更新) 或 `force`(强制更新)
update_method	string	更新方式：`auto`(自动更新) 或 `manual`(手动更新)

获取公告列表

获取应用的公告列表。

请求

GET /api/v1/app/{appKey}/announcements

响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "公告标题",
      "content": "公告内容",
      "type": "info",
      "priority": "normal",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

用户认证接口

用户注册

注册新用户。

请求

POST /api/v1/app/{appKey}/register

请求体

{
  "username": "testuser",
  "password": "123456",
  "device_id": "DEVICE_001"
}

参数名	类型	必填	说明
username	string	是	用户名
password	string	是	密码
device_id	string	否	设备ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "user_id": 1,
    "token": ""
  }
}

用户登录

用户登录验证。

请求

POST /api/v1/app/{appKey}/login

请求体

{
  "username": "testuser",
  "password": "123456",
  "device_id": "DEVICE_001"
}

参数名	类型	必填	说明
username	string	是	用户名
password	string	是	密码
device_id	string	否	设备ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "user_id": 1,
    "token": ""
  }
}

账户管理接口

获取账户信息

获取用户账户详细信息。

请求

GET /api/v1/app/{appKey}/account

请求体

{
  "user_id": 1
}

参数名	类型	必填	说明
user_id	uint	是	用户ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "user_id": 1,
    "username": "testuser",
    "expire_time": "2024-12-31T23:59:59Z",
    "status": "active"
  }
}

心跳检测

客户端心跳检测，保持在线状态。

请求

POST /api/v1/app/{appKey}/heartbeat

请求体

{
  "user_id": 1
}

参数名	类型	必填	说明
user_id	uint	是	用户ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "心跳成功"
  }
}

充值与试用接口

卡密充值

使用卡密为账户充值。

请求

POST /api/v1/app/{appKey}/recharge

请求体

{
  "user_id": 1,
  "card_key": "CARD_KEY_123456"
}

参数名	类型	必填	说明
user_id	uint	是	用户ID
card_key	string	是	卡密

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "充值成功",
    "value": 30
  }
}

试用申请

申请试用功能。

请求

POST /api/v1/app/{appKey}/trial

请求体

{
  "user_id": 1
}

参数名	类型	必填	说明
user_id	uint	是	用户ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "试用成功",
    "duration": 7
  }
}

设备管理接口

获取设备列表

获取用户绑定的设备列表。

请求

GET /api/v1/app/{appKey}/devices

请求体

{
  "user_id": 1
}

参数名	类型	必填	说明
user_id	uint	是	用户ID

响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "device_id": "DEVICE_001",
      "user_id": 1
    }
  ]
}

解绑设备

解绑指定设备。

请求

POST /api/v1/app/{appKey}/unbind-device

请求体

{
  "user_id": 1,
  "device_id": "DEVICE_001"
}

参数名	类型	必填	说明
user_id	uint	是	用户ID
device_id	string	是	设备ID

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "解绑成功"
  }
}

云端数据接口

注意：云端数据接口需要用户登录认证，需要在请求头中携带JWT token：

Authorization: Bearer {token}

获取云端常量

获取应用设置的云端常量。

请求

GET /api/v1/app/{appKey}/constants

响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "常量名称",
      "key": "CONSTANT_KEY",
      "value": "常量值",
      "var_type": "string",
      "description": "常量描述"
    }
  ]
}

获取指定云端常量

根据key获取指定的云端常量。

请求

GET /api/v1/app/{appKey}/constants/{key}

路径参数

参数名	类型	必填	说明
key	string	是	常量key

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "常量名称",
    "key": "CONSTANT_KEY",
    "value": "常量值",
    "var_type": "string",
    "description": "常量描述"
  }
}

获取云端变量

获取用户的云端变量。

请求

GET /api/v1/app/{appKey}/variables

响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "变量名称",
      "key": "VARIABLE_KEY",
      "default_value": "默认值",
      "var_type": "string",
      "scope": "user",
      "description": "变量描述"
    }
  ]
}

获取指定云端变量

根据key获取指定的云端变量。

请求

GET /api/v1/app/{appKey}/variables/{key}

路径参数

参数名	类型	必填	说明
key	string	是	变量key

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "变量名称",
    "key": "VARIABLE_KEY",
    "default_value": "默认值",
    "var_type": "string",
    "scope": "user",
    "description": "变量描述"
  }
}

更新云端变量

更新用户的云端变量。

请求

POST /api/v1/app/{appKey}/variables

请求体

{
  "variables": {
    "key1": "value1",
    "key2": "value2"
  }
}

参数名	类型	必填	说明
variables	object	是	变量键值对

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "更新成功"
  }
}

调用云端函数

调用云端自定义函数。

请求

POST /api/v1/app/{appKey}/call-function

请求体

{
  "name": "function_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

参数名	类型	必填	说明
name	string	是	函数名称
params	object	否	函数参数

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "result": null
  }
}

动态代码接口

注意：动态代码接口需要用户登录认证，需要在请求头中携带JWT token：

Authorization: Bearer {token}

获取动态代码

获取应用的动态代码。

请求

GET /api/v1/app/{appKey}/dynamic-code

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "code": "function hello() {\n  return 'Hello World';\n}"
  }
}

更新动态代码

更新应用的动态代码。

请求

POST /api/v1/app/{appKey}/dynamic-code

请求体

{
  "code": "function hello() {\n  return 'Hello World';\n}"
}

参数名	类型	必填	说明
code	string	是	Goja代码（JavaScript语法）

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "message": "更新成功"
  }
}

说明

动态代码使用Goja引擎执行（Go语言的JavaScript实现）
支持完整的JavaScript语法
代码执行环境受限，无法访问系统资源
建议代码简洁高效，避免复杂逻辑

错误响应示例

应用不存在

{
  "code": 404,
  "message": "应用不存在",
  "data": null
}

参数错误

{
  "code": 400,
  "message": "参数错误",
  "data": null
}

用户不存在

{
  "code": 404,
  "message": "用户不存在",
  "data": null
}

卡密已使用

{
  "code": 400,
  "message": "卡密已使用",
  "data": null
}

接入流程

创建应用：在开发者后台创建应用，获取 appKey 和 secretKey
配置应用：设置应用的绑定类型、最大设备数、试用功能等
创建卡密类型：根据业务需求创建卡密类型（订阅/计时/点卡）
生成卡密：生成卡密供用户充值使用
客户端对接：按照本文档进行客户端开发

安全建议

HTTPS：生产环境建议使用 HTTPS 加密传输
签名验证：敏感操作建议添加签名验证
频率限制：建议对 API 调用频率进行限制
数据加密：敏感数据建议加密存储和传输

版本历史

版本	日期	说明
1.1.0	2024-03-10	新增动态代码接口（使用Goja引擎）
1.0.0	2024-01-01	初始版本

11 KiB Raw Blame History

应用对接 API 文档

概述

通用说明

请求格式

响应格式

错误码

应用信息接口

获取应用信息

检查更新

获取公告列表

用户认证接口

用户注册

用户登录

账户管理接口

获取账户信息

心跳检测

充值与试用接口

卡密充值

试用申请

设备管理接口

获取设备列表

解绑设备

云端数据接口

获取云端常量

获取指定云端常量

获取云端变量

获取指定云端变量

更新云端变量

调用云端函数

动态代码接口

获取动态代码

更新动态代码

错误响应示例

应用不存在

参数错误

用户不存在

卡密已使用

接入流程

安全建议

版本历史

11 KiB

Raw Blame History