# 创作者TTS-添加橱窗商品

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[创作者TTS-添加橱窗商品](/openapi/add-showcase-products)
- 完整接口约束：[JSON Schema](/openapi/operations/addTikTokShowcaseProducts.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## POST /v1/creator/tiktokshop/product/addToShowcase

接口标识：`addTikTokShowcaseProducts`

将 TikTok Shop 商品添加到创作者展示橱窗。可按商品 ID 批量添加，或通过单个商品链接添加。

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `id` | body | integer | 是 | 创作者账号 ID（creator account id） |
| `addType` | body | PRODUCT_ID \| PRODUCT_LINK | 是 | 添加方式 |
| `productIds` | body | string[] | 条件必填 | addType=PRODUCT_ID 时必填，1～20 个商品 ID |
| `productLink` | body | string(uri) | 条件必填 | addType=PRODUCT_LINK 时必填 |

请求格式：`application/json`

### 请求示例：按商品 ID 添加

```json
{
  "id": 12345,
  "addType": "PRODUCT_ID",
  "productIds": [
    "1732280564607717841",
    "1732280564607717842"
  ]
}
```

### 请求示例：按商品链接添加

```json
{
  "id": 12345,
  "addType": "PRODUCT_LINK",
  "productLink": "https://shop.tiktok.com/view/product/1732280564607717841"
}
```

### 成功响应：全部商品添加成功

```json
{
  "code": 0,
  "data": {},
  "message": "success",
  "timestamp": 1786406400000
}
```

### 成功响应：部分商品添加失败

```json
{
  "code": 0,
  "data": {
    "errors": [
      {
        "code": 16001001,
        "message": "Product is unavailable for this creator",
        "detail": {
          "productId": "1732280564607717842"
        }
      }
    ]
  },
  "message": "success",
  "timestamp": 1786406400000
}
```

### 成功响应：创作者授权过期

```json
{
  "code": 40101,
  "data": {},
  "message": "授权过期，请重新授权",
  "timestamp": 1786406400000
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 业务状态码，0 表示请求已处理；仍需检查逐项结果。 |
| `data` | object | 是 | — |
| `data.errors` | object[] | 否 | 逐商品失败信息；全部添加成功时可能为空或省略。 |
| `data.errors[].code` | integer | 否 | — |
| `data.errors[].message` | string | 否 | — |
| `data.errors[].detail` | object | 否 | — |
| `data.errors[].detail.productId` | string | 否 | 添加失败的商品 ID。 |
| `message` | string | 是 | — |
| `timestamp` | integer | 是 | Unix 时间戳，单位毫秒。 |

### 接入说明与限制

- 所需 scope：creator.showcase.write、creator.video.write。
- 一次最多添加 20 个 productId。
- 业务 code=0 时仍需检查 data.errors；存在 errors 表示对应商品添加失败。
- 创作者授权失效时返回业务错误「授权过期，请重新授权」。

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。