# 创建监控任务

本文档介绍如何通过广告主账号创建监控任务。创建监控任务支持以下四种方式：

| 方式 | 参数名 | 说明 | 示例 |
| ---- | ------ | ---- | ---- |
| 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 | 是   | 广告主名称关键词 |

#### 请求示例

```bash
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"
    }
  }'
```

### 响应参数

#### 响应体结构

```json
{
  "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] | 否   | 店铺/网站/落地页链接列表                                   |

> **注意事项**:
> 1. 以上四个参数不能全为 null 或空列表，至少需要提供一个
> 2. 每次最多可添加 50 个监控对象
> 3. **如果同时提交多个参数，系统按优先级使用: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list**

#### 请求示例

**方式1：通过广告主ID创建（推荐）**

```bash
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：通过广告主链接创建**

```bash
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：通过公共主页编号创建**

```bash
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：通过店铺/网站链接创建**

```bash
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"]
    }
  }'
```

### 响应参数

#### 响应体结构

```json
{
  "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    | 服务器内部错误 |