# 广告库产品详情接口

## 接口信息

- **接口名称**: 广告库产品详情
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ppspy/ad-products/detail`
- **接口描述**: 根据产品ID获取广告库产品的详细信息，包括产品基本信息、广告数据、店铺信息、广告主信息以及广告数量趋势等完整数据
- **价格说明**: 基础费用：1 credit/次。 免费访问条件（满足其一即可）： 该ID在3天内已获取过详情；该ID在3天内出现在您的榜单列表查询结果中。

**请求头:**

- Content-Type: application/json
- Accept: application/json

## 请求参数

### 请求结构

| 参数名 | 类型   | 描述                        | 示例                           | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ------------------------------ | ---- | ------ |
| key    | string | 用户申请的外部 api 请求 key | "your_api_key_here"            | 是   |        |
| uri    | string | 接口路径                    | "/v3/api/open/ppspy/ad-products/detail" | 是   |        |
| params | object | 接口入参对象                | 见参数列表                     | 是   |        |

### 路径参数

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| id | String | 是 | 产品ID，用于标识要查询的具体产品。可以从产品搜索接口的返回结果中获取 |

### 请求示例

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/open/ppspy/ad-products/detail",
    "params": {
      "id": "5b9ac27f7b3d21aecdca5cb00be71baa"
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "product": {},
    "store": {},
    "advertisers": [],
    "ad_started_history": []
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}
```

### 响应字段说明

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| code | Integer | 业务状态码，200 表示成功 |
| message | String | 响应的消息，成功时通常为"success" |
| data | Object | 响应的数据对象 |
| version | string        | API 版本                 |
| timestamp | number        | 响应时间戳               |
| sign | string        | 响应签名                 |
| remaining_credits | Long    | 当前请求后的剩余可用积分 |
| consumed_credits  | Long    | 本次请求消耗的积分 |
| success | boolean       | 请求是否成功             |
| fail | boolean       | 请求是否失败             |

### 数据对象字段 (data)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| product | Object | 产品信息，包含产品的完整详细数据 |
| store | Object | 店铺信息，产品所属店铺的详细信息 |
| advertisers | Array | 广告主信息列表，投放该产品广告的所有广告主数据 |
| ad_started_history | Array | 广告数量的趋势，展示产品广告投放的历史趋势数据 |

### 产品信息字段 (product)

#### 基本信息

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| id | String | 产品ID，产品的唯一标识符 |
| name | String | 产品名称 |
| price | Double | 产品价格（原始货币） |
| price_usd | Double | 产品美元价格，统一换算为美元方便比较 |
| currency | String | 货币单位，如USD、EUR等 |
| image_url | String | 产品主图URL，产品的主要展示图片 |
| images | String Array | 产品图片列表，包含产品的所有图片URL |
| source_product_id | String | 电商平台的产品ID，在原电商平台的产品标识 |
| source_product_link | String | 产品链接，产品在电商平台的详情页URL |
| e_commerce_platform | String | 电商平台，产品所在的电商平台名称 |
| store_id | String | 店铺ID，产品所属店铺的唯一标识 |
| category_id | String | 分类ID，产品所属分类的唯一标识 |
| category_name | String | 分类名称，产品所属的分类名称 |
| creation_time | Long | 产品创建时间，时间戳：秒 |
| user_collected | Integer | 是否已收藏，可选值：<br>• 1 - 未收藏<br>• 2 - 已收藏 |

#### 广告数据

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| ad_status | Integer | 广告状态，可选值：1-活跃中，2-已停止 |
| ad_forecast | Integer | AI分数，可选值：1-测品阶段，2-上升阶段，3-盈利阶段 |
| active_ad_count | Integer | 活跃广告数，当前正在投放的广告数量 |
| ad_count | Integer | 广告数，产品总共创建的广告数量 |
| active_adset_count | Integer | 活跃广告组数，当前正在投放的广告组数量 |
| adset_count | Integer | 总广告组数，产品总共创建的广告组数量 |
| adset_count_24h | Integer | 24小时广告组数，最近24小时内新增的广告组数量 |
| active_days | Integer | 广告天数，产品持续投放广告的天数 |
| ad_started_at | Long | 广告开始时间，时间戳：秒。产品首次开始投放广告的时间 |
| ad_ended_at | Long | 广告结束时间，时间戳：秒。产品最后一次广告投放的结束时间 |
| ad_cost | Double | 广告花费，单位：美元。产品累计的广告投入成本 |
| ad_audience_reach | Integer | 覆盖人数，广告触达的独立用户总数 |
| ad_platform | String Array | 广告平台列表，产品投放广告的平台，如FACEBOOK、INSTAGRAM等 |

### 店铺信息字段 (store)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| id | String | 店铺ID，店铺的唯一标识符 |
| name | String | 店铺名称 |
| logo_url | String | 店铺logo图片URL |
| e_commerce_platform | String | 电商平台，店铺所在的电商平台名称 |
| source_store_link | String | 店铺链接，店铺在电商平台的主页URL |
| month_visits | Integer | 月访问量，店铺的月度访问量（预估值） |
| published_products_count | Integer | 产品数量，店铺发布的产品总数 |
| monthly_sales | Integer | 月销量，店铺的月度销售数量（预估值） |

### 广告主信息字段 (advertisers)

advertisers 是一个数组，包含投放该产品广告的所有广告主信息。每个广告主对象包含以下字段：

#### 基本信息

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| id | String | 广告主ID，广告主的唯一标识符 |
| name | String | 广告主的名字 |
| profile_picture_url | String | 广告主头像链接 |
| source_advertiser_id | String | 广告主的主页ID，在广告平台上的主页标识 |
| source_advertiser_link | String | 广告主的主页链接，广告主在广告平台的主页URL |
| ads_library_link | String | 广告主的广告库链接，查看该广告主所有广告的链接 |
| category_name | String | 分类，广告主所属的分类 |
| creation_time | Long | 创建时间，时间戳：秒 |

#### 广告数据

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| ad_status | Integer | 广告状态，可选值：1-活跃中，2-已停止 |
| active_ad_count | Integer | 活跃的广告数，该广告主当前正在投放的广告数量 |
| inactive_ad_count | Integer | 不活跃的广告数，已暂停投放的广告数量 |
| removed_ad_count | Integer | 已下架的广告数，已删除或下架的广告数量 |
| ad_count | Integer | 广告素材数，该广告主总共创建的广告数量 |
| adset_count | Integer | 广告组数，该广告主创建的广告组总数 |
| active_days | Integer | 广告天数，该广告主持续投放广告的天数 |
| ad_started_at | Long | 广告开始时间，时间戳：秒 |
| ad_ended_at | Long | 广告结束时间，时间戳：秒 |
| ad_country | String Array | 投放国家列表，该广告主广告投放的国家代码 |
| ad_platform | String Array | 广告平台列表，该广告主使用的广告平台 |
| like_count | Integer | 点赞数，该广告主广告获得的点赞总数 |
| ad_source | Integer | 广告来源 |

### 广告趋势数据字段 (ad_started_history)

ad_started_history 是一个数组，记录产品广告数量随时间的变化趋势。每个趋势数据点包含以下字段：

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| date | String | 日期，UTC时间。格式：YYYY-MM-DD |
| count | Integer | 广告数，该日期对应的广告数量 |

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "advertisers": [
      {
        "id": "f57f4c9d3ea20be66a132adb5f557eba",
        "name": "wijnvoordeel.be",
        "active_ad_count": 9,
        "active_days": 780,
        "ad_count": 321,
        "ad_country": [
          "BE",
          "other"
        ],
        "ad_ended_at": 1766995200,
        "ad_started_at": 1699603200,
        "ad_status": 1,
        "ads_library_link": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=186022184808923",
        "adset_count": 531,
        "creation_time": 1318448479,
        "inactive_ad_count": 0,
        "like_count": 19420,
        "profile_picture_url": "https://scontent-lga3-1.xx.fbcdn.net/v/t39.35426-6/599566144_1210304384349710_4804416712767355916_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=UydCX9qVwIMQ7kNvwGqJ0kM&_nc_oc=AdnRT5BJoxS5kk-6exgTkCsIjeAeP4S6lmunXkvWZZOS6QNPr_cXeohqsKL1RegXxU4&_nc_zt=14&_nc_ht=scontent-lga3-1.xx&_nc_gid=lEhGO0OMT5L5L9xSpwx3OA&oh=00_AfnI22FlLJw3cHbRiXqUAIQRp1pSWWmgsYlAgNt9RC5y3Q&oe=69592A57",
        "removed_ad_count": 312,
        "ad_source": 1,
        "category_name": "Wine, Beer & Spirits Store",
        "source_advertiser_id": "186022184808923",
        "source_advertiser_link": "https://facebook.com/WijnvoordeelBE"
      }
    ],
    "product": {
      "currency": "EUR",
      "id": "5b9ac27f7b3d21aecdca5cb00be71baa",
      "images": [
        "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
        "https://fb-cdn.ppspy.com/images/pimg_6ca311198854c6eeeffc9.png",
        "https://fb-cdn.ppspy.com/images/pimg_0d9e6a0a2e72f9f291f07.png",
        "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
        "https://fb-cdn.ppspy.com/images/pimg_6ca311198854c6eeeffc9.png"
      ],
      "name": "Infinitum Grillo",
      "price": 5.79,
      "active_ad_count": 1,
      "active_adset_count": 1,
      "active_days": 2,
      "ad_audience_reach": 368,
      "ad_cost": 6.6,
      "ad_count": 1,
      "ad_ended_at": 1766995200,
      "ad_forecast": 1,
      "ad_started_at": 1766822400,
      "ad_status": 1,
      "adset_count": 1,
      "adset_count_24h": 0,
      "category_id": "62739aec38365b2f72048ebd",
      "ad_platform": [
        "FACEBOOK",
        "INSTAGRAM",
        "MESSENGER",
        "THREADS"
      ],
      "category_name": "Food",
      "e_commerce_platform": "magento",
      "price_usd": 6.82,
      "source_product_id": "c068345331a01d1216591db170f03672",
      "image_url": "https://fb-cdn.ppspy.com/images/pimg_c1cb26db9e59ba4c70688.png",
      "source_product_link": "https://www.wijnvoordeel.be/infinitum-grillo?channable=019969736b75004b3230303738324e",
      "store_id": "2382cd09c06c7d31cdca5cb00be71baa",
      "user_collected": 2
    },
    "store": {
      "id": "2382cd09c06c7d31cdca5cb00be71baa",
      "name": "wijnvoordeel.be",
      "e_commerce_platform": "magento",
      "logo_url": "https://fb-cdn.pipiads.com/icon_ad0a30d8c8334ccbf37488a8ce91377b.png",
      "month_visits": 19928,
      "source_store_link": "http://wijnvoordeel.be"
    },
    "ad_started_history": [
      {
        "count": 1,
        "date": "2025-12-27"
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}
```

## 错误码说明

| 错误码 | 描述 |
| ------ | ---- |
| 200 | 成功 |
| 400 | 请求参数错误，产品ID格式不正确 |
| 401 | 未授权，API key无效或已过期 |
| 403 | 权限不足，账户余额不足或接口访问受限 |
| 404 | 产品不存在，找不到指定ID的产品 |
| 444 | 请求过于频繁，已触发限流 |
| 500 | 服务器内部错误，请稍后重试 |

## 注意事项

1. **产品ID获取**: 产品ID需要从广告产品搜索接口 (`/v3/api/open/ppspy/ad-products/search`) 的返回结果中获取
2. **数据完整性**: 某些字段可能为null，表示该数据暂未收集或不适用于该产品
3. **广告主数量**: `advertisers` 数组可能包含多个广告主，表示有多个广告主在推广同一个产品
4. **趋势数据**: `ad_started_history` 提供了时间序列数据，可用于绘制趋势图表
5. **时间格式**:
   - 产品和广告主的时间字段使用Unix时间戳（秒级）
   - 趋势数据的日期使用UTC时间，格式为 YYYY-MM-DD
6. **货币单位**: 所有价格相关字段（`price`、`price_usd`、`ad_cost`）的单位可能不同，注意区分
7. **广告平台**: `ad_platform` 字段可能包含多个平台，如FACEBOOK、INSTAGRAM、AUDIENCE_NETWORK、MESSENGER等
8. **分类信息**: 产品和广告主可能属于不同的分类，`category_id` 和 `category_name` 分别对应产品和广告主的分类
9. **数据更新**: 广告数据会定期更新，建议定期重新查询以获取最新数据
10. **收藏状态**: `user_collected` 字段反映当前API用户的收藏状态，不同用户查询同一产品可能返回不同值