Admin
801 lines
11 KiB
Markdown
801 lines
11 KiB
Markdown
# 应用对接 API 文档
|
|
|
|
## 概述
|
|
|
|
本文档描述了开发者应用程序对接网络验证平台的 API 接口。所有 API 请求的基础路径为：
|
|
|
|
```
|
|
http://your-domain:8080/api/v1/app/{appKey}
|
|
```
|
|
|
|
其中 `{appKey}` 为开发者在后台创建应用时获取的应用密钥。
|
|
|
|
## 通用说明
|
|
|
|
### 请求格式
|
|
|
|
- 所有请求使用 JSON 格式
|
|
- Content-Type: `application/json`
|
|
|
|
### 响应格式
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
### 错误码
|
|
|
|
| 错误码 | 说明 |
|
|
|--------|------|
|
|
| 200 | 成功 |
|
|
| 400 | 参数错误 |
|
|
| 404 | 资源不存在 |
|
|
| 500 | 服务器错误 |
|
|
|
|
---
|
|
|
|
## 应用信息接口
|
|
|
|
### 获取应用信息
|
|
|
|
获取应用的基本信息。
|
|
|
|
**请求**
|
|
|
|
```
|
|
GET /api/v1/app/{appKey}/info
|
|
```
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"name": "应用名称",
|
|
"description": "应用描述",
|
|
"status": "active"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 检查更新
|
|
|
|
检查应用是否有新版本。
|
|
|
|
**请求**
|
|
|
|
```
|
|
GET /api/v1/app/{appKey}/check-update?version=1.0.0
|
|
```
|
|
|
|
**参数**
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| version | string | 否 | 当前客户端版本号 |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"username": "testuser",
|
|
"password": "123456",
|
|
"device_id": "DEVICE_001"
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| username | string | 是 | 用户名 |
|
|
| password | string | 是 | 密码 |
|
|
| device_id | string | 否 | 设备ID |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"user_id": 1,
|
|
"token": ""
|
|
}
|
|
}
|
|
```
|
|
|
|
### 用户登录
|
|
|
|
用户登录验证。
|
|
|
|
**请求**
|
|
|
|
```
|
|
POST /api/v1/app/{appKey}/login
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"username": "testuser",
|
|
"password": "123456",
|
|
"device_id": "DEVICE_001"
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| username | string | 是 | 用户名 |
|
|
| password | string | 是 | 密码 |
|
|
| device_id | string | 否 | 设备ID |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"user_id": 1,
|
|
"token": ""
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 账户管理接口
|
|
|
|
### 获取账户信息
|
|
|
|
获取用户账户详细信息。
|
|
|
|
**请求**
|
|
|
|
```
|
|
GET /api/v1/app/{appKey}/account
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"user_id": 1
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| user_id | uint | 是 | 用户ID |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"user_id": 1
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| user_id | uint | 是 | 用户ID |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"message": "心跳成功"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 充值与试用接口
|
|
|
|
### 卡密充值
|
|
|
|
使用卡密为账户充值。
|
|
|
|
**请求**
|
|
|
|
```
|
|
POST /api/v1/app/{appKey}/recharge
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"user_id": 1,
|
|
"card_key": "CARD_KEY_123456"
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| user_id | uint | 是 | 用户ID |
|
|
| card_key | string | 是 | 卡密 |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"message": "充值成功",
|
|
"value": 30
|
|
}
|
|
}
|
|
```
|
|
|
|
### 试用申请
|
|
|
|
申请试用功能。
|
|
|
|
**请求**
|
|
|
|
```
|
|
POST /api/v1/app/{appKey}/trial
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"user_id": 1
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| user_id | uint | 是 | 用户ID |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"message": "试用成功",
|
|
"duration": 7
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 设备管理接口
|
|
|
|
### 获取设备列表
|
|
|
|
获取用户绑定的设备列表。
|
|
|
|
**请求**
|
|
|
|
```
|
|
GET /api/v1/app/{appKey}/devices
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"user_id": 1
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| user_id | uint | 是 | 用户ID |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": [
|
|
{
|
|
"device_id": "DEVICE_001",
|
|
"user_id": 1
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 解绑设备
|
|
|
|
解绑指定设备。
|
|
|
|
**请求**
|
|
|
|
```
|
|
POST /api/v1/app/{appKey}/unbind-device
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"user_id": 1,
|
|
"device_id": "DEVICE_001"
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| user_id | uint | 是 | 用户ID |
|
|
| device_id | string | 是 | 设备ID |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"message": "解绑成功"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 云端数据接口
|
|
|
|
**注意**：云端数据接口需要用户登录认证，需要在请求头中携带JWT token：
|
|
```
|
|
Authorization: Bearer {token}
|
|
```
|
|
|
|
### 获取云端常量
|
|
|
|
获取应用设置的云端常量。
|
|
|
|
**请求**
|
|
|
|
```
|
|
GET /api/v1/app/{appKey}/constants
|
|
```
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"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 |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"id": 1,
|
|
"name": "常量名称",
|
|
"key": "CONSTANT_KEY",
|
|
"value": "常量值",
|
|
"var_type": "string",
|
|
"description": "常量描述"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 获取云端变量
|
|
|
|
获取用户的云端变量。
|
|
|
|
**请求**
|
|
|
|
```
|
|
GET /api/v1/app/{appKey}/variables
|
|
```
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"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 |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"variables": {
|
|
"key1": "value1",
|
|
"key2": "value2"
|
|
}
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| variables | object | 是 | 变量键值对 |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"message": "更新成功"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 调用云端函数
|
|
|
|
调用云端自定义函数。
|
|
|
|
**请求**
|
|
|
|
```
|
|
POST /api/v1/app/{appKey}/call-function
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"name": "function_name",
|
|
"params": {
|
|
"param1": "value1",
|
|
"param2": "value2"
|
|
}
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| name | string | 是 | 函数名称 |
|
|
| params | object | 否 | 函数参数 |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"result": null
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 动态代码接口
|
|
|
|
**注意**：动态代码接口需要用户登录认证，需要在请求头中携带JWT token：
|
|
```
|
|
Authorization: Bearer {token}
|
|
```
|
|
|
|
### 获取动态代码
|
|
|
|
获取应用的动态代码。
|
|
|
|
**请求**
|
|
|
|
```
|
|
GET /api/v1/app/{appKey}/dynamic-code
|
|
```
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"code": "function hello() {\n return 'Hello World';\n}"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 更新动态代码
|
|
|
|
更新应用的动态代码。
|
|
|
|
**请求**
|
|
|
|
```
|
|
POST /api/v1/app/{appKey}/dynamic-code
|
|
```
|
|
|
|
**请求体**
|
|
|
|
```json
|
|
{
|
|
"code": "function hello() {\n return 'Hello World';\n}"
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
|--------|------|------|------|
|
|
| code | string | 是 | Goja代码（JavaScript语法） |
|
|
|
|
**响应**
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": {
|
|
"message": "更新成功"
|
|
}
|
|
}
|
|
```
|
|
|
|
**说明**
|
|
|
|
- 动态代码使用Goja引擎执行（Go语言的JavaScript实现）
|
|
- 支持完整的JavaScript语法
|
|
- 代码执行环境受限，无法访问系统资源
|
|
- 建议代码简洁高效，避免复杂逻辑
|
|
|
|
---
|
|
|
|
## 错误响应示例
|
|
|
|
### 应用不存在
|
|
|
|
```json
|
|
{
|
|
"code": 404,
|
|
"message": "应用不存在",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
### 参数错误
|
|
|
|
```json
|
|
{
|
|
"code": 400,
|
|
"message": "参数错误",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
### 用户不存在
|
|
|
|
```json
|
|
{
|
|
"code": 404,
|
|
"message": "用户不存在",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
### 卡密已使用
|
|
|
|
```json
|
|
{
|
|
"code": 400,
|
|
"message": "卡密已使用",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 接入流程
|
|
|
|
1. **创建应用**：在开发者后台创建应用，获取 `appKey` 和 `secretKey`
|
|
2. **配置应用**：设置应用的绑定类型、最大设备数、试用功能等
|
|
3. **创建卡密类型**：根据业务需求创建卡密类型（订阅/计时/点卡）
|
|
4. **生成卡密**：生成卡密供用户充值使用
|
|
5. **客户端对接**：按照本文档进行客户端开发
|
|
|
|
## 安全建议
|
|
|
|
1. **HTTPS**：生产环境建议使用 HTTPS 加密传输
|
|
2. **签名验证**：敏感操作建议添加签名验证
|
|
3. **频率限制**：建议对 API 调用频率进行限制
|
|
4. **数据加密**：敏感数据建议加密存储和传输
|
|
|
|
## 版本历史
|
|
|
|
| 版本 | 日期 | 说明 |
|
|
|------|------|------|
|
|
| 1.1.0 | 2024-03-10 | 新增动态代码接口（使用Goja引擎） |
|
|
| 1.0.0 | 2024-01-01 | 初始版本 |
|