345 lines
7.6 KiB
Markdown
345 lines
7.6 KiB
Markdown
# ///
|
|
# API.md
|
|
# 描述：WXAuto Center API 接口文档
|
|
# 作者：AI Generated
|
|
# 创建日期：2026-04-06
|
|
# 更新日期：2026-04-06
|
|
# ///
|
|
|
|
# WXAuto Center API 接口文档
|
|
|
|
## 概述
|
|
|
|
本系统提供完整的 RESTful API，支持节点管理、消息发送、插件管理、外部程序接入、Webhook 管理等功能。所有 API 均使用 JSON 格式进行请求和响应。
|
|
|
|
## 基础信息
|
|
|
|
| 项目 | 说明 |
|
|
|------|------|
|
|
| Base URL | `http://{host}:{port}/api/v1` |
|
|
| 默认端口 | 8080 |
|
|
| 内部 API 认证 | Header: `X-API-Key: your-external-api-key` |
|
|
| 外部 API 认证 | Header: `X-ExternalKey: your-external-api-key` |
|
|
| 响应格式 | JSON |
|
|
|
|
## API 列表
|
|
|
|
### 节点管理 `/api/v1/nodes`
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | `/nodes/` | 获取所有节点 |
|
|
| GET | `/nodes/{node_id}` | 获取指定节点信息 |
|
|
| POST | `/nodes/` | 添加节点 |
|
|
| PUT | `/nodes/{node_id}` | 更新节点信息 |
|
|
| DELETE | `/nodes/{node_id}` | 删除节点 |
|
|
| GET | `/nodes/{node_id}/status` | 检查节点状态 |
|
|
| POST | `/nodes/{node_id}/enable` | 启用节点 |
|
|
| POST | `/nodes/{node_id}/disable` | 禁用节点 |
|
|
| GET | `/nodes/{node_id}/friends` | 获取节点好友列表 |
|
|
| GET | `/nodes/{node_id}/groups` | 获取节点群列表 |
|
|
| GET | `/nodes/{node_id}/messages/{chat_name}` | 获取聊天消息 |
|
|
|
|
### 消息管理 `/api/v1/messages`
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| POST | `/messages/send` | 发送消息 |
|
|
| POST | `/messages/send_group` | 发送群消息 |
|
|
| POST | `/messages/batch` | 批量发送消息 |
|
|
| POST | `/messages/template/{node_id}/{who}` | 发送模板消息 |
|
|
| GET | `/messages/history/{node_id}/{chat_name}` | 获取消息历史 |
|
|
|
|
### 插件管理 `/api/v1/plugins`
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | `/plugins/` | 获取所有插件 |
|
|
| GET | `/plugins/{plugin_name}` | 获取插件详情 |
|
|
| GET | `/plugins/{plugin_name}/schema` | 获取插件表单Schema |
|
|
| POST | `/plugins/{plugin_name}/enable` | 启用插件 |
|
|
| POST | `/plugins/{plugin_name}/disable` | 禁用插件 |
|
|
| PUT | `/plugins/{plugin_name}/config` | 更新插件配置 |
|
|
| POST | `/plugins/{plugin_name}/execute` | 执行插件 |
|
|
| GET | `/plugins/{plugin_name}/logs` | 获取插件日志 |
|
|
| POST | `/plugins/{plugin_name}/logs/clear` | 清空插件日志 |
|
|
| GET | `/plugins/type/{plugin_type}` | 按类型获取插件 |
|
|
|
|
### 回调接口 `/api/v1/callback`
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| POST | `/callback/node/reset` | 重置节点微信状态 |
|
|
| POST | `/callback/node/check` | 检测节点微信状态 |
|
|
| GET | `/callback/node/{node_id}/status` | 获取节点回调状态 |
|
|
|
|
### Webhook 管理 `/api/v1/webhook`
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| GET | `/webhook/` | 获取所有Webhook |
|
|
| GET | `/webhook/{webhook_id}` | 获取指定Webhook |
|
|
| POST | `/webhook/` | 添加Webhook |
|
|
| PUT | `/webhook/{webhook_id}` | 更新Webhook |
|
|
| DELETE | `/webhook/{webhook_id}` | 删除Webhook |
|
|
| POST | `/webhook/{webhook_id}/enable` | 启用Webhook |
|
|
| POST | `/webhook/{webhook_id}/disable` | 禁用Webhook |
|
|
|
|
### 外部接口 `/api/v1/external`
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|------|------|------|
|
|
| POST | `/external/send` | 外部接口-发送消息 |
|
|
| POST | `/external/trigger` | 外部接口-触发数据处理 |
|
|
| POST | `/external/plugin/execute` | 外部接口-执行插件 |
|
|
| GET | `/external/plugins` | 外部接口-获取可用插件列表 |
|
|
| GET | `/external/nodes` | 外部接口-获取可用节点 |
|
|
| POST | `/external/ai/process` | 外部接口-AI处理消息 |
|
|
| POST | `/external/webhook/{event}` | 外部接口-Webhook接收 |
|
|
|
|
---
|
|
|
|
## 节点管理 API 详解
|
|
|
|
### 获取所有节点
|
|
|
|
```
|
|
GET /api/v1/nodes/
|
|
```
|
|
|
|
**响应示例：**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"node_id": "wx1",
|
|
"name": "微信1",
|
|
"api_url": "http://192.168.20.84:5000",
|
|
"enabled": true,
|
|
"description": "",
|
|
"group": "wechat",
|
|
"status": "error",
|
|
"wechat_status": "online",
|
|
"is_healthy": false
|
|
}
|
|
],
|
|
"count": 1
|
|
}
|
|
```
|
|
|
|
### 添加节点
|
|
|
|
```
|
|
POST /api/v1/nodes/
|
|
```
|
|
|
|
**请求体：**
|
|
```json
|
|
{
|
|
"node_id": "wx1",
|
|
"name": "微信1",
|
|
"api_url": "http://192.168.20.84:5000",
|
|
"api_key": "your-node-api-key",
|
|
"description": "测试节点",
|
|
"group": "wechat"
|
|
}
|
|
```
|
|
|
|
### 更新节点
|
|
|
|
```
|
|
PUT /api/v1/nodes/{node_id}
|
|
```
|
|
|
|
**请求体：**
|
|
```json
|
|
{
|
|
"api_url": "http://192.168.20.84:5000",
|
|
"api_key": "updated-key"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 消息发送 API 详解
|
|
|
|
### 发送消息
|
|
|
|
```
|
|
POST /api/v1/messages/send
|
|
```
|
|
|
|
**请求体：**
|
|
```json
|
|
{
|
|
"node_id": "wx1",
|
|
"who": "文件传输助手",
|
|
"msg": "测试消息",
|
|
"msg_type": "text"
|
|
}
|
|
```
|
|
|
|
**响应示例：**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "消息发送成功"
|
|
}
|
|
```
|
|
|
|
### 发送群消息
|
|
|
|
```
|
|
POST /api/v1/messages/send_group
|
|
```
|
|
|
|
**请求体：**
|
|
```json
|
|
{
|
|
"node_id": "wx1",
|
|
"group_name": "测试群",
|
|
"msg": "群消息测试",
|
|
"msg_type": "text"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 插件管理 API 详解
|
|
|
|
### 获取所有插件
|
|
|
|
```
|
|
GET /api/v1/plugins/
|
|
```
|
|
|
|
**响应示例：**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"plugins": [
|
|
{
|
|
"name": "http_scheduled_sender",
|
|
"version": "1.0.0",
|
|
"type": "scheduled_task",
|
|
"description": "定时HTTP数据源推送",
|
|
"enabled": true,
|
|
"config": {
|
|
"node_id": "wx1",
|
|
"receiver": "asq",
|
|
"cron": "0 8 * * *"
|
|
}
|
|
}
|
|
],
|
|
"count": 1
|
|
}
|
|
```
|
|
|
|
### 配置插件
|
|
|
|
```
|
|
PUT /api/v1/plugins/{plugin_name}/config
|
|
```
|
|
|
|
**请求体：**
|
|
```json
|
|
{
|
|
"name": "http_scheduled_sender",
|
|
"config": {
|
|
"node_id": "wx1",
|
|
"receiver": "文件传输助手",
|
|
"cron": "0 8 * * *",
|
|
"http_url": "https://api.example.com/news",
|
|
"message_template": "📰 {title}\n{url}"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 执行插件
|
|
|
|
```
|
|
POST /api/v1/plugins/{plugin_name}/execute
|
|
```
|
|
|
|
**请求体：**
|
|
```json
|
|
{
|
|
"action": "preview"
|
|
}
|
|
```
|
|
|
|
**action 选项：**
|
|
- `send` - 执行完整流程
|
|
- `fetch` - 仅请求API
|
|
- `parse` - 请求并解析数据
|
|
- `preview` - 预览格式化后的消息
|
|
- `test` - 测试cron表达式
|
|
|
|
---
|
|
|
|
## 通用响应格式
|
|
|
|
**成功：**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {},
|
|
"message": "操作成功"
|
|
}
|
|
```
|
|
|
|
**失败：**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "错误描述"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 插件类型
|
|
|
|
| 类型 | 值 | 说明 |
|
|
|------|-----|------|
|
|
| `message_handler` | MESSAGE_HANDLER | 消息处理器 |
|
|
| `data_source` | DATA_SOURCE | 数据源 |
|
|
| `action_trigger` | ACTION_TRIGGER | 动作触发器 |
|
|
| `ai_agent` | AI_AGENT | AI智能体 |
|
|
| `scheduled_task` | SCHEDULED_TASK | 定时任务 |
|
|
| `http_scheduled_sender` | HTTP_SCHEDULED_SENDER | 定时HTTP推送 |
|
|
| `custom` | CUSTOM | 自定义 |
|
|
|
|
---
|
|
|
|
## 节点数据模型
|
|
|
|
```json
|
|
{
|
|
"node_id": "wx1",
|
|
"name": "微信1",
|
|
"api_url": "http://192.168.20.84:5000",
|
|
"api_key": "your-key",
|
|
"enabled": true,
|
|
"description": "",
|
|
"group": "wechat",
|
|
"status": "active",
|
|
"wechat_status": "online",
|
|
"is_healthy": true
|
|
}
|
|
```
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| node_id | string | 节点唯一标识 |
|
|
| name | string | 节点显示名称 |
|
|
| api_url | string | 节点API地址 |
|
|
| api_key | string | 节点API密钥 |
|
|
| enabled | bool | 是否启用 |
|
|
| description | string | 节点描述 |
|
|
| group | string | 节点分组 |
|
|
| status | string | API状态 (active/inactive/error) |
|
|
| wechat_status | string | 微信状态 (online/offline) |
|
|
| is_healthy | bool | 健康状态 |
|