# TikTok 商品列表接口 ## API 信息 - **API 名称**: 获取 TikTok 小店商品列表 - **请求方法**: POST - **API 地址**: `/open-api/v1/data` - **接口路径**: `/v3/api/open/tiktok-shop/product/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/product/list" | 是 | | | params | object | 接口入参对象 | 见参数列表 | 是 | | #### 参数列表 (params 对象) | 参数名 | 类型 | 必填 | 描述 | 示例 | 默认值 | | --------------------- | ------- | ---- |---------------------------------------------------------| ----------------- | ------ | | current_page | Integer | 是 | 当前页码，分页查询的当前页数，从 1 开始 | 1 | | | page_size | Integer | 是 | 每页大小，分页查询的每页记录数，默认 20 | 20 | | | sort | Integer | 是 | 排序字段，1-最后时间，2-开始时间，3-销量，4-GMV，5-广告展示，6-广告花费，7-广告数，8-红人数 | 3 | | | sort_type | String | 是 | 排序类型，asc-正序，desc-倒序 | "desc" | | | time | Long | 是 | 时间范围，0-全部，1-昨天，7-近7天，30-近 30 天，90-近 90 天 | 30 | | | categorize | String | 否 | 分类，多个则英文逗号隔开，用于按商品分类进行筛选 | "cat_001,cat_002" | | | commission_rate_max | Double | 否 | 佣金比例最大值，用于筛选佣金比例不超过指定值的商品 | 0.2 | | | commission_rate_min | Double | 否 | 佣金比例最小值，用于筛选佣金比例不低于指定值的商品 | 0.05 | | | cpm_max | Double | 否 | 广告花费最大值（CPM），用于筛选广告花费不超过指定值的商品 | 10.0 | | | cpm_min | Double | 否 | 广告花费最小值（CPM），用于筛选广告花费不低于指定值的商品 | 1.0 | | | delivery | String | 否 | 发货方式，overseas-跨境发货，local-本地发货 | "local" | | | found_time_end | Long | 否 | 广告首次发现时间结束（时间戳），用于筛选在指定时间范围内首次发现的商品 | 1643673600 | | | found_time_start | Long | 否 | 广告首次发现时间开始（时间戳），用于筛选在指定时间范围内首次发现的商品 | 1640995200 | | | gmv_max | Double | 否 | 销售额最大值（GMV），用于筛选销售额不超过指定值的商品 | 100000.0 | | | gmv_min | Double | 否 | 销售额最小值（GMV），用于筛选销售额不低于指定值的商品 | 1000.0 | | | is_in_marketplace | Boolean | 否 | 是否联盟商品，false-非联盟商品，true-联盟商品 | true | | | is_managed | Boolean | 否 | 是否全托管商品，false-非全托管商品，true-全托管商品 | false | | | keyword | String | 否 | 搜索关键词，用于按商品标题、描述等进行模糊搜索 | "手机壳" | | | last_found_time_end | Long | 否 | 广告最后发现时间结束（时间戳），用于筛选在指定时间范围内最后发现的商品 | 1643673600 | | | last_found_time_start | Long | 否 | 广告最后发现时间开始（时间戳），用于筛选在指定时间范围内最后发现的商品 | 1640995200 | | | person_count_max | Long | 否 | 红人数量最大值，用于筛选达人数量不超过指定值的商品 | 100 | | | person_count_min | Long | 否 | 红人数量最小值，用于筛选达人数量不低于指定值的商品 | 1 | | | play_count_max | Long | 否 | 广告展示，播放量/广告曝光最大值，用于筛选播放量不超过指定值的商品 | 1000000 | | | play_count_min | Long | 否 | 广告展示，播放量/广告曝光最小值，用于筛选播放量不低于指定值的商品 | 1000 | | | price_usd_max | Double | 否 | 价格（美元），商品美元价格最大值，用于筛选美元价格不超过指定值的商品 | 100.0 | | | price_usd_min | Double | 否 | 价格（美元），商品美元价格最小值，用于筛选美元价格不低于指定值的商品 | 10.0 | | | region | String | 否 | 国家/地区，多个则英文逗号隔开，用于按地区筛选商品 | "US,GB" | | | sales_trend | Integer | 否 | 销售趋势，1-增长，0-平稳，-1-下降 | 1 | | | sales_volume_max | Long | 否 | 销量最大值，用于筛选销量不超过指定值的商品 | 10000 | | | sales_volume_min | Long | 否 | 销量最小值，用于筛选销量不低于指定值的商品 | 100 | | | search_type | String | 否 | 搜索类型，1-产品名称（描述），2-店铺名称，3-红人名称，默认 1 | "1" | | | shop_id | String | 否 | 店铺 ID，用于筛选指定店铺的商品 | "shop_001" | | | video_count_max | Long | 否 | 广告数最大值，用于筛选广告数量不超过指定值的商品 | 100 | | | video_count_min | Long | 否 | 广告数最小值，用于筛选广告数量不低于指定值的商品 | 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/tiktok-shop/product/list", "params": { "current_page": 1, "page_size": 20, "sort": 3, "sort_type": "desc", "time": 30, "keyword": "手机壳", "region": "US,GB", "price_usd_min": 10.0, "price_usd_max": 50.0, "sales_volume_min": 100 } }' ``` ### 响应 #### 响应体结构 ```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 | 响应状态码 | | **message** | String | 响应消息 | | **data** | Object | 响应数据对象 | | **version** | String | API 版本号 | | **timestamp** | Long | 时间戳（可为 null） | | **sign** | String | 签名（可为 null） | | **remaining_credits** | Long | 当前请求后的剩余可用积分 | | **consumed_credits** | Long | 本次请求消耗的积分 | | **success** | Boolean | 请求是否成功 | | **fail** | Boolean | 请求是否失败 | ##### 商品信息字段 (data) | 字段名 | 类型 | 描述 | | -------------------- | ------- | ------------------------------------------- | | id | String | 商品唯一标识 ID | | image | String | 商品主图片 URL | | title | String | 商品标题 | | desc | String | 商品描述（可选字段） | | price | Double | 商品价格（本地货币） | | price_usd | Double | 商品美元价格 | | sales_volume | Long | 商品销量 | | score | Double | 商品评分 | | shop_name | String | 店铺名称 | | video_count | Long | 广告视频数量 | | categorize | Object | 商品分类信息 | | region | String | 商品投放地区 | | 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 | | root_path | String | 广告主（域名） | | keywords | Array | 商品关键词列表（可选字段） | | card_found_time | Long | 卡片首次发现时间（时间戳） | | card_last_found_time | Long | 卡片最后发现时间（时间戳） | | commission_rate | Double | 佣金比例 | | sales_trend | Integer | 销售趋势，1-增长，0-平稳，-1-下降 | | sales_trend_data | Array | 销售趋势数据列表 | | gmv | Double | 销售额（GMV） | | delivery | String | 发货方式，overseas-跨境发货，local-本地发货 | | is_in_marketplace | Boolean | 是否联盟商品 | | is_managed | Boolean | 是否全托管商品 | | person_count | Long | 达人数量 | | shop_sales_volume | Long | 店铺销量 | | gmv_usd | Double | 美元销售额（GMV USD） | ##### 商品分类信息对象字段 (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 | 当日销量 | ##### 分页信息字段 (page) | 字段名称 | 类型 | 描述 | | ------------ | ------- | ------------ | | total_count | Long | 总记录数 | | page_count | Long | 总页数 | | current_page | Long | 当前页码 | | page_size | Long | 每页大小 | | is_next | Boolean | 是否有下一页 | #### 响应示例 ```json { "code": 200, "message": "success", "data": { "data": [ { "id": "1731082690126648263", "image": "https://im.pipispy.com/products/images/4b5f6645b62f59e6.png", "title": "Scrub Daddy 10-Piece Multi-Color Microfiber Towel Set Colorful Cleaning", "price": 16.98, "price_usd": 16.98, "sales_volume": 2954, "score": 4.9, "shop_name": "QVC, Inc", "video_count": 30, "categorize": { "_id": "600409", "name_zh": "清洁抹布", "name_vi": "Khăn lau", "name_th": "ผ้าเช็ดทำความสะอาด", "name_pt": "Cleaning Cloths", "name_ja": "Cleaning Cloths", "name_id": "Kain Pembersih", "name_en": "Cleaning Cloths" }, "region": "US", "play_count": 3604387, "share_count": 1095, "found_time": 1748325472, "last_found_time": 1752200041, "insert_time": 1747783755, "update_time": 1752200071, "min_cpm": 12327.0, "max_cpm": 49416.15, "currency": "USD", "shop_id": "7495811038271212487", "is_collection": false, "shop_image": "https://im.pipispy.com/shops/images/63f695e743c88654.png", "root_path": "shop.tiktok.com", "card_found_time": 1748325472, "card_last_found_time": 1752200041, "commission_rate": 0.0, "sales_trend": 1, "sales_trend_data": [ { "day": 1748188800, "sales_volume": 139 }, { "day": 1748275200, "sales_volume": 1 } ], "gmv": 50158.92, "delivery": "local", "is_in_marketplace": false, "is_managed": true, "person_count": 20, "shop_sales_volume": 559338, "gmv_usd": 50158.92 } ], "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 | 服务器内部错误 |