476 lines
15 KiB
Markdown
476 lines
15 KiB
Markdown
# Template模块API文档
|
||
|
||
## 概述
|
||
|
||
Template (模板) 模块用于管理各种模板内容，支持按任务类型、平台、合作模式和服务类型等分类管理模板。主要包括模板分类和模板两大类接口。
|
||
|
||
## 通用响应格式
|
||
|
||
所有API响应都遵循以下统一的JSON格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200, // 状态码，200表示成功，其他值表示错误
|
||
"message": "成功", // 响应消息
|
||
"data": {} // 响应数据，可能是对象、数组或null
|
||
}
|
||
```
|
||
|
||
## 分页响应格式
|
||
|
||
使用分页的接口将返回以下格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"count": 100, // 总记录数
|
||
"next": "下一页URL或null", // 下一页链接
|
||
"previous": "上一页URL或null", // 上一页链接
|
||
"results": [], // 当前页的数据
|
||
"total_pages": 10, // 总页数
|
||
"current_page": 1 // 当前页码
|
||
}
|
||
}
|
||
```
|
||
|
||
## 认证方式
|
||
|
||
所有接口都需要使用自定义Token认证，请在HTTP请求头中添加以下字段：
|
||
|
||
```
|
||
Authorization: Token your_token_here
|
||
```
|
||
|
||
## 1. 模板分类管理 (Template Categories)
|
||
|
||
模板分类用于对模板进行分类和归类，便于管理和检索。
|
||
|
||
### 1.1 获取模板分类列表
|
||
|
||
- **URL**: `/categories/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取所有模板分类的列表
|
||
- **请求参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页记录数，默认为10，最大为100
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板分类列表成功",
|
||
"data": {
|
||
"count": 5,
|
||
"next": null,
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"name": "营销模板",
|
||
"description": "用于营销推广的模板集合",
|
||
"created_at": "2023-06-01T10:00:00Z",
|
||
"updated_at": "2023-06-01T10:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 1,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 创建模板分类
|
||
|
||
- **URL**: `/categories/`
|
||
- **方法**: `POST`
|
||
- **描述**: 创建一个新的模板分类
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"name": "营销模板", // 必填，分类名称
|
||
"description": "用于营销推广的模板集合" // 可选，分类描述
|
||
}
|
||
```
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 201,
|
||
"message": "模板分类创建成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "营销模板",
|
||
"description": "用于营销推广的模板集合",
|
||
"created_at": "2023-06-01T10:00:00Z",
|
||
"updated_at": "2023-06-01T10:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.3 获取模板分类详情
|
||
|
||
- **URL**: `/categories/{id}/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取指定ID的模板分类详情
|
||
- **请求参数**: 无
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板分类详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "营销模板",
|
||
"description": "用于营销推广的模板集合",
|
||
"created_at": "2023-06-01T10:00:00Z",
|
||
"updated_at": "2023-06-01T10:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.4 更新模板分类
|
||
|
||
- **URL**: `/categories/{id}/`
|
||
- **方法**: `PUT`/`PATCH`
|
||
- **描述**: 更新指定ID的模板分类信息
|
||
- **请求参数**: 同创建模板分类
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "模板分类更新成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "更新后的营销模板",
|
||
"description": "这是更新后的描述",
|
||
"created_at": "2023-06-01T10:00:00Z",
|
||
"updated_at": "2023-06-02T10:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.5 删除模板分类
|
||
|
||
- **URL**: `/categories/{id}/`
|
||
- **方法**: `DELETE`
|
||
- **描述**: 删除指定ID的模板分类
|
||
- **请求参数**: 无
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "模板分类删除成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 2. 模板管理 (Templates)
|
||
|
||
模板是系统中的核心内容，可以按各种条件进行分类和检索。
|
||
|
||
### 2.1 获取模板列表
|
||
|
||
- **URL**: `/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取所有模板的列表，支持多种过滤和排序
|
||
- **请求参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页记录数，默认为10，最大为100
|
||
- `title`: 按标题模糊搜索
|
||
- `content`: 按内容模糊搜索
|
||
- `mission`: 按任务类型筛选，可选值：initial_contact, follow_up, negotiation, closing, other
|
||
- `platform`: 按平台筛选，可选值：tiktok, instagram, youtube, facebook, twitter, other
|
||
- `collaboration_type`: 按合作模式筛选，可选值：paid_promotion, affiliate, sponsored_content, brand_ambassador, other
|
||
- `service`: 按服务类型筛选，可选值：voice, text, video, image, other
|
||
- `category`: 按分类ID筛选
|
||
- `category_name`: 按分类名称模糊搜索
|
||
- `is_public`: 按是否公开筛选，true或false
|
||
- `created_after`: 按创建时间筛选，格式：YYYY-MM-DDThh:mm:ssZ
|
||
- `created_before`: 按创建时间筛选，格式：YYYY-MM-DDThh:mm:ssZ
|
||
- `ordering`: 排序字段，可选值：created_at, -created_at, updated_at, -updated_at, title, -title
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板列表成功",
|
||
"data": {
|
||
"count": 20,
|
||
"next": null,
|
||
"previous": null,
|
||
"results": [
|
||
{
|
||
"id": 1,
|
||
"title": "TikTok初次合作邀请",
|
||
"preview": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...",
|
||
"category_name": "营销模板",
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-06-01T10:00:00Z",
|
||
"updated_at": "2023-06-01T10:00:00Z"
|
||
}
|
||
],
|
||
"total_pages": 2,
|
||
"current_page": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 创建模板
|
||
|
||
- **URL**: `/`
|
||
- **方法**: `POST`
|
||
- **描述**: 创建一个新的模板
|
||
- **请求参数**:
|
||
```json
|
||
{
|
||
"title": "TikTok初次合作邀请", // 必填，模板标题
|
||
"content": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...", // 必填，模板内容
|
||
"category": 1, // 必填，模板分类ID
|
||
"mission": "initial_contact", // 可选，任务类型，默认为initial_contact
|
||
"platform": "tiktok", // 可选，平台，默认为tiktok
|
||
"collaboration_type": "paid_promotion", // 可选，合作模式，默认为paid_promotion
|
||
"service": "text", // 可选，服务类型，默认为text
|
||
"is_public": true // 可选，是否公开，默认为true
|
||
}
|
||
```
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 201,
|
||
"message": "模板创建成功",
|
||
"data": {
|
||
"id": 1,
|
||
"title": "TikTok初次合作邀请",
|
||
"content": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...",
|
||
"category": 1,
|
||
"mission": "initial_contact",
|
||
"platform": "tiktok",
|
||
"service": "text",
|
||
"collaboration_type": "paid_promotion",
|
||
"is_public": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 获取模板详情
|
||
|
||
- **URL**: `/{id}/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取指定ID的模板详情
|
||
- **请求参数**: 无
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取模板详情成功",
|
||
"data": {
|
||
"id": 1,
|
||
"title": "TikTok初次合作邀请",
|
||
"content": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...",
|
||
"preview": "亲爱的[创作者名称]，我们是[品牌名称]，我们注意到您的内容非常精彩，希望能与您合作...",
|
||
"category": {
|
||
"id": 1,
|
||
"name": "营销模板",
|
||
"description": "用于营销推广的模板集合",
|
||
"created_at": "2023-06-01T10:00:00Z",
|
||
"updated_at": "2023-06-01T10:00:00Z"
|
||
},
|
||
"mission": "initial_contact",
|
||
"mission_display": "初步联系",
|
||
"platform": "tiktok",
|
||
"platform_display": "TikTok",
|
||
"service": "text",
|
||
"service_display": "文本",
|
||
"collaboration_type": "paid_promotion",
|
||
"collaboration_type_display": "付费推广",
|
||
"is_public": true,
|
||
"created_at": "2023-06-01T10:00:00Z",
|
||
"updated_at": "2023-06-01T10:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 更新模板
|
||
|
||
- **URL**: `/{id}/`
|
||
- **方法**: `PUT`/`PATCH`
|
||
- **描述**: 更新指定ID的模板信息
|
||
- **请求参数**: 同创建模板
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "模板更新成功",
|
||
"data": {
|
||
"id": 1,
|
||
"title": "更新后的TikTok合作邀请",
|
||
"content": "更新后的内容...",
|
||
"category": 1,
|
||
"mission": "follow_up",
|
||
"platform": "tiktok",
|
||
"service": "text",
|
||
"collaboration_type": "paid_promotion",
|
||
"is_public": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.5 删除模板
|
||
|
||
- **URL**: `/{id}/`
|
||
- **方法**: `DELETE`
|
||
- **描述**: 删除指定ID的模板
|
||
- **请求参数**: 无
|
||
- **响应数据**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "模板删除成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 2.6 获取我的模板
|
||
|
||
- **URL**: `/mine/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取所有模板，实际上与获取模板列表功能相同
|
||
- **请求参数**: 同获取模板列表
|
||
- **响应数据**: 同获取模板列表
|
||
|
||
### 2.7 获取公开模板
|
||
|
||
- **URL**: `/public/`
|
||
- **方法**: `GET`
|
||
- **描述**: 获取所有公开的模板
|
||
- **请求参数**: 同获取模板列表
|
||
- **响应数据**: 同获取模板列表，但只返回is_public=true的模板
|
||
|
||
### 2.8 按任务类型获取模板
|
||
|
||
- **URL**: `/by_mission/`
|
||
- **方法**: `GET`
|
||
- **描述**: 按任务类型获取模板
|
||
- **请求参数**:
|
||
- `mission`: 必填，任务类型，可选值：initial_contact, follow_up, negotiation, closing, other
|
||
- 其他参数同获取模板列表
|
||
- **响应数据**: 同获取模板列表，但只返回指定任务类型的模板
|
||
|
||
### 2.9 按平台获取模板
|
||
|
||
- **URL**: `/by_platform/`
|
||
- **方法**: `GET`
|
||
- **描述**: 按平台获取模板
|
||
- **请求参数**:
|
||
- `platform`: 必填，平台，可选值：tiktok, instagram, youtube, facebook, twitter, other
|
||
- 其他参数同获取模板列表
|
||
- **响应数据**: 同获取模板列表，但只返回指定平台的模板
|
||
|
||
### 2.10 按合作模式获取模板
|
||
|
||
- **URL**: `/by_collaboration/`
|
||
- **方法**: `GET`
|
||
- **描述**: 按合作模式获取模板
|
||
- **请求参数**:
|
||
- `collaboration_type`: 必填，合作模式，可选值：paid_promotion, affiliate, sponsored_content, brand_ambassador, other
|
||
- 其他参数同获取模板列表
|
||
- **响应数据**: 同获取模板列表，但只返回指定合作模式的模板
|
||
|
||
### 2.11 按服务类型获取模板
|
||
|
||
- **URL**: `/by_service/`
|
||
- **方法**: `GET`
|
||
- **描述**: 按服务类型获取模板
|
||
- **请求参数**:
|
||
- `service`: 必填，服务类型，可选值：voice, text, video, image, other
|
||
- 其他参数同获取模板列表
|
||
- **响应数据**: 同获取模板列表，但只返回指定服务类型的模板
|
||
|
||
## 3. 模板字段说明
|
||
|
||
### 3.1 模板分类字段
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|-------------|-----------|-------------|
|
||
| id | 整数 | 分类ID |
|
||
| name | 字符串 | 分类名称 |
|
||
| description | 字符串 | 分类描述 |
|
||
| created_at | 日期时间 | 创建时间 |
|
||
| updated_at | 日期时间 | 更新时间 |
|
||
|
||
### 3.2 模板字段
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------------------------|-----------|------------------------------|
|
||
| id | 整数 | 模板ID |
|
||
| title | 字符串 | 模板标题 |
|
||
| content | 字符串 | 模板内容 |
|
||
| preview | 字符串 | 内容预览，自动生成 |
|
||
| category | 对象/整数 | 模板分类对象或ID |
|
||
| category_name | 字符串 | 分类名称 |
|
||
| mission | 字符串 | 任务类型代码 |
|
||
| mission_display | 字符串 | 任务类型显示名称 |
|
||
| platform | 字符串 | 平台代码 |
|
||
| platform_display | 字符串 | 平台显示名称 |
|
||
| service | 字符串 | 服务类型代码 |
|
||
| service_display | 字符串 | 服务类型显示名称 |
|
||
| collaboration_type | 字符串 | 合作模式代码 |
|
||
| collaboration_type_display | 字符串 | 合作模式显示名称 |
|
||
| is_public | 布尔值 | 是否公开 |
|
||
| created_at | 日期时间 | 创建时间 |
|
||
| updated_at | 日期时间 | 更新时间 |
|
||
|
||
## 4. 使用示例
|
||
|
||
### 4.1 创建一个新的模板分类
|
||
|
||
```http
|
||
POST /api/categories/
|
||
Content-Type: application/json
|
||
Authorization: Token your_token_here
|
||
|
||
{
|
||
"name": "电商推广模板",
|
||
"description": "专门用于电商产品推广的各类模板"
|
||
}
|
||
```
|
||
|
||
### 4.2 创建一个新的TikTok初次联系模板
|
||
|
||
```http
|
||
POST /api/
|
||
Content-Type: application/json
|
||
Authorization: Token your_token_here
|
||
|
||
{
|
||
"title": "TikTok品牌合作初次邀请",
|
||
"content": "亲爱的[创作者名称]，\n\n我是[品牌名称]的[您的姓名]。我们非常欣赏您在TikTok上分享的[内容类型]内容，特别是您关于[具体内容]的视频，展现了很高的创意和专业性。\n\n我们希望能与您合作，进行一次付费推广活动。我们的产品是[产品描述]，我们认为这与您的内容风格和受众非常匹配。\n\n如果您有兴趣，我们可以提供[报酬说明]的报酬，以及[其他福利]。希望能得到您的回复，进一步讨论合作细节。\n\n期待您的回复！\n\n谢谢，\n[您的姓名]\n[品牌名称]",
|
||
"category": 1,
|
||
"mission": "initial_contact",
|
||
"platform": "tiktok",
|
||
"collaboration_type": "paid_promotion",
|
||
"service": "text",
|
||
"is_public": true
|
||
}
|
||
```
|
||
|
||
### 4.3 查找所有TikTok平台的文本类模板
|
||
|
||
```http
|
||
GET /api/?platform=tiktok&service=text
|
||
Authorization: Token your_token_here
|
||
```
|
||
|
||
### 4.4 按任务类型查询模板
|
||
|
||
```http
|
||
GET /api/by_mission/?mission=follow_up
|
||
Authorization: Token your_token_here
|
||
```
|