# TikTok 店铺列表接口 ## 接口信息 - **接口名称**: 获取 TikTok 小店店铺列表 - **请求方法**: POST - **接口地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/tiktok-shop/shop/list` - **接口描述**: 根据过滤条件获取 TikTok 小店的店铺列表信息 - **价格说明**: 获取一条数据结果消耗1 credit **请求头:** - Content-Type: application/json - Accept: application/json ## 请求参数 ### 请求结构 | 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 | | ------ | ------ | --------------------------- | ------------------------------------ | ---- | ------ | | key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | | | uri | string | 接口路径 | "/v3/api/open/tiktok-shop/shop/list" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | ### 请求体参数 (params 对象) | 参数名 | 类型 | 必填 | 描述 | | --------------------- | ------- | ---- |-----------------------------------------------------------------------------| | avg_price_usd_max | Double | 否 | 平均销售价格(美元)最大值，用于筛选平均美元价格不超过指定值的店铺 | | avg_price_usd_min | Double | 否 | 平均销售价格(美元)最小值，用于筛选平均美元价格不低于指定值的店铺 | | categorize | String | 否 | 分类，用于按店铺分类进行筛选 | | cpm_max | Double | 否 | 广告花费最大值（CPM），用于筛选广告花费不超过指定值的店铺 | | cpm_min | Double | 否 | 广告花费最小值（CPM），用于筛选广告花费不低于指定值的店铺 | | current_page | Integer | 否 | 当前页码，分页查询的当前页数，从 1 开始 | | delivery | String | 否 | 店铺类型，overseas-跨境店，local-本地店 | | found_time_end | Long | 否 | 广告首次发现时间结束（时间戳），用于筛选在指定时间范围内首次发现的店铺 | | found_time_start | Long | 否 | 广告首次发现时间开始（时间戳），用于筛选在指定时间范围内首次发现的店铺 | | gmv_max | Double | 否 | 销售额最大值（GMV），用于筛选销售额不超过指定值的店铺 | | gmv_min | Double | 否 | 销售额最小值（GMV），用于筛选销售额不低于指定值的店铺 | | goods_count_max | Long | 否 | 商品数量最大值，用于筛选商品数量不超过指定值的店铺 | | goods_count_min | Long | 否 | 商品数量最小值，用于筛选商品数量不低于指定值的店铺 | | is_managed | Boolean | 否 | 是否全托管店铺，false-非全托管店铺，true-全托管店铺 | | keyword | String | 否 | 搜索关键词，用于按店铺名称、描述等进行模糊搜索 | | last_found_time_end | Long | 否 | 广告最后发现时间结束（时间戳），用于筛选在指定时间范围内最后发现的店铺 | | last_found_time_start | Long | 否 | 广告最后发现时间开始（时间戳），用于筛选在指定时间范围内最后发现的店铺 | | page_size | Integer | 否 | 每页大小，分页查询的每页记录数 | | person_count_max | Long | 否 | 红人数量最大值，用于筛选达人数量不超过指定值的店铺 | | person_count_min | Long | 否 | 红人数量最小值，用于筛选达人数量不低于指定值的店铺 | | play_count_max | Long | 否 | 广告展示， 播放量/广告曝光最大值，用于筛选播放量不超过指定值的店铺 | | play_count_min | Long | 否 | 广告展示，播放量/广告曝光最小值，用于筛选播放量不低于指定值的店铺 | | product_type | String | 否 | 商品类型，brand-品牌，retail-零售商 | | region | String | 否 | 国家/地区，用于按地区筛选店铺 | | sales_trend | Integer | 否 | 销售趋势，1-增长，0-平稳，-1-下降 | | sales_volume_max | Long | 否 | 销量最大值，用于筛选销量不超过指定值的店铺 | | sales_volume_min | Long | 否 | 销量最小值，用于筛选销量不低于指定值的店铺 | | sort | Integer | 否 | 排序字段，1-最后广告时间，2-首次广告时间，3-销量，4-GMV，5-广告展示，6-广告花费，7-广告数，8-红人数，9-商品数，10-平均销售价格 | | sort_type | String | 否 | 排序类型，asc-正序，desc-倒序 | | time | Long | 否 | 时间范围，0-全部，1-昨天，7-近7天，30-近30天，90-近90天 | | video_count_max | Long | 否 | 广告数最大值，用于筛选广告数量不超过指定值的店铺 | | video_count_min | Long | 否 | 广告数最小值，用于筛选广告数量不低于指定值的店铺 | ### 请求示例 ```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/tiktok-shop/shop/list", "params": { "current_page": 1, "page_size": 20, "sort": 3, "sort_type": "desc", "time": 30, "keyword": "时尚配件", "region": "US", "avg_price_usd_min": 10.0, "avg_price_usd_max": 100.0, "sales_volume_min": 1000, "product_type": "brand" } }' ``` ## 响应参数 ### 响应体结构 ```json { "code": 200, "message": "success", "data": { "data": [], "page": {} }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ### 响应字段说明 | 字段名 | 类型 | 描述 | | --------- | ------- | ------------------------- | | code | Integer | 响应状态码，200 表示成功 | | message | String | 响应消息 | | data | Object | 响应数据 | | data.data | Array | 店铺列表 | | data.page | Object | 分页信息 | | version | String | API 版本 | | timestamp | Long | 响应时间戳（此处为 null） | | sign | String | 响应签名（此处为 null） | | remaining_credits | Long | 当前请求后的剩余可用积分 | | consumed_credits | Long | 本次请求消耗的积分 | | success | Boolean | 请求是否成功 | | fail | Boolean | 请求是否失败 | ### 店铺信息字段 | 字段名 | 类型 | 描述 | | ------------------ | ------- | ----------------------------------------------- | | id | String | 店铺唯一标识 ID | | image | String | 店铺主图片 URL | | title | String | 店铺标题 | | sales_volume | Long | 店铺销量 | | score | Double | 店铺评分 | | shop_name | String | 店铺名称 | | video_count | Long | 广告视频数量 | | categorize | Array | 店铺分类信息列表（第三级分类） | | region | Array | 店铺投放地区列表 | | play_count | Long | 播放量/广告曝光数 | | share_count | Long | 分享数 | | found_time | Long | 首次发现时间（时间戳） | | last_found_time | Long | 最后发现时间（时间戳） | | insert_time | Long | 数据入库时间（时间戳） | | update_time | Long | 数据更新时间（时间戳） | | min_cpm | Double | 最小广告花费（CPM） | | max_cpm | Double | 最大广告花费（CPM） | | currency | String | 货币类型 | | shop_id | String | 店铺 ID | | is_collection | Boolean | 是否已收藏 | | shop_image | String | 店铺图片 URL | | sales_trend | Integer | 销售趋势，1-增长，0-平稳，-1-下降 | | sales_trend_data | Array | 销售趋势数据列表 | | gmv | Double | 销售额（GMV） | | is_in_marketplace | Boolean | 是否联盟店铺 | | is_managed | Boolean | 是否全托管店铺 | | person_count | Long | 达人数量 | | gmv_usd | Double | 美元销售额（GMV USD） | | goods_count | Long | 商品数量 | | goods_ad_count | String | 广告商品数量 | | best_selling_goods | Array | 最畅销商品列表 | | avg_price | Double | 平均价格（本地货币） | | avg_price_usd | Double | 平均美元价格 | | product_type | Array | 产品类型列表，brand-品牌，retail-零售商 | | delivery | Array | 发货方式列表，overseas-跨境发货，local-本地发货 | ### 分类信息字段 (categorize 数组) | 字段名 | 类型 | 描述 | | ------- | ------ | ---------------- | | \_id | String | 分类 ID | | name_zh | String | 中文分类名称 | | name_vi | String | 越南语分类名称 | | name_th | String | 泰语分类名称 | | name_pt | String | 葡萄牙语分类名称 | | name_ja | String | 日语分类名称 | | name_id | String | 印尼语分类名称 | | name_en | String | 英语分类名称 | ### 销售趋势数据字段 (sales_trend_data 数组) | 字段名 | 类型 | 描述 | | ------------ | ---- | ---------- | | day | Long | 日期时间戳 | | sales_volume | Long | 该日销量 | ### 最畅销商品字段 (best_selling_goods 数组) | 字段名 | 类型 | 描述 | | ------------ | ------ | ------------ | | product_id | String | 商品 ID | | image | String | 商品图片 URL | | sales_volume | Long | 商品销量 | ##### 分页信息字段 (page) | 字段名称 | 类型 | 描述 | | ------------ | ------- | ------------ | | total_count | Long | 总记录数 | | page_count | Long | 总页数 | | current_page | Long | 当前页码 | | page_size | Long | 每页大小 | | is_next | Boolean | 是否有下一页 | ## 响应示例 ```json { "code": 200, "message": "success", "data": { "data": [ { "id": "7495432992748505937", "image": "https://im.pipispy.com/shops/images/5ecdf34a797edc74.png", "title": "ZOOONE NATURE", "sales_volume": 484186, "score": 4.3, "shop_name": "ZOOONE NATURE", "video_count": 3157, "categorize": [ { "_id": "700650", "name_zh": "保健食品", "name_vi": "Thực phẩm bổ sung sức khỏe", "name_th": "อาหารเสริมเพื่อสุขภาพ", "name_pt": "Vitamins, Minerals & Wellness Supplements", "name_ja": "Vitamins, Minerals & Wellness Supplements", "name_id": "Suplemen Kesehatan", "name_en": "Vitamins, Minerals & Wellness Supplements" } ], "region": ["US"], "play_count": 203301212, "share_count": 254734, "found_time": 1701638465, "last_found_time": 1752199606, "insert_time": 1702748197, "update_time": 1752199633, "min_cpm": 695290.15, "max_cpm": 2787259.62, "currency": "USD", "shop_id": "7495432992748505937", "is_collection": false, "shop_image": "https://im.pipispy.com/shops/images/5ecdf34a797edc74.png", "sales_trend": -1, "sales_trend_data": [ { "day": 1744300800, "sales_volume": 3565 } ], "gmv": 12908398.76, "is_in_marketplace": true, "is_managed": true, "person_count": 280, "gmv_usd": 12908398.76, "goods_count": 24, "goods_ad_count": "25", "best_selling_goods": [ { "product_id": "1730501450773467985", "image": "https://im.pipispy.com/products/images/9f33b35307396d27.png", "sales_volume": 190407 } ], "avg_price": 26.66, "avg_price_usd": 26.66, "product_type": ["brand", "retail"], "delivery": ["local"] } ], "page": { "total_count": 10000, "page_count": 500, "current_page": 1, "page_size": 20, "is_next": true } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` ## 错误码说明 | 错误码 | 描述 | | ------ | -------------- | | 200 | 成功 | | 400 | 请求参数错误 | | 500 | 服务器内部错误 |