zjpb.net/docs/API_DOC.md

# ZJPB API 文档

## 概述

ZJPB 网站管理 API，通过 API Key 进行认证，可用于外部工具（如 OpenClaw）调用。

## 基础信息

- **Base URL**: `http://175.178.72.171`
- **认证方式**: Header (`X-API-Key`)
- **数据格式**: JSON

## 认证

所有 API 请求需要在 Header 中携带 API Key：

```
X-API-Key: your-api-key-here
```

获取 API Key：进入后台管理 → API密钥 → 创建新密钥

---

## API 接口

### 1. 获取网站列表

```http
GET /api/key/sites
```

**权限**: `site:read`

**响应示例**:
```json
{
  "success": true,
  "sites": [
    {
      "id": 1,
      "code": "12345678",
      "name": "网站名称",
      "url": "https://example.com",
      "slug": "example",
      "logo": "/uploads/logo.png",
      "short_desc": "简短描述",
      "description": "详细介绍",
      "features": "主要功能",
      "news_keywords": "关键词",
      "is_active": true,
      "is_recommended": false,
      "view_count": 100,
      "tags": ["标签1", "标签2"],
      "created_at": "2026-03-23 10:00:00"
    }
  ]
}
```

---

### 2. 创建网站

```http
POST /api/key/sites
```

**权限**: `site:write`

**请求体**:
```json
{
  "name": "网站名称",
  "url": "https://example.com",
  "slug": "example",
  "logo": "/uploads/logo.png",
  "short_desc": "简短描述",
  "description": "详细介绍",
  "features": "主要功能",
  "news_keywords": "关键词",
  "tags": ["标签1", "标签2"],
  "is_active": true,
  "is_recommended": false,
  "sort_order": 0
}
```

**字段说明**:
| 字段 | 必填 | 说明 |
|------|------|------|
| name | 是 | 网站名称 |
| url | 是 | 网站 URL |
| slug | 否 | URL别名，用于 SEO |
| logo | 否 | Logo 图片路径 |
| short_desc | 否 | 简短描述 |
| description | 否 | 详细介绍 |
| features | 否 | 主要功能 |
| news_keywords | 否 | 新闻关键词 |
| tags | 否 | 标签数组 |
| is_active | 否 | 是否启用，默认 true |
| is_recommended | 否 | 是否推荐，默认 false |
| sort_order | 否 | 排序权重，默认 0 |

**响应示例**:
```json
{
  "success": true,
  "site": {
    "id": 2,
    "code": "87654321",
    "name": "网站名称",
    "url": "https://example.com",
    "slug": "example"
  }
}
```

---

### 3. 获取单个网站

```http
GET /api/key/sites/{code}
```

**权限**: `site:read`

**参数**:
- `code`: 网站编码（8位数字）

**响应示例**:
```json
{
  "success": true,
  "site": {
    "id": 1,
    "code": "12345678",
    "name": "网站名称",
    "url": "https://example.com",
    ...
  }
}
```

---

### 4. 更新网站

```http
PUT /api/key/sites/{code}
```

**权限**: `site:write`

**参数**:
- `code`: 网站编码（8位数字）

**请求体**: 同创建网站，可只传需要更新的字段

**响应示例**:
```json
{
  "success": true,
  "site": {
    "id": 1,
    "code": "12345678",
    "name": "新名称",
    ...
  }
}
```

---

### 5. 删除网站

```http
DELETE /api/key/sites/{code}
```

**权限**: `site:write`

**参数**:
- `code`: 网站编码（8位数字）

**响应示例**:
```json
{
  "success": true,
  "message": "网站已删除"
}
```

---

## 错误响应

```json
{
  "success": false,
  "message": "错误信息"
}
```

**状态码**:
- `200`: 成功
- `400`: 请求参数错误
- `401`: 认证失败（无效的 API Key）
- `403`: 权限不足
- `404`: 资源不存在
- `500`: 服务器错误

---

## 使用示例

### cURL

```bash
# 获取网站列表
curl -X GET http://175.178.72.171/api/key/sites \
  -H "X-API-Key: your-api-key"

# 创建网站
curl -X POST http://175.178.72.171/api/key/sites \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "示例网站",
    "url": "https://example.com",
    "short_desc": "这是一个示例网站",
    "tags": ["科技", "开源"]
  }'

# 更新网站
curl -X PUT http://175.178.72.171/api/key/sites/12345678 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"name": "新名称"}'

# 删除网站
curl -X DELETE http://175.178.72.171/api/key/sites/12345678 \
  -H "X-API-Key: your-api-key"
```

### Python

```python
import requests

API_KEY = "your-api-key"
BASE_URL = "http://175.178.72.171"
headers = {"X-API-Key": API_KEY}

# 获取网站列表
response = requests.get(f"{BASE_URL}/api/key/sites", headers=headers)
print(response.json())

# 创建网站
data = {
    "name": "示例网站",
    "url": "https://example.com",
    "short_desc": "这是一个示例网站",
    "tags": ["科技", "开源"]
}
response = requests.post(f"{BASE_URL}/api/key/sites", json=data, headers=headers)
print(response.json())
```

### JavaScript

```javascript
const API_KEY = "your-api-key";
const BASE_URL = "http://175.178.72.171";
const headers = { "X-API-Key": API_KEY };

// 获取网站列表
fetch(`${BASE_URL}/api/key/sites`, { headers })
  .then(res => res.json())
  .then(data => console.log(data));

// 创建网站
fetch(`${BASE_URL}/api/key/sites`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
  },
  body: JSON.stringify({
    name: "示例网站",
    url: "https://example.com",
    short_desc: "这是一个示例网站"
  })
})
  .then(res => res.json())
  .then(data => console.log(data));
```

---

## OpenClaw 集成

在 OpenClaw 中配置 API：

1. **Base URL**: `http://175.178.72.171`
2. **Auth Header**: `X-API-Key`
3. **Auth Value**: 你创建的 API Key

创建网站的 prompt 示例：

```
你是一个网站发布助手。请根据用户提供的网站信息，调用 ZJPB API 创建网站。

网站信息：
- 名称：{name}
- URL：{url}
- 描述：{description}

请调用 POST /api/key/sites 接口创建网站。
```

---

**最后更新**: 2026-03-23