创建监控任务
本文档介绍如何通过广告主账号创建监控任务。创建监控任务支持以下四种方式:
| 方式 |
参数名 |
说明 |
示例 |
| 1. 广告主ID |
facebook_page_id_list |
通过广告主搜索接口获取 |
["614178972053891"] |
| 2. 广告主链接 |
facebook_page_url_list |
直接输入 Facebook 广告主主页链接 |
["https://www.facebook.com/example"] |
| 3. 公共主页编号 |
facebook_public_page_number_list |
输入 Facebook 公共主页编号 |
["123456789"] |
| 4. 店铺/网站链接 |
facebook_shop_url_list |
输入店铺、网站或落地页链接 |
["https://example.com"] |
优先级说明: 如果同时提交多个参数,系统按以下优先级使用: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list
接口一:广告主搜索
接口信息
- 接口名称: 广告主搜索
- 请求方法: POST
- 接口地址:
open-api/v1/monitor/data
- 接口路径:
/v3/api/ad-monitor-task/search-fb-ads-advertiser
- 接口描述: 根据关键词搜索广告主信息,返回匹配的广告主列表。用户可以根据返回的
facebook_page_id 创建监控任务。
- 价格说明: 免费
请求头:
- Content-Type: application/json
- Accept: application/json
请求参数
请求结构
| 参数名 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| key |
string |
用户申请的外部 api 请求 key |
"your_api_key_here" |
是 |
|
| uri |
string |
接口路径 |
"/v3/api/ad-monitor-task/search-fb-ads-advertiser" |
是 |
|
| params |
object |
接口入参对象 |
见参数列表 |
是 |
|
请求体参数 (params 对象)
| 参数名 |
类型 |
必填 |
描述 |
| name |
String |
是 |
广告主名称关键词 |
请求示例
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/ad-monitor-task/search-fb-ads-advertiser",
"params": {
"name": "example"
}
}'
响应参数
响应体结构
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"facebook_page_id": "714739975064116",
"name": "Example Advertiser",
"avatar_url": "https://example.com/avatar.jpg",
"category": "Digital creator",
"country": null
}
]
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 0,
"success": true,
"fail": false
}
响应字段说明
| 字段名 |
类型 |
描述 |
| code |
Integer |
响应状态码,200 表示成功 |
| message |
String |
响应消息 |
| data |
Object |
响应数据 |
| version |
String |
API 版本 |
| timestamp |
String |
响应时间戳 |
| sign |
String |
响应签名 |
| remaining_credits |
Long |
当前请求后的剩余可用积分 |
| consumed_credits |
Long |
本次请求消耗的积分 |
| success |
Boolean |
请求是否成功 |
| fail |
Boolean |
请求是否失败 |
响应结果信息字段
| 字段名 |
类型 |
描述 |
| data[].facebook_page_id |
string |
广告主ID,用于创建监控任务 |
| data[].name |
string |
广告主名称 |
| data[].avatar_url |
string |
广告主头像 |
| data[].category |
string |
类别 |
| data[].country |
string |
国家 |
接口二:创建监控任务
接口信息
- 接口名称: 创建监控任务
- 请求方法: POST
- 接口地址:
open-api/v1/monitor/data
- 接口路径:
/v3/api/ad-monitor-task/create-monitor-task
- 接口描述: 批量创建广告主或店铺/网站的监控任务,支持四种输入方式,并返回每个任务的创建结果。
- 价格说明: 每成功创建一个监控任务,将扣除1积分
请求头:
- Content-Type: application/json
- Accept: application/json
请求参数
请求结构
| 参数名 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| key |
string |
用户申请的外部 api 请求 key |
"your_api_key_here" |
是 |
|
| uri |
string |
接口路径 |
"/v3/api/ad-monitor-task/create-monitor-task" |
是 |
|
| params |
object |
接口入参对象 |
见参数列表 |
是 |
|
请求体参数 (params 对象)
| 参数名 |
类型 |
必填 |
描述 |
| facebook_page_id_list |
array[string] |
否 |
广告主ID列表(可通过广告主搜索接口获取) |
| facebook_page_url_list |
array[string] |
否 |
广告主主页链接列表 |
| facebook_public_page_number_list |
array[string] |
否 |
公共主页编号列表 |
| facebook_shop_url_list |
array[string] |
否 |
店铺/网站/落地页链接列表 |
注意事项:
- 以上四个参数不能全为 null 或空列表,至少需要提供一个
- 每次最多可添加 50 个监控对象
- 如果同时提交多个参数,系统按优先级使用: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list
请求示例
方式1:通过广告主ID创建(推荐)
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/ad-monitor-task/create-monitor-task",
"params": {
"facebook_page_id_list": ["614178972053891", "714739975064116"]
}
}'
方式2:通过广告主链接创建
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/ad-monitor-task/create-monitor-task",
"params": {
"facebook_page_url_list": ["https://www.facebook.com/example"]
}
}'
方式3:通过公共主页编号创建
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/ad-monitor-task/create-monitor-task",
"params": {
"facebook_public_page_number_list": ["123456789"]
}
}'
方式4:通过店铺/网站链接创建
curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/ad-monitor-task/create-monitor-task",
"params": {
"facebook_shop_url_list": ["https://example.com"]
}
}'
响应参数
响应体结构
{
"code": 200,
"message": "success",
"data": [
{
"task_id": "1005",
"facebook_page_id": "614178972053891",
"facebook_page_url": null,
"facebook_public_page_number": null,
"facebook_shop_url": null,
"error_message": null
}
],
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 1,
"fail": false,
"success": true
}
响应字段说明
| 字段名 |
类型 |
描述 |
| code |
Integer |
响应状态码,200 表示成功 |
| message |
String |
响应消息 |
| data |
Array |
响应数据(任务创建结果列表) |
| version |
String |
API 版本 |
| timestamp |
String |
响应时间戳 |
| sign |
String |
响应签名 |
| success |
Boolean |
请求是否成功 |
| fail |
Boolean |
请求是否失败 |
响应结果信息字段
| 字段名 |
类型 |
描述 |
| task_id |
string |
监控任务ID |
| facebook_page_id |
string |
广告主ID |
| facebook_page_url |
string |
广告主链接 |
| facebook_public_page_number |
string |
公共主页编号 |
| facebook_shop_url |
string |
店铺/网站链接 |
| error_message |
string |
错误信息(如有) |
错误码说明
| 错误码 |
描述 |
| 200 |
成功 |
| 400 |
请求参数错误 |
| 500 |
服务器内部错误 |