# 应用对接 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 | 初始版本 |