# 店铺播放成本明细查询接口 ## 接口信息 - **接口名称**: 店铺播放成本明细查询接口 - **请求方法**: GET - **接口地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/store/play-cost/detail` - **接口描述**: - 查询指定店铺在不同平台（TikTok/Facebook）的每日播放成本明细数据 - 支持按时间范围筛选，获取店铺每日的广告投放表现数据 - 包含广告数量、播放次数、CPM成本、互动数据（点赞、评论、分享）等指标 - 价格说明: `免费` **请求头:** - Content-Type: application/json - Accept: application/json ## 请求参数 ### 请求结构 | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ------ | ------ | --------------------------- | ------------------------------------- | ---- | ------ | | key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | | | uri | string | 接口路径 | "/v3/api/open/store/play-cost/detail" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | ### 请求体参数 (params 对象) | 参数名 | 类型 | 必填 | 描述 | | ------------ | ------- | ----- | ------------------------------------------------------------ | | id | string | true | 店铺 ID 为 13 位字符串（例如：`c2d5b2547218a`），对应店铺榜单列表接口返回结果中的 `store_id` 字段 | | type | integer | false | 平台类型：1-TikTok平台，2-Facebook平台，默认为1 | | time_start | long | false | 开始时间，时间戳（秒），不传则不限制开始时间 | | time_end | long | false | 结束时间，时间戳（秒），不传则不限制结束时间 | | current_page | integer | false | 当前页码，默认为1 | | page_size | integer | false | 每页数量，默认为10 | ### 请求示例 ```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/store/play-cost/detail", "params": { "id": "c2d5b2547218a", "type": 1, "time_start": 1704067200, "time_end": 1706745599, "current_page": 1, "page_size": 10 } }' ``` ## 响应参数 ### 响应体结构 ```json { "code": 200, "message": "success", "data": { "data": [ { "max_cpm": 12.6, "digg_count": 8, "ad_count": 1, "comment": 0, "share": 0, "play_count": 2271, "day": 1706716800, "min_cpm": 3.14 }, { "max_cpm": 17.56, "digg_count": 2, "ad_count": 2, "comment": 0, "share": 0, "play_count": 3165, "day": 1706630400, "min_cpm": 4.38 }, { "max_cpm": 21.28, "digg_count": 6, "ad_count": 2, "comment": 0, "share": 0, "play_count": 3836, "day": 1706544000, "min_cpm": 5.31 }, { "max_cpm": 7.93, "digg_count": 4, "ad_count": 1, "comment": 0, "share": 0, "play_count": 1429, "day": 1706284800, "min_cpm": 1.98 }, { "max_cpm": 30.8, "digg_count": 21, "ad_count": 3, "comment": 0, "share": 1, "play_count": 5552, "day": 1706198400, "min_cpm": 7.69 }, { "max_cpm": 54.11, "digg_count": 20, "ad_count": 3, "comment": 1, "share": 0, "play_count": 9754, "day": 1706112000, "min_cpm": 13.5 }, { "max_cpm": 27.51, "digg_count": 4, "ad_count": 3, "comment": 0, "share": 0, "play_count": 4959, "day": 1706025600, "min_cpm": 6.86 }, { "max_cpm": 46.78, "digg_count": 24, "ad_count": 3, "comment": 0, "share": 2, "play_count": 8434, "day": 1705939200, "min_cpm": 11.68 }, { "max_cpm": 85.55, "digg_count": 54, "ad_count": 3, "comment": 4, "share": 0, "play_count": 15423, "day": 1705852800, "min_cpm": 21.35 }, { "max_cpm": 48.53, "digg_count": 31, "ad_count": 3, "comment": 0, "share": 2, "play_count": 8748, "day": 1705766400, "min_cpm": 12.11 } ], "page": { "total_count": 23, "current_page": 1, "page_count": 3, "page_size": 10 } }, "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 | Array[Object] | 每日数据列表 | | page | Object | 分页信息 | #### data 数组元素结构（每日数据） | 字段名 | 类型 | 描述 | | ----------- | ------- | -------------------------------------------------------------- | | day | Long | 统计日期，时间戳（秒） | | ad_count | Long | 该日广告数量 | | play_count | Long | 该日播放次数（仅TikTok平台有此字段，type=1时返回） | | min_cpm | Double | 该日最小CPM成本（仅TikTok平台有此字段，type=1时返回） | | max_cpm | Double | 该日最大CPM成本（仅TikTok平台有此字段，type=1时返回） | | digg_count | Long | 该日点赞数 | | comment | Long | 该日评论数 | | share | Long | 该日分享数 | **说明**： - 当 type=1（TikTok平台）时，返回所有字段 - 当 type=2（Facebook平台）时，play_count、min_cpm、max_cpm 字段为 null 或不返回 #### page 对象结构 | 字段名 | 类型 | 描述 | | ------------ | ------- | ------------ | | current_page | Integer | 当前页码 | | page_size | Integer | 每页数量 | | total | Long | 总记录数 | ## 响应示例 ### TikTok 平台数据示例（type=1） ```json { "code": 200, "message": "success", "data": { "data": [ { "day": 1706745600, "ad_count": 150, "play_count": 1250000, "min_cpm": 2.5, "max_cpm": 15.8, "digg_count": 35000, "comment": 2500, "share": 1800 }, { "day": 1706659200, "ad_count": 145, "play_count": 1180000, "min_cpm": 2.3, "max_cpm": 14.5, "digg_count": 32000, "comment": 2300, "share": 1650 }, { "day": 1706572800, "ad_count": 138, "play_count": 1050000, "min_cpm": 2.1, "max_cpm": 13.2, "digg_count": 28000, "comment": 2100, "share": 1500 } ], "page": { "current_page": 1, "page_size": 10, "total": 60 } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 0, "fail": false, "success": true } ``` ### Facebook 平台数据示例（type=2） ```json { "code": 200, "message": "success", "data": { "data": [ { "day": 1706745600, "ad_count": 85, "play_count": 0, "min_cpm": null, "max_cpm": null, "digg_count": 12000, "comment": 850, "share": 620 }, { "day": 1706659200, "ad_count": 80, "play_count": 0, "min_cpm": null, "max_cpm": null, "digg_count": 11500, "comment": 800, "share": 580 } ], "page": { "current_page": 1, "page_size": 10, "total": 45 } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 0, "fail": false, "success": true } ``` ## 错误码说明 | 错误码 | 描述 | | ------ | -------------- | | 200 | 成功 | | 400 | 请求参数错误 | | 500 | 服务器内部错误 | ## 使用说明 1. **平台类型说明**： - type=1 查询 TikTok 平台数据，返回包含播放次数和CPM成本的完整数据 - type=2 查询 Facebook 平台数据，返回互动数据但不包含播放次数和CPM成本 2. **时间范围**： - time_start 和 time_end 均为可选参数 - 如果不传时间参数，则返回店铺所有历史数据 - 时间戳单位为秒 3. **数据排序**： - 数据按统计日期（day字段）倒序排列，最新的日期排在前面 4. **分页**： - 支持分页查询，通过 current_page 和 page_size 控制 - 默认每页10条记录