1057 lines
25 KiB
Markdown
1057 lines
25 KiB
Markdown
# 达人详情模块 (daren_detail) API 接口文档
|
||
|
||
## 模块简介
|
||
|
||
`daren_detail` 模块是达人管理系统的核心模块，提供了完整的达人信息管理功能，包括：
|
||
- 达人筛选、详情查看、信息更新
|
||
- 营销活动管理和达人合作详情
|
||
- 多维度指标数据管理（协作指标、视频指标、直播指标、粉丝统计、趋势分析）
|
||
- 视频内容管理
|
||
- 公有达人库和私有达人库管理
|
||
|
||
## 认证方式
|
||
|
||
所有接口都需要使用 `CustomTokenAuthentication` 进行身份验证，请在请求头中包含：
|
||
```http
|
||
Authorization: Token <your_token>
|
||
```
|
||
|
||
## 1. 达人管理相关接口
|
||
|
||
### 1.1 添加/更新达人
|
||
- **接口路径**: `POST /creators/add/`
|
||
- **功能**: 添加新达人或更新现有达人信息
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"name": "达人姓名", // 必填
|
||
"avatar_url": "头像URL",
|
||
"category": "Beauty & Personal Care",
|
||
"e_commerce_level": "L3", // 或数字3
|
||
"exposure_level": "KOL-1",
|
||
"followers": 125000,
|
||
"gmv": "$534.1k", // 或数字534.1
|
||
"items_sold": "2.5k", // 或数字2.5
|
||
"avg_video_views": "85k", // 或数字85000
|
||
"pricing": {
|
||
"individual": 200, // 或直接传数字
|
||
"package": "套餐描述"
|
||
},
|
||
"collab_count": 15,
|
||
"latest_collab": "2024-03-15",
|
||
"e_commerce_platforms": ["TikTok Shop", "Instagram Shop"],
|
||
"mcn": "MCN机构名称"
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "达人信息已添加/更新",
|
||
"data": {
|
||
"created": true, // true为新建，false为更新
|
||
"creator_id": 123
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 获取达人详情
|
||
- **接口路径**: `GET /creators/{creator_id}/`
|
||
- **功能**: 获取指定达人的详细信息
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `creator_id`: 达人ID（必填）
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"creator": {
|
||
"id": 123,
|
||
"name": "达人姓名",
|
||
"avatar": "头像URL",
|
||
"email": "邮箱",
|
||
"social_accounts": {
|
||
"instagram": "@username",
|
||
"tiktok": "tiktok链接"
|
||
},
|
||
"location": "地理位置",
|
||
"live_schedule": "直播时间安排"
|
||
},
|
||
"metrics": {
|
||
"e_commerce_level": "L3",
|
||
"exposure_level": "KOL-1",
|
||
"followers": "125k",
|
||
"actual_followers": 125000,
|
||
"gmv": "$534k",
|
||
"actual_gmv": 534.1,
|
||
"items_sold": "2500",
|
||
"avg_video_views": "85k",
|
||
"actual_views": 85000,
|
||
"gpm": "$2.35", // 每千次观看收入
|
||
"gmv_per_customer": "$213.64" // 每位客户GMV
|
||
},
|
||
"business": {
|
||
"category": "Beauty & Personal Care",
|
||
"categories": ["Beauty & Personal Care"],
|
||
"mcn": "MCN机构",
|
||
"pricing": {
|
||
"price": "$200",
|
||
"package": "套餐描述"
|
||
},
|
||
"collab_count": 15,
|
||
"latest_collab": "2024-03-15",
|
||
"e_commerce_platforms": ["TikTok Shop"]
|
||
},
|
||
"analytics": {
|
||
"gmv_by_channel": {...}, // 按渠道分析
|
||
"gmv_by_category": {...} // 按类别分析
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.3 更新达人详细信息
|
||
- **接口路径**: `POST /creators/update_detail/`
|
||
- **功能**: 更新达人的详细信息（联系方式、社交账号等）
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"creator_id": 123, // 必填
|
||
"email": "新邮箱",
|
||
"instagram": "@new_username",
|
||
"tiktok_link": "新TikTok链接",
|
||
"location": "新地理位置",
|
||
"live_schedule": "新直播时间安排",
|
||
"mcn": "新MCN机构",
|
||
"gmv_by_channel": {...}, // 按渠道GMV分析数据
|
||
"gmv_by_category": {...} // 按类别GMV分析数据
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "达人详细信息已更新",
|
||
"data": {
|
||
"creator_id": 123,
|
||
"name": "达人姓名"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.4 获取达人品牌合作详情
|
||
- **接口路径**: `GET /creators/{creator_id}/campaigns/`
|
||
- **功能**: 获取指定达人与各品牌的合作活动详情，支持分页
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `creator_id`: 达人ID（必填）
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页数量，默认为10
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": [
|
||
{
|
||
"brand": {
|
||
"id": "U",
|
||
"name": "品牌名称",
|
||
"color": "#E74694"
|
||
},
|
||
"pricing_detail": "$80",
|
||
"start_date": "05/31/2024",
|
||
"end_date": "05/29/2024",
|
||
"status": "completed", // pending, in_progress, completed, cancelled
|
||
"gmv_achieved": "$120",
|
||
"views_achieved": "650",
|
||
"video_link": "视频链接",
|
||
"campaign_id": 456,
|
||
"campaign_name": "活动名称"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"current_page": 1,
|
||
"total_pages": 5,
|
||
"total_count": 45,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
},
|
||
"creator": {
|
||
"id": 123,
|
||
"name": "达人姓名",
|
||
"avatar": "头像URL",
|
||
"category": "Beauty & Personal Care",
|
||
"exposure_level": "KOL-1"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 2. 营销活动相关接口
|
||
|
||
### 2.1 获取营销活动列表
|
||
- **接口路径**: `GET /campaigns/`
|
||
- **功能**: 获取所有活跃的营销活动列表
|
||
- **请求方法**: GET
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": [
|
||
{
|
||
"id": 456,
|
||
"name": "品牌名 产品名",
|
||
"brand": "品牌名",
|
||
"product": "产品名"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2.2 添加达人到营销活动
|
||
- **接口路径**: `POST /campaigns/add/`
|
||
- **功能**: 将达人添加到指定营销活动中
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"campaign_id": 456, // 必填
|
||
"creator_ids": [123, 124, 125] // 达人ID列表，必填
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功添加达人到活动",
|
||
"data": {
|
||
"campaign": {
|
||
"id": "456",
|
||
"name": "活动名称"
|
||
},
|
||
"added_creators": [
|
||
{
|
||
"id": 123,
|
||
"name": "达人姓名"
|
||
}
|
||
],
|
||
"stats": {
|
||
"added": 1, // 成功添加数量
|
||
"skipped": 0, // 跳过数量（达人不存在）
|
||
"already_exists": 2 // 已存在数量
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 指标数据相关接口
|
||
|
||
### 3.1 获取创作者指标数据
|
||
- **接口路径**: `GET /creators/{creator_id}/metrics/`
|
||
- **功能**: 获取创作者的协作指标、视频和直播指标数据
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `creator_id`: 创作者ID（必填）
|
||
- `start_date`: 开始日期，格式：YYYY-MM-DD（可选）
|
||
- `end_date`: 结束日期，格式：YYYY-MM-DD（可选）
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"collaboration_metrics": {
|
||
"avg_commission_rate": "15.5%",
|
||
"products_count": 25,
|
||
"brand_collaborations": 8,
|
||
"product_price": "$50 - $200",
|
||
"date_range": "Mar 01, 2024 - Mar 31, 2024"
|
||
},
|
||
"video": {
|
||
"gpm": "$2.35",
|
||
"videos_count": 12,
|
||
"avg_views": "85k",
|
||
"avg_engagement": "3.2%",
|
||
"avg_likes": 2500,
|
||
"date_range": "Mar 01, 2024 - Mar 31, 2024"
|
||
},
|
||
"shoppable_video": {
|
||
"gpm": "$3.15",
|
||
"videos_count": 8,
|
||
"avg_views": "92k",
|
||
"avg_engagement": "4.1%",
|
||
"avg_likes": 3200,
|
||
"date_range": "Mar 01, 2024 - Mar 31, 2024"
|
||
},
|
||
"live": {
|
||
"gpm": "$4.50",
|
||
"lives_count": 5,
|
||
"avg_views": "150k",
|
||
"avg_engagement": "5.8%",
|
||
"avg_likes": 8500,
|
||
"date_range": "Mar 01, 2024 - Mar 31, 2024"
|
||
},
|
||
"shoppable_live": {
|
||
"gpm": "$6.20",
|
||
"lives_count": 3,
|
||
"avg_views": "180k",
|
||
"avg_engagement": "7.2%",
|
||
"avg_likes": 12000,
|
||
"date_range": "Mar 01, 2024 - Mar 31, 2024"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 更新创作者指标数据
|
||
- **接口路径**: `POST /creators/metrics/update/`
|
||
- **功能**: 更新创作者的指标数据
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"creator_id": 123, // 必填
|
||
"metrics_type": "collaboration", // 必填：collaboration, video, shoppable_video, live, shoppable_live
|
||
"metrics_data": {
|
||
"start_date": "2024-03-01", // 必填，格式：YYYY-MM-DD
|
||
"end_date": "2024-03-31", // 必填，格式：YYYY-MM-DD
|
||
// 根据metrics_type不同，以下参数有所不同：
|
||
|
||
// 当metrics_type为"collaboration"时：
|
||
"avg_commission_rate": "15.5%", // 或数字15.5
|
||
"products_count": 25,
|
||
"brand_collaborations": 8,
|
||
"product_price": "$50 - $200", // 格式：$最小值 - $最大值
|
||
|
||
// 当metrics_type为"video"或"shoppable_video"时：
|
||
"gpm": "$2.35", // 或数字2.35
|
||
"videos_count": 12,
|
||
"avg_views": "85k", // 或数字85000
|
||
"avg_engagement": "3.2%", // 或数字3.2
|
||
"avg_likes": 2500,
|
||
|
||
// 当metrics_type为"live"或"shoppable_live"时：
|
||
"gpm": "$4.50",
|
||
"lives_count": 5,
|
||
"avg_views": "150k",
|
||
"avg_engagement": "5.8%",
|
||
"avg_likes": 8500
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "协作指标数据已更新", // 根据metrics_type变化
|
||
"data": {
|
||
"created": true, // true为新建，false为更新
|
||
"metrics_id": 789
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 获取创作者粉丝统计数据
|
||
- **接口路径**: `GET /creator/{creator_id}/followers/` 或 `GET /creator/followers/?creator_id={creator_id}`
|
||
- **功能**: 获取创作者的粉丝性别、年龄、地域分布统计
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `creator_id`: 创作者ID（必填）
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"gender": {
|
||
"female": 65.5,
|
||
"male": 34.5
|
||
},
|
||
"age": {
|
||
"18-24": 25.2,
|
||
"25-34": 35.8,
|
||
"35-44": 22.1,
|
||
"45-54": 12.3,
|
||
"55+": 4.6
|
||
},
|
||
"locations": {
|
||
"TX": 18.5,
|
||
"FL": 15.2,
|
||
"NY": 12.8,
|
||
"CA": 11.3,
|
||
"GE": 8.9
|
||
},
|
||
"date_range": {
|
||
"start_date": "2024-03-29",
|
||
"end_date": "2024-04-28"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.4 更新创作者粉丝统计数据
|
||
- **接口路径**: `POST /creator/followers/update/`
|
||
- **功能**: 更新创作者的粉丝统计数据
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"creator_id": 123, // 必填
|
||
"follower_data": {
|
||
"date_range": {
|
||
"start_date": "2024-03-29", // 必填
|
||
"end_date": "2024-04-28" // 必填
|
||
},
|
||
"gender": {
|
||
"female": 65.5,
|
||
"male": 34.5
|
||
},
|
||
"age": {
|
||
"18-24": 25.2,
|
||
"25-34": 35.8,
|
||
"35-44": 22.1,
|
||
"45-54": 12.3,
|
||
"55+": 4.6
|
||
},
|
||
"locations": {
|
||
"TX": 18.5,
|
||
"FL": 15.2,
|
||
"NY": 12.8,
|
||
"CA": 11.3,
|
||
"GE": 8.9
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "粉丝统计数据已更新",
|
||
"data": {
|
||
"created": true,
|
||
"metrics_id": 890
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.5 获取创作者趋势数据
|
||
- **接口路径**: `GET /creator/{creator_id}/trends/` 或 `GET /creator/trends/?creator_id={creator_id}`
|
||
- **功能**: 获取创作者的GMV、销量、粉丝、观看量等趋势数据
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `creator_id`: 创作者ID（必填）
|
||
- `start_date`: 开始日期，格式：YYYY-MM-DD（可选，默认最近30天）
|
||
- `end_date`: 结束日期，格式：YYYY-MM-DD（可选，默认今天）
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"gmv": [1250.5, 1380.2, 1156.8, ...], // 30天的GMV数据
|
||
"items_sold": [850, 920, 780, ...], // 30天的销量数据
|
||
"followers": [125000, 125150, 125300, ...], // 30天的粉丝数据
|
||
"video_views": [85000, 92000, 78000, ...], // 30天的观看量数据
|
||
"engagement_rate": [3.2, 3.5, 2.8, ...], // 30天的互动率数据
|
||
"dates": ["2024-03-01", "2024-03-02", ...], // 对应的日期
|
||
"date_range": {
|
||
"start_date": "2024-03-01",
|
||
"end_date": "2024-03-31"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.6 更新创作者趋势数据
|
||
- **接口路径**: `POST /creator/trend/update/`
|
||
- **功能**: 更新单日的创作者趋势数据
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"creator_id": 123, // 必填
|
||
"date": "2024-03-15", // 必填，格式：YYYY-MM-DD
|
||
"metrics": {
|
||
"gmv": 1250.5,
|
||
"items_sold": 850,
|
||
"followers": 125000,
|
||
"video_views": 85000,
|
||
"engagement_rate": 3.2
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "趋势数据已更新",
|
||
"data": {
|
||
"created": true,
|
||
"metrics_id": 901,
|
||
"date": "2024-03-15"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. 视频管理相关接口
|
||
|
||
### 4.1 获取创作者视频列表
|
||
- **接口路径**: `GET /creator/{creator_id}/videos/` 或 `GET /creator/videos/?creator_id={creator_id}`
|
||
- **功能**: 获取创作者的视频列表，分为普通视频和带产品视频
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `creator_id`: 创作者ID（必填）
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页数量，默认为6
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": {
|
||
"regular_videos": {
|
||
"videos": [
|
||
{
|
||
"id": 1,
|
||
"title": "视频标题",
|
||
"thumbnail_url": "缩略图URL",
|
||
"badge": "red", // red, gold等
|
||
"view_count": 2130,
|
||
"like_count": 20,
|
||
"release_date": "2025-03-31"
|
||
}
|
||
],
|
||
"total": 15,
|
||
"page": 1,
|
||
"page_size": 6,
|
||
"total_pages": 3
|
||
},
|
||
"product_videos": {
|
||
"videos": [
|
||
{
|
||
"id": 4,
|
||
"title": "带产品的视频标题",
|
||
"thumbnail_url": "缩略图URL",
|
||
"badge": "red",
|
||
"view_count": 2130,
|
||
"like_count": 20,
|
||
"release_date": "2025-03-31",
|
||
"has_product": true,
|
||
"product_name": "产品名称",
|
||
"product_url": "产品链接"
|
||
}
|
||
],
|
||
"total": 8,
|
||
"page": 1,
|
||
"page_size": 6,
|
||
"total_pages": 2
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 添加创作者视频
|
||
- **接口路径**: `POST /creator/video/add/`
|
||
- **功能**: 为创作者添加新视频
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"creator_id": 123, // 必填
|
||
"title": "视频标题", // 必填
|
||
"release_date": "2024-03-15", // 必填，格式：YYYY-MM-DD
|
||
"video_type": "regular", // 可选：regular, product，默认regular
|
||
"description": "视频描述",
|
||
"thumbnail_url": "缩略图URL",
|
||
"video_url": "视频URL",
|
||
"video_id": "vid_123456", // 可选，不提供会自动生成
|
||
"badge": "red", // 可选：red, gold等，默认red
|
||
"view_count": 2130,
|
||
"like_count": 20,
|
||
"comment_count": 5,
|
||
"has_product": false, // 如果video_type为product，会自动设为true
|
||
"product_name": "产品名称", // 有产品时填写
|
||
"product_url": "产品链接" // 有产品时填写
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "视频添加成功",
|
||
"data": {
|
||
"video_id": 456,
|
||
"created": true // true为新建，false为更新
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. 公有达人库相关接口
|
||
|
||
### 5.1 获取公有达人库列表
|
||
- **接口路径**: `GET /public/creators/`
|
||
- **功能**: 获取公有达人库中的达人列表
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页数量，默认为10
|
||
- `category`: 分类过滤（可选）
|
||
- `keyword`: 关键词搜索（可选）
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": [
|
||
{
|
||
"public_id": 123,
|
||
"creator_id": 456,
|
||
"name": "达人姓名",
|
||
"avatar": "头像URL",
|
||
"category": "Beauty & Personal Care",
|
||
"e_commerce_level": "L3",
|
||
"exposure_level": "KOL-1",
|
||
"followers": "125k",
|
||
"gmv": "$534k",
|
||
"avg_video_views": "85k",
|
||
"pricing": "$200",
|
||
"pricing_package": "套餐描述",
|
||
"collab_count": 15,
|
||
"remark": "公有库备注",
|
||
"category_public": "公有库分类"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"current_page": 1,
|
||
"total_pages": 15,
|
||
"total_count": 150,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 筛选公有达人库
|
||
- **接口路径**: `POST /public/creators/filter/`
|
||
- **功能**: 根据过滤条件筛选公有达人库中的达人
|
||
- **请求方法**: POST
|
||
|
||
**URL参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页数量，默认为10
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"filter": {
|
||
"category": ["Beauty & Personal Care"], // 多选
|
||
"e_commerce_level": ["L1", "L2", "L3"], // 多选
|
||
"exposure_level": ["KOL-1", "KOC-1"], // 多选
|
||
"gmv_range": ["$0-$5k", "$5k-$25k"], // 多选
|
||
"views_range": ["10k-100k"], // 单选
|
||
"pricing": ["100-500"] // 单选
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应格式**: 同5.1
|
||
|
||
### 5.3 添加达人到公有库
|
||
- **接口路径**: `POST /public/creators/add/`
|
||
- **功能**: 将达人添加到公有达人库
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"creator_id": 456, // 必填
|
||
"category": "分类", // 可选
|
||
"remark": "备注信息" // 可选
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功添加达人到公有库", // 或"成功更新达人到公有库"
|
||
"data": {
|
||
"creator": {
|
||
"id": 456,
|
||
"name": "达人姓名"
|
||
},
|
||
"public_pool": {
|
||
"id": 123,
|
||
"category": "分类",
|
||
"remark": "备注信息"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.4 从公有库移除达人
|
||
- **接口路径**: `POST /public/creators/remove/`
|
||
- **功能**: 从公有达人库中移除达人，同时更新私有库中相关记录的状态
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"creator_id": 456, // 二选一
|
||
"public_id": 123 // 二选一
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功从公有库移除达人",
|
||
"data": {
|
||
"creator": {
|
||
"id": 456,
|
||
"name": "达人姓名"
|
||
},
|
||
"removed_from_public": true,
|
||
"updated_private_relations": 3,
|
||
"note": "已更新 3 个私有库中的相关记录状态"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 私有达人库相关接口
|
||
|
||
### 6.1 获取私有达人库列表
|
||
- **接口路径**: `GET /private/pools/`
|
||
- **功能**: 获取当前用户的私有达人库列表
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `user_id`: 用户ID（可选，只能查看自己的）
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": [
|
||
{
|
||
"id": 123,
|
||
"name": "我的收藏",
|
||
"description": "私有库描述",
|
||
"is_default": true,
|
||
"creator_count": 25,
|
||
"created_at": "2024-03-15"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 6.2 创建私有达人库
|
||
- **接口路径**: `POST /private/pools/create/`
|
||
- **功能**: 创建新的私有达人库
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"name": "私有库名称", // 必填
|
||
"description": "私有库描述", // 可选
|
||
"is_default": false // 可选，是否设为默认库
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "私有库创建成功",
|
||
"data": {
|
||
"id": 123,
|
||
"name": "私有库名称",
|
||
"is_default": false,
|
||
"creator_count": 0,
|
||
"created_at": "2024-03-15"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.3 获取私有库中的达人
|
||
- **接口路径**: `GET /private/pools/creators/{pool_id}/` 或 `GET /private/pools/creators/?pool_id={pool_id}`
|
||
- **功能**: 获取指定私有库中的达人列表
|
||
- **请求方法**: GET
|
||
|
||
**URL参数**:
|
||
- `pool_id`: 私有库ID（必填）
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页数量，默认为10
|
||
- `status`: 状态过滤，默认为active（可选：active, archived, public_removed）
|
||
- `keyword`: 关键词搜索（可选）
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取成功",
|
||
"data": [
|
||
{
|
||
"relation_id": 789,
|
||
"creator_id": 456,
|
||
"name": "达人姓名",
|
||
"avatar": "头像URL",
|
||
"category": "Beauty & Personal Care",
|
||
"e_commerce_level": "L3",
|
||
"exposure_level": "KOL-1",
|
||
"followers": "125k",
|
||
"gmv": "$534k",
|
||
"avg_video_views": "85k",
|
||
"pricing": "$200",
|
||
"collab_count": 15,
|
||
"notes": "私有库备注",
|
||
"status": "active", // active, archived, public_removed
|
||
"added_from_public": true,
|
||
"added_at": "2024-03-15",
|
||
"is_public_removed": false,
|
||
"status_note": null
|
||
}
|
||
],
|
||
"pagination": {
|
||
"current_page": 1,
|
||
"total_pages": 3,
|
||
"total_count": 25,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
},
|
||
"pool_info": {
|
||
"id": 123,
|
||
"name": "我的收藏",
|
||
"description": "私有库描述",
|
||
"is_default": true,
|
||
"user_id": 1,
|
||
"created_at": "2024-03-15"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.4 添加达人到私有库
|
||
- **接口路径**: `POST /private/pools/creators/add/`
|
||
- **功能**: 将达人添加到指定私有库
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"pool_id": 123, // 必填
|
||
"creator_id": 456, // 单个添加时使用
|
||
"creator_ids": [456, 457, 458], // 批量添加时使用
|
||
"notes": "备注信息" // 可选
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"added": [
|
||
{
|
||
"id": 456,
|
||
"name": "达人姓名",
|
||
"action": "添加"
|
||
}
|
||
],
|
||
"already_exists_count": 2,
|
||
"pool": {
|
||
"id": 123,
|
||
"name": "我的收藏"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.5 更新私有库中的达人
|
||
- **接口路径**: `POST /private/pools/creators/update/`
|
||
- **功能**: 更新私有库中达人的状态或备注
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"relation_id": 789, // 必填
|
||
"status": "archived", // 可选：active, archived
|
||
"notes": "新的备注信息" // 可选，传null可清空
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新成功",
|
||
"data": {
|
||
"relation_id": 789,
|
||
"creator_id": 456,
|
||
"pool_id": 123,
|
||
"status": "archived",
|
||
"notes": "新的备注信息"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.6 从私有库移除达人
|
||
- **接口路径**: `POST /private/pools/creators/remove/`
|
||
- **功能**: 从私有库中移除达人
|
||
- **请求方法**: POST
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
// 方式1：通过关联ID删除
|
||
"relation_id": 789, // 单个删除
|
||
"relation_ids": [789, 790], // 批量删除
|
||
|
||
// 方式2：通过私有库ID和达人ID删除
|
||
"pool_id": 123,
|
||
"creator_id": 456, // 单个删除
|
||
"creator_ids": [456, 457] // 批量删除
|
||
}
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "移除成功",
|
||
"data": {
|
||
"deleted_count": 2,
|
||
"relation_ids": [789, 790], // 或creator_ids
|
||
"pool_id": 123
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.7 筛选私有库中的达人
|
||
- **接口路径**: `POST /private/pools/creators/filter/`
|
||
- **功能**: 根据过滤条件筛选私有库中的达人
|
||
- **请求方法**: POST
|
||
|
||
**URL参数**:
|
||
- `page`: 页码，默认为1
|
||
- `page_size`: 每页数量，默认为10
|
||
|
||
**请求体参数**:
|
||
```json
|
||
{
|
||
"pool_id": 123, // 必填
|
||
"filter": {
|
||
"status": "active", // 可选：active, archived, public_removed
|
||
"category": ["Beauty & Personal Care"], // 多选
|
||
"e_commerce_level": ["L1", "L2", "L3"], // 多选
|
||
"exposure_level": ["KOL-1", "KOC-1"], // 多选
|
||
"gmv_range": ["$0-$5k", "$5k-$25k"], // 多选
|
||
"views_range": ["10k-100k"], // 单选
|
||
"pricing": ["100-500"] // 单选
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应格式**: 同6.3
|
||
|
||
## 错误响应格式
|
||
|
||
所有接口在出错时都会返回统一的错误格式：
|
||
|
||
```json
|
||
{
|
||
"code": 400, // 错误状态码
|
||
"message": "错误描述信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**常见错误码**:
|
||
- `400`: 请求参数错误
|
||
- `401`: 用户未认证
|
||
- `403`: 权限不足
|
||
- `404`: 资源不存在
|
||
- `409`: 资源冲突（如重名）
|
||
- `500`: 服务器内部错误
|
||
|
||
## 使用示例
|
||
|
||
### 筛选达人示例
|
||
```bash
|
||
curl -X POST "https://api.example.com/creators/filter/?page=1" \
|
||
-H "Authorization: Token your_token_here" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"filter": {
|
||
"category": ["Beauty & Personal Care"],
|
||
"e_commerce_level": ["L2", "L3"],
|
||
"gmv_range": ["$5k-$25k", "$25k-$50k"]
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 获取达人详情示例
|
||
```bash
|
||
curl -X GET "https://api.example.com/creators/123/" \
|
||
-H "Authorization: Token your_token_here"
|
||
```
|
||
|
||
### 更新指标数据示例
|
||
```bash
|
||
curl -X POST "https://api.example.com/creators/metrics/update/" \
|
||
-H "Authorization: Token your_token_here" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"creator_id": 123,
|
||
"metrics_type": "video",
|
||
"metrics_data": {
|
||
"start_date": "2024-03-01",
|
||
"end_date": "2024-03-31",
|
||
"gpm": 2.35,
|
||
"videos_count": 12,
|
||
"avg_views": 85000,
|
||
"avg_engagement": 3.2,
|
||
"avg_likes": 2500
|
||
}
|
||
}'
|
||
```
|