# TikTok 商品详情接口

## API 信息

- **API 名称**: 获取 TikTok 小店商品详情
- **请求方法**: POST
- **API 地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/tiktok-shop/product/detail`
- **接口描述**: 根据商品 ID 获取 TikTok 小店的商品详细信息
- **价格说明**: 详情接口计费规则： 基础费用：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/tiktok-shop/product/detail" | 是   |        |
| params | object | 接口入参对象                | 见参数列表                                | 是   |        |

#### 参数列表 (params 对象)

| 参数名 | 类型   | 必填 | 描述            | 示例        | 默认值 |
| ------ | ------ | ---- | --------------- | ----------- | ------ |
| id     | String | 是   | 商品唯一标识 ID | "123456789" |        |

#### 请求示例

```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/detail",
    "params": {
      "id": "123456789"
    }
  }'
```

### 响应

#### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    // 商品详情信息
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}
```

#### 响应字段说明

##### 主要响应字段

| 字段名        | 类型        | 描述         |
| ------------- | ----------- | ------------ |
| **data**      | Object      | 商品详情信息 |
| **version**   | String      | API 版本     |
| **timestamp** | String/null | 响应时间戳   |
| **sign**      | String/null | 响应签名     |
| **remaining_credits** | Long          | 当前请求后的剩余可用积分 |
| **consumed_credits**  | Long          | 本次请求消耗的积分 |
| **success**   | Boolean     | 请求成功状态 |
| **fail**      | Boolean     | 请求失败状态 |

##### 商品详情字段 (data)

| 字段名            | 类型    | 描述                                        |
| ----------------- | ------- | ------------------------------------------- |
| id                | String  | 商品唯一标识 ID                             |
| image             | String  | 商品主图片 URL                              |
| title             | String  | 商品标题                                    |
| landing_page      | String  | 商品落地页 URL                              |
| desc              | String  | 商品描述                                    |
| currency          | String  | 货币类型                                    |
| price             | Double  | 商品价格（本地货币）                        |
| price_usd         | Double  | 商品美元价格                                |
| sales_volume      | Long    | 商品销量                                    |
| commission_rate   | Double  | 佣金比例                                    |
| sales_trend       | Integer | 销售趋势，1-增长，0-平稳，-1-下降           |
| sales_trend_data  | Array   | 销售趋势数据列表                            |
| score             | Double  | 商品评分                                    |
| gmv               | Double  | 销售额（GMV）                               |
| gmv_usd           | Double  | 美元销售额（GMV USD）                       |
| delivery          | String  | 发货方式，overseas-跨境发货，local-本地发货 |
| is_in_marketplace | Boolean | 是否联盟商品                                |
| is_managed        | Boolean | 是否全托管商品                              |
| person_count      | Long    | 达人数量                                    |
| video_count       | Long    | 广告视频数量                                |
| categorize        | Object  | 商品分类信息                                |
| region            | String  | 商品投放地区                                |
| play_count        | Long    | 播放量/广告曝光数                           |
| like_count        | Long    | 点赞数                                      |
| like_rate         | Double  | 点赞率                                      |
| comment_count     | Long    | 评论数                                      |
| product_comment   | 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）                         |
| shop_info         | Object  | 店铺信息                                    |
| is_collection     | Boolean | 是否已收藏                                  |
| root_path         | String  | 广告主（域名）                          |
| image_list        | Array   | 商品图片列表 URL                            |

##### 商品分类信息对象字段 (categorize)

| 字段名     | 类型   | 描述                   |
| ---------- | ------ | ---------------------- |
| \_id       | String | 分类 ID                |
| parent_id  | String | 父分类 ID              |
| name_zh    | String | 中文分类名称           |
| name_vi    | String | 越南语分类名称         |
| name_th    | String | 泰语分类名称           |
| name_pt    | String | 葡萄牙语分类名称       |
| name_ja    | String | 日语分类名称           |
| name_id    | String | 印尼语分类名称         |
| name_en    | String | 英语分类名称           |
| child_node | Object | 子分类信息（嵌套结构） |

##### 店铺信息对象字段 (shop_info)

| 字段名        | 类型    | 描述                 |
| ------------- | ------- | -------------------- |
| image         | String  | 店铺图片 URL         |
| name          | String  | 店铺名称             |
| avg_price     | Double  | 平均价格（本地货币） |
| currency      | String  | 货币类型             |
| id            | String  | 店铺 ID              |
| goods_count   | Long    | 商品数量             |
| region        | Array   | 店铺投放地区列表     |
| avg_price_usd | Double  | 平均美元价格         |
| sales_volume  | Long    | 店铺销量             |
| is_managed    | Boolean | 是否全托管店铺       |

##### 销售趋势数据对象字段 (sales_trend_data)

| 字段名       | 类型 | 描述       |
| ------------ | ---- | ---------- |
| day          | Long | 日期时间戳 |
| sales_volume | Long | 当日销售值 |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1729588788549551549",
    "image": "https://cdn-product.pipispy.com/xd_7bc3ff56783ac45048d903b0d414c7fc.jpg",
    "title": "[TANPA LEM] Dream Lashes L4 Sunflower Bulu Mata Palsu Tanpa Lem + FREE Tweezers",
    "landing_page": "https://shop.tiktok.com/view/product/1729588788549551549?region=ID",
    "desc": "✨ HALO DREAMERS! ✨\n\nSpecial untuk kalian : Beli 1 kotak bulu mata langsung mendapatkan bonus Twizzer...",
    "currency": "IDR",
    "price": 79900.0,
    "price_usd": 4.91,
    "sales_volume": 7606,
    "commission_rate": 0.1,
    "sales_trend": 1,
    "sales_trend_data": [
      {
        "day": 1744214400,
        "sales_volume": 9
      },
      {
        "day": 1744300800,
        "sales_volume": 10
      }
    ],
    "score": 4.7,
    "gmv": 6.077194e8,
    "gmv_usd": 37345.46,
    "delivery": "local",
    "is_in_marketplace": true,
    "is_managed": true,
    "person_count": 5,
    "video_count": 17,
    "categorize": {
      "_id": "601450",
      "parent_id": "0",
      "name_zh": "美妆个护",
      "name_vi": "Chăm sóc sắc đẹp & Chăm sóc cá nhân",
      "name_th": "ความงามและของใช้ส่วนตัว",
      "name_pt": "Beauty & Personal Care",
      "name_ja": "Beauty & Personal Care",
      "name_id": "Perawatan & Kecantikan",
      "name_en": "Beauty & Personal Care",
      "child_node": {
        "_id": "848648",
        "parent_id": "601450",
        "name_zh": "美妆",
        "name_vi": "Trang điểm",
        "name_th": "เครื่องสำอาง",
        "name_pt": "Makeup",
        "name_ja": "Makeup",
        "name_id": "Makeup",
        "name_en": "Makeup",
        "child_node": {
          "_id": "824720",
          "parent_id": "848648",
          "name_zh": "假睫毛与胶水",
          "name_vi": "Mí mắt giả & keo",
          "name_th": "ขนตาปลอมและกาว",
          "name_pt": "False Eyelashes & Adhesives",
          "name_ja": "False Eyelashes & Adhesives",
          "name_id": "Bulu Mata Palsu & Perekat",
          "name_en": "False Eyelashes & Adhesives"
        }
      }
    },
    "region": "ID",
    "play_count": 38217272,
    "like_count": 207307,
    "like_rate": 0.0054,
    "comment_count": 1348,
    "product_comment": 1013,
    "share_count": 17907,
    "found_time": 1718850206,
    "last_found_time": 1752103443,
    "insert_time": 1727694776,
    "update_time": 1752115234,
    "min_cpm": 15669.08,
    "max_cpm": 63822.84,
    "shop_info": {
      "image": "https://cdn-product.pipispy.com/xd_cdca8fe4b5f6023d2f07.jpg",
      "name": "Dream Lashes",
      "avg_price": 75704.13,
      "currency": "IDR",
      "id": "7494784729622284733",
      "goods_count": 16,
      "region": ["ID"],
      "avg_price_usd": 4.67,
      "sales_volume": 183793,
      "is_managed": true
    },
    "is_collection": false,
    "root_path": "shop.tiktok.com",
    "image_list": [
      "https://cdn-product.pipispy.com/xd_7bc3ff56783ac45048d903b0d414c7fc.jpg",
      "https://cdn-product.pipispy.com/xd_f6b642263b1c8483a639f246499cd24d.jpg",
      "https://cdn-product.pipispy.com/xd_d706e48a17564cf167e8cc47fd2812a1.jpg"
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}
```

### 错误码

| 错误码 | 描述                        |
| ------ | --------------------------- |
| 200    | 成功                        |
| 400    | 请求参数错误，如缺少商品 ID |
| 404    | 商品不存在                  |
| 500    | 服务器内部错误              |