# 店铺 Meta 广告资料库最长运营广告文案列表接口

## 接口信息

- **接口名称**: 获取店铺最长运营广告文案列表
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ppspy/pp-stores/ad-content/longest-run`
- **接口描述**: 获取指定店铺在Meta广告资料库中运营时间最长的广告文案列表，包括广告内容、媒体素材（图片/视频/轮播）、投放天数等信息，帮助分析店铺的长期稳定投放的广告素材
- **价格说明**: `免费`

**请求头:**

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

## 请求参数

### 请求结构

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

### 请求体参数 (params 对象)

| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| id | String | 是 | 店铺唯一标识ID，为13位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 |
| order_by | String | 否 | 排序字段。可选值：`active_days`-按投放天数排序，`ad_started_at`-按广告开始时间排序。默认值：`active_days` |
| direction | String | 否 | 排序方式。可选值：`desc`-降序（从大到小/从新到旧），`asc`-升序（从小到大/从旧到新）。默认值：`desc` |
| page_size | Long | 否 | 每页记录数，指定单页返回的广告数量。默认值：20 |
| current_page | Long | 否 | 当前页码，页码从1开始。默认值：1 |

### 请求示例

```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/pp-stores/ad-content/longest-run",
    "params": {
        "id": "c2d5b2547218a",
        "order_by": "active_days",
        "direction": "desc",
        "page_size": 20,
        "current_page": 1
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [],
    "first_page_url": "",
    "from": 1,
    "is_logged_in": false,
    "last_page": 1,
    "last_page_url": "",
    "next_page_url": null,
    "path": "",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 100
  },
  "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.data)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| current_page | Long | 当前页码 |
| data | Array | 广告内容列表 |
| first_page_url | String | 第一页的URL地址 |
| from | Long | 起始记录位置（当前页第一条记录在总结果集中的位置） |
| is_logged_in | Boolean | 用户是否已登录，用于标识数据权限状态 |
| last_page | Long | 最后一页的页码（总页数） |
| last_page_url | String | 最后一页的URL地址 |
| next_page_url | String | 下一页的URL地址，如果没有下一页则为null |
| path | String | API请求路径 |
| per_page | Long | 每页记录数 |
| prev_page_url | String | 上一页的URL地址，如果没有上一页则为null |
| to | Long | 结束记录位置（当前页最后一条记录在总结果集中的位置） |
| total | Long | 总记录数 |

### 广告内容字段 (AdContent)

| 字段名 | 类型 | 描述                          |
| ------ | ---- |-----------------------------|
| id | String | 广告唯一标识ID                    |
| source_ad_id | String | 原始广告ID（来源平台的广告唯一标识）         |
| ad_content | String | 广告文案内容                      |
| media_format | Long | 媒体格式类型。1-单图，2-单视频，3-轮播      |
| images | Array | 图片素材列表，当 media_format=1 时有值 |
| videos | Array | 视频素材列表，当 media_format=2 时有值 |
| cards | Array | 轮播卡片列表，当 media_format=3 时有值 |
| ad_started_at | Long | 广告开始投放时间，Unix时间戳（秒级）        |
| active_days | Long | 广告投放天数（从开始到现在或结束的天数）        |
| ad_status | Long | 广告状态。1-活跃投放中，2-不活跃，3-下架     |
| ad_content_md5 | String | 广告内容的MD5哈希值，用于标识相同内容的广告     |

### 图片素材字段 (Image)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| url | String | 图片资源URL地址 |
| width | Long | 图片宽度（像素） |
| height | Long | 图片高度（像素） |

### 视频素材字段 (Video)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| url | String | 视频资源URL地址 |
| width | Long | 视频宽度（像素） |
| height | Long | 视频高度（像素） |
| duration | Double | 视频时长（秒） |
| cover_url | String | 视频封面图URL地址 |

### 轮播卡片字段 (Card)

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| url | String | 卡片媒体资源URL地址（图片或视频） |
| width | Long | 媒体宽度（像素） |
| height | Long | 媒体高度（像素） |
| duration | Double | 视频时长（秒），仅当 media_type=1 时有值 |
| cover_url | String | 视频封面图URL地址，仅当 media_type=1 时有值 |
| media_type | Long | 媒体类型。1-视频，2-图片 |

## 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": "ad_001",
        "source_ad_id": "123456789012345",
        "ad_content": "Shop now and get 50% off! Limited time offer. Free shipping on orders over $50.",
        "media_format": 2,
        "images": [],
        "videos": [
          {
            "url": "https://example.com/video/ad_video_001.mp4",
            "width": 1080,
            "height": 1920,
            "duration": 15.5,
            "cover_url": "https://example.com/cover/ad_cover_001.jpg"
          }
        ],
        "cards": [],
        "ad_started_at": 1680000000,
        "active_days": 180,
        "ad_status": 1,
        "ad_content_md5": "a1b2c3d4e5f6g7h8i9j0"
      },
      {
        "id": "ad_002",
        "source_ad_id": "123456789012346",
        "ad_content": "New arrivals! Check out our latest collection.",
        "media_format": 3,
        "images": [],
        "videos": [],
        "cards": [
          {
            "url": "https://example.com/image/card_001.jpg",
            "width": 1080,
            "height": 1080,
            "duration": null,
            "cover_url": null,
            "media_type": 2
          },
          {
            "url": "https://example.com/video/card_002.mp4",
            "width": 1080,
            "height": 1080,
            "duration": 10,
            "cover_url": "https://example.com/cover/card_002.jpg",
            "media_type": 1
          }
        ],
        "ad_started_at": 1685000000,
        "active_days": 120,
        "ad_status": 1,
        "ad_content_md5": "b2c3d4e5f6g7h8i9j0k1"
      },
      {
        "id": "ad_003",
        "source_ad_id": "123456789012347",
        "ad_content": "Best seller! Don't miss out.",
        "media_format": 1,
        "images": [
          {
            "url": "https://example.com/image/ad_image_001.jpg",
            "width": 1200,
            "height": 628
          }
        ],
        "videos": [],
        "cards": [],
        "ad_started_at": 1690000000,
        "active_days": 90,
        "ad_status": 0,
        "ad_content_md5": "c3d4e5f6g7h8i9j0k1l2"
      }
    ],
    "first_page_url": "https://api.example.com/ads?page=1",
    "from": 1,
    "is_logged_in": false,
    "last_page": 5,
    "last_page_url": "https://api.example.com/ads?page=5",
    "next_page_url": "https://api.example.com/ads?page=2",
    "path": "https://api.example.com/ads",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 100
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

## 错误码说明

| 错误码 | 描述           |
| ------ | -------------- |
| 200    | 成功           |
| 400    | 请求参数错误   |
| 401    | 未授权         |
| 403    | 权限不足       |
| 500    | 服务器内部错误 |**