makemd/docs/API_Documentations/TikTok_API_Documentation.md

# TikTok API 接口文档

> 基于官方文档整理
> 最后更新: 2026-03-23

---

## 1. TikTok Shop Partner API

### 1.1 获取授权类别资产

**接口信息**
- **接口**: GET /authorization/202405/category_assets
- **版本**: 202405
- **目标合作伙伴**: 所有
- **权限范围**: partner.authorization.info

**功能说明**
获取应用程序授权的业务类别资产列表。在应用程序访问合作伙伴数据之前，需要合作伙伴授权，此访问基于业务类别。使用此API检查当前为应用程序授权的业务类别资产，并获取相应的类别资产密码，用作联盟合作伙伴相关API的输入参数。

**请求头**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| content-type | string | 允许类型: application/json | ✅ 是 |
| x-tts-access-token | string | 来自Get Access Token的合作伙伴access_token值，当user_type = 3时。 | ✅ 是 |

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 每个应用程序都有唯一的密钥。请使用分配给您应用程序的特定密钥。 | ✅ 是 |
| sign | string | 通过gen算法生成的签名。当您向TTS发送API请求时，必须对其进行签名，以便TTS可以识别发送者。 | ✅ 是 |
| timestamp | int | Unix时间戳GMT (UTC+00:00)。此时间戳用于所有API请求。开发人员可以使用此转换为本地时间。 | ✅ 是 |

**响应结构**
| 属性 | 类型 | 说明 |
|------|------|------|
| code | int | API响应中返回的成功或失败状态代码。 |
| message | string | API响应中返回的成功或失败消息。失败原因将在消息中描述。 |
| request_id | string | 请求日志 |
| data | object | 具体返回信息 |

**错误代码**
- 无业务逻辑错误代码

### 1.2 获取访问令牌 (Get Access Token)

**接口信息**
- **接口**: GET /api/v2/token/get
- **主机**: auth.tiktok-shops.com
- **功能**: 获取用户访问令牌

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | Partner Center应用页面中的App key | ✅ 是 |
| app_secret | string | Partner Center应用页面中的App secret | ✅ 是 |
| auth_code | string | 使用授权链接获取的授权代码 | ✅ 是 |
| grant_type | string | 授权令牌类型，仅接受authorized_code | ✅ 是 |

**请求示例**
```
https://auth.tiktok-shops.com/api/v2/token/get?app_key=123abcd  
&app_secret=15abf8a4972afd1f275d5b19bfa9a17e0d142aa7  
&auth_code=TTP_FeBoANmHP3yqdoUI9fZOCw  
&grant_type=authorized_code
```

**响应结构**
| 属性 | 类型 | 说明 |
|------|------|------|
| code | int | 表示请求结果的机器可读响应代码。0表示成功。 |
| message | string | 描述API请求成功或失败的人类可读消息。 |
| request_id | string | 跟踪API请求的ID。 |
| data | object | 响应数据负载。 |
| data.access_token | string | 用于调用TikTok Shop Open API端点的用户访问令牌。在API请求的x-tts-access-token头中传递此值以授权请求。 |
| data.access_token_expire_in | Unix timestamp | 访问令牌的过期时间戳，默认过期时间设置为7天。Unix时间戳表示访问令牌将过期的日期和时间。 |
| data.refresh_token | string | 用于刷新访问令牌的令牌。 |
| data.refresh_token_expire_in | Unix timestamp | 刷新令牌的过期时间戳。Unix时间戳表示刷新令牌将过期的日期和时间。 |
| data.open_id | string | 用于在API调用中识别已授权检索其数据的用户的ID。 |
| data.seller_name | string | 您正在为应用程序授权的卖家名称。 |
| data.seller_base_region | string | 卖家所在的地区。 |
| data.user_type | int | 用户类型，可能的值：0: 卖家, 1: 创作者, 3: 合作伙伴 |
| data.granted_scopes | []string | 应用程序的授权API范围。此字段将返回授权API范围的Scope Key值。 |

**响应示例**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "TTP_Fw8rBwAAAAAkW03FYd09DG-9INtpw361hWthei8S3fHX8iPJ5AUv99fLSCYD9-UucaqxTgNRzKZxi5-tfFMtdWqglEt5_iCk",
    "access_token_expire_in": 1660556783,
    "refresh_token": "TTP_NTUxZTNhYTQ2ZDk2YmRmZWNmYWY2YWY2YzkxNGYwNjQ3YjkzYTllYjA0YmNlMw",
    "refresh_token_expire_in": 1691487031,
    "open_id": "7010736057180325637",
    "seller_name": "Jjj test shop",
    "seller_base_region": "ID",
    "user_type": 0,
    "granted_scopes": [
      "seller.affiliate_collaboration.read",
      "seller.affiliate_collaboration.write"
    ]
  },
  "request_id": "2022080809462301024509910319695C45"
}
```

### 1.3 刷新访问令牌 (Get Refresh Token)

**接口信息**
- **接口**: GET /api/v2/token/refresh
- **主机**: auth.tiktok-shops.com
- **功能**: 刷新访问令牌

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | TikTok Shop Partner Center应用页面中的App key | ✅ 是 |
| app_secret | string | TikTok Shop Partner Center应用页面中的App secret | ✅ 是 |
| refresh_token | string | 在Get Access Token API的响应参数中获得的刷新令牌 | ✅ 是 |
| grant_type | string | 授权令牌类型，仅接受refresh_token | ✅ 是 |

**请求示例**
```
https://auth.tiktok-shops.com/api/v2/token/refresh?app_key=65t6a8e8bfejb  
&app_secret=f4c770e4b45aa62e  
&refresh_token=TTP_EB9rlwAAAADXbnMESTWAZSxIcC-XUA5AyeEOdmGBKY2FiKFYKqON6jco  
&grant_type=refresh_token
```

**响应结构**
与Get Access Token API相同

### 1.4 商品管理API

**1.4.1 获取商品列表**

**接口信息**
- **接口**: GET /product/202405/products
- **版本**: 202405
- **权限范围**: seller.product.read

**功能说明**
获取店铺的商品列表，支持分页和筛选。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| page_size | int | 每页数量，最大100 | ✅ 是 |
| page_no | int | 页码，从1开始 | ✅ 是 |
| status | string | 商品状态：ALL, ONLINE, OFFLINE, PENDING | ❌ 否 |
| product_ids | string | 商品ID列表，逗号分隔 | ❌ 否 |

**响应结构**
| 属性 | 类型 | 说明 |
|------|------|------|
| code | int | 状态码 |
| message | string | 消息 |
| data | object | 数据 |
| data.total | int | 总数量 |
| data.products | array | 商品列表 |

**1.4.2 获取商品详情**

**接口信息**
- **接口**: GET /product/202405/product/detail
- **版本**: 202405
- **权限范围**: seller.product.read

**功能说明**
获取单个商品的详细信息。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| product_id | string | 商品ID | ✅ 是 |

**1.4.3 创建商品**

**接口信息**
- **接口**: POST /product/202405/product/create
- **版本**: 202405
- **权限范围**: seller.product.write

**功能说明**
创建新商品。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| product_name | string | 商品名称 | ✅ 是 |
| category_id | string | 分类ID | ✅ 是 |
| price | decimal | 价格 | ✅ 是 |
| stock | int | 库存 | ✅ 是 |
| description | string | 商品描述 | ✅ 是 |
| images | array | 图片URL列表 | ✅ 是 |
| skus | array | SKU信息 | ❌ 否 |

**1.4.4 更新商品**

**接口信息**
- **接口**: POST /product/202405/product/update
- **版本**: 202405
- **权限范围**: seller.product.write

**功能说明**
更新商品信息。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| product_id | string | 商品ID | ✅ 是 |
| product_name | string | 商品名称 | ❌ 否 |
| price | decimal | 价格 | ❌ 否 |
| stock | int | 库存 | ❌ 否 |
| description | string | 商品描述 | ❌ 否 |

**1.4.5 上下架商品**

**接口信息**
- **接口**: POST /product/202405/product/status/update
- **版本**: 202405
- **权限范围**: seller.product.write

**功能说明**
修改商品状态（上架/下架）。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| product_ids | array | 商品ID列表 | ✅ 是 |
| status | string | 状态：ONLINE, OFFLINE | ✅ 是 |

### 1.5 订单管理API

**1.5.1 获取订单列表**

**接口信息**
- **接口**: GET /order/202405/orders
- **版本**: 202405
- **权限范围**: seller.order.read

**功能说明**
获取店铺的订单列表，支持分页和筛选。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| page_size | int | 每页数量，最大100 | ✅ 是 |
| page_no | int | 页码，从1开始 | ✅ 是 |
| order_status | string | 订单状态 | ❌ 否 |
| start_time | string | 开始时间，格式：2024-01-01 00:00:00 | ❌ 否 |
| end_time | string | 结束时间，格式：2024-01-01 23:59:59 | ❌ 否 |

**1.5.2 获取订单详情**

**接口信息**
- **接口**: GET /order/202405/order/detail
- **版本**: 202405
- **权限范围**: seller.order.read

**功能说明**
获取单个订单的详细信息。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| order_id | string | 订单ID | ✅ 是 |

**1.5.3 发货**

**接口信息**
- **接口**: POST /order/202405/order/ship
- **版本**: 202405
- **权限范围**: seller.order.write

**功能说明**
订单发货。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| order_id | string | 订单ID | ✅ 是 |
| logistics_company | string | 物流公司 | ✅ 是 |
| tracking_number | string | 物流单号 | ✅ 是 |

**1.5.4 取消订单**

**接口信息**
- **接口**: POST /order/202405/order/cancel
- **版本**: 202405
- **权限范围**: seller.order.write

**功能说明**
取消订单。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| order_id | string | 订单ID | ✅ 是 |
| cancel_reason | string | 取消原因 | ✅ 是 |

### 1.6 财务管理API

**1.6.1 获取账户余额**

**接口信息**
- **接口**: GET /finance/202405/balance
- **版本**: 202405
- **权限范围**: seller.finance.read

**功能说明**
获取店铺的账户余额。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |

**1.6.2 获取交易记录**

**接口信息**
- **接口**: GET /finance/202405/transactions
- **版本**: 202405
- **权限范围**: seller.finance.read

**功能说明**
获取店铺的交易记录。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| page_size | int | 每页数量 | ✅ 是 |
| page_no | int | 页码 | ✅ 是 |
| start_date | string | 开始日期，格式：2024-01-01 | ❌ 否 |
| end_date | string | 结束日期，格式：2024-01-31 | ❌ 否 |
| transaction_type | string | 交易类型 | ❌ 否 |

**1.6.3 获取结算单**

**接口信息**
- **接口**: GET /finance/202405/settlements
- **版本**: 202405
- **权限范围**: seller.finance.read

**功能说明**
获取店铺的结算单列表。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| page_size | int | 每页数量 | ✅ 是 |
| page_no | int | 页码 | ✅ 是 |
| start_date | string | 开始日期 | ❌ 否 |
| end_date | string | 结束日期 | ❌ 否 |

**1.6.4 申请提现**

**接口信息**
- **接口**: POST /finance/202405/withdraw
- **版本**: 202405
- **权限范围**: seller.finance.write

**功能说明**
申请提现。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| amount | decimal | 提现金额 | ✅ 是 |
| bank_account_id | string | 银行账户ID | ✅ 是 |

### 1.7 库存管理API

**1.7.1 获取库存信息**

**接口信息**
- **接口**: GET /inventory/202405/inventory
- **版本**: 202405
- **权限范围**: seller.inventory.read

**功能说明**
获取商品库存信息。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| product_ids | string | 商品ID列表，逗号分隔 | ❌ 否 |

**1.7.2 更新库存**

**接口信息**
- **接口**: POST /inventory/202405/inventory/update
- **版本**: 202405
- **权限范围**: seller.inventory.write

**功能说明**
更新商品库存。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| inventory_updates | array | 库存更新信息 | ✅ 是 |

**1.7.3 批量更新库存**

**接口信息**
- **接口**: POST /inventory/202405/inventory/batch/update
- **版本**: 202405
- **权限范围**: seller.inventory.write

**功能说明**
批量更新多个商品的库存。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| inventory_updates | array | 库存更新信息列表 | ✅ 是 |

### 1.8 物流管理API

**1.8.1 获取物流信息**

**接口信息**
- **接口**: GET /logistics/202405/logistics/tracking
- **版本**: 202405
- **权限范围**: seller.logistics.read

**功能说明**
获取物流跟踪信息。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |
| tracking_number | string | 物流单号 | ✅ 是 |
| logistics_company | string | 物流公司 | ✅ 是 |

**1.8.2 获取物流公司列表**

**接口信息**
- **接口**: GET /logistics/202405/logistics/companies
- **版本**: 202405
- **权限范围**: seller.logistics.read

**功能说明**
获取可用的物流公司列表。

**请求参数**
| 属性 | 类型 | 说明 | 是否必填 |
|------|------|------|----------|
| app_key | string | 应用密钥 | ✅ 是 |
| sign | string | 签名 | ✅ 是 |
| timestamp | int | 时间戳 | ✅ 是 |

---

## 2. 授权流程

### 2.1 权限分析

TikTok Shop API 授权主要分为三类：

1. **达人授权（Creator Authorization）**
2. **合作伙伴授权（Partner Authorization）**
3. **商家授权（Seller Authorization）**

#### 2.1.1 达人授权（Creator Authorization）

达人授权主要用于 **达人橱窗商品管理、联盟推广、推广链接生成等功能**。

| API Name | 中文名称 | Scope Key | 功能说明 |
|---|---|---|---|
| Affiliate Information | 达人联盟信息 | creator.affiliate.info | 获取达人联盟账户相关信息 |
| Manage Affiliate Tracking Links | 管理达人推广追踪链接 | creator.affiliate.link.write | 创建和管理达人推广追踪链接 |
| Read Affiliate Share Link | 读取达人分享推广链接 | creator.affiliate.share_link.read | 获取达人分享用的推广链接 |
| Read Creator Affiliate Collaborations | 读取达人联盟合作 | creator.affiliate_collaboration.read | 查询达人参与的联盟合作信息 |
| Read Showcase Products | 读取达人橱窗商品 | creator.showcase.read | 获取达人橱窗中的商品 |
| Manage Showcase Products | 管理达人橱窗商品 | creator.showcase.write | 添加、删除或管理橱窗商品 |

达人授权核心能力：
- 橱窗商品管理
- 商品推广链接生成
- 联盟合作查询

#### 2.1.2 合作伙伴授权（Partner Authorization）

合作伙伴授权主要用于 **TAP（TikTok Affiliate Partner）联盟营销活动管理**，通常用于：
- MCN机构
- 服务商
- 代理商系统

| API Name | 中文名称 | Scope Key | 功能说明 |
|---|---|---|---|
| Manage Affiliate Partner Campaigns | 管理联盟营销活动 | partner.tap_campaign.write | 创建和管理联盟营销活动 |
| Read Affiliate Partner Campaigns | 读取联盟营销活动 | partner.tap_campaign.read | 查询联盟营销活动信息 |
| Manage Affiliate Partner Campaign Products | 管理活动商品 | partner.tap_campaign.product.write | 管理营销活动中的商品 |
| Manage Product Promote Links | 管理商品推广链接 | partner.tap_campaign.link.write | 为商品生成推广链接 |
| Partner Authorized Information | 合作伙伴授权信息 | partner.authorization.info | 获取授权类目及授权信息 |

合作伙伴授权核心能力：
- 联盟营销活动管理
- 推广商品管理
- 推广链接生成

#### 2.1.3 商家授权（Seller Authorization）

商家授权权限最多，涵盖 **店铺运营的全部核心能力**：

##### 2.1.3.1 联盟相关权限

| API Name | 中文名称 | Scope Key | 功能说明 |
|---|---|---|---|
| Manage Seller Affiliate Collaboration | 管理商家联盟合作 | seller.affiliate_collaboration.write | 创建和管理商家联盟合作 |
| Read Seller Affiliate Collaboration | 读取商家联盟合作 | seller.affiliate_collaboration.read | 查询商家联盟合作信息 |
| Manage Affiliate Messages | 管理联盟达人消息 | seller.affiliate_messages.write | 向联盟达人发送或读取消息 |
| Read Creator Marketplace | 读取达人市场 | seller.creator_marketplace.read | 搜索和筛选达人 |

##### 2.1.3.2 数据分析权限

| API Name | 中文名称 | Scope Key | 功能说明 |
|---|---|---|---|
| TikTok Shop Analytics | 店铺数据分析 | data.shop_analytics.public.read | 获取GMV、订单数、访客数等数据 |

#### 2.1.4 权限能力矩阵

| 功能 | 达人 | 合作伙伴 | 商家 |
|---|----|------|----|
| 橱窗商品管理 | ✔  | ✖    | ✖  |
| 联盟合作 | ✔  | ✔    | ✔  |
| 推广链接 | ✔  | ✔    | ✔  |
| 营销活动 Campaign | ✖  | ✔    | ✖  |
| 商品管理 | ✖  | ✔    | ✔  |
| 订单管理 | ✖  | ✖    | ✔  |
| 物流管理 | ✖  | ✖    | ✔  |
| 退货退款 | ✖  | ✖    | ✔  |
| 财务信息 | ✖  | ✖    | ✔  |
| 数据分析 | ✖  | ✖    | ✔  |

#### 2.1.5 总结

TikTok Shop API 实际上分为 **三套不同的权限体系**：

| API体系 | 授权主体 | 管理对象 |
|---|------|---|
| Creator API | 达人   | 橱窗商品与推广 |
| Partner API | 合作伙伴 | 联盟营销活动 |
| Seller API | 商家   | 整个店铺运营 |

### 2.2 前置条件

**对于自定义应用程序**：
- 应用程序已启用至少一个API范围用户：卖家、创作者和/或合作伙伴
- 应用程序通过"注册审核"

**对于公共应用程序**：
- 应用程序已启用至少一个API范围用户：卖家、创作者和/或合作伙伴
- 应用程序通过"注册审核"
- 应用程序通过"USDS/OPIS审核"（仅针对美国目标市场）
- 应用程序通过"Listing Review"
- 应用程序通过"App review"
- 应用程序通过"Beta Testing"（仅针对连接器应用程序）

### 2.2 启用API范围

在开发应用程序之前，开发人员应根据应用程序的业务类型启用或申请必要的API范围。

> 注意：启用不必要的范围可能会导致应用程序审核时间延长和用户授权率降低。

### 2.3 获取授权链接

通过在应用程序的Authorization部分点击Copy authorization link生成授权链接：

> 注意：如果应用程序处于开发阶段，Copy authorization link按钮将不可见。

**授权链接格式**：
- US: `https://services.tiktokshops.us/open/authorize?service_id=7369437808455026474`
- 世界其他地区: `https://services.tiktokshop.com/open/authorize?service_id=7431458374265161478`

应在授权链接中添加state参数以提高安全性。

### 2.4 用户授权流程

1. 用户访问授权链接
2. 用户接受或拒绝授权请求
3. 如果用户接受授权请求，他们将被重定向到Redirect URL，该URL还将包含作为参数的临时代码。此代码将用作获取访问令牌时的auth_code。
4. 重定向URL和auth_code示例：`{redirect_url}?code=FeBoANmHP3yqdoUI9fZOCw&state={state}`
5. 如果用户拒绝授权请求，他们仍将被重定向到Redirect URL，但code将为null：`code=null&error=auth_denied`

> 重要：auth_code在30分钟后过期，只能使用一次。

---

## 3. TikTok Business API

> 注意: 由于官方文档访问限制，以下内容基于公开信息整理

### 3.1 API结构

TikTok Business API提供了以下主要功能模块：

| 模块 | 功能 | 说明 |
|------|------|------|
| 广告管理 | 创建、管理广告活动 | 支持广告系列、广告组、广告的全生命周期管理 |
| 受众管理 | 管理目标受众 | 支持自定义受众、相似受众等 |
| 转化追踪 | 追踪广告转化 | 支持像素追踪、事件追踪等 |
| 创意管理 | 管理广告创意 | 支持图片、视频等创意素材管理 |
| 洞察分析 | 广告效果分析 | 提供详细的广告数据报告 |
| 账户管理 | 管理广告账户 | 支持账户设置、权限管理等 |

### 3.2 认证方式

TikTok Business API使用OAuth 2.0认证机制：

1. **获取授权码**
2. **获取访问令牌**
3. **使用访问令牌调用API**
4. **刷新访问令牌**

### 3.3 基本请求结构

```
GET /api/v1/{endpoint}
Host: business-api.tiktok.com
Authorization: Bearer {access_token}
Content-Type: application/json
```

### 3.4 常用端点

| 端点 | 功能 | 方法 |
|------|------|------|
| /campaigns | 广告系列管理 | GET, POST, PUT, DELETE |
| /adgroups | 广告组管理 | GET, POST, PUT, DELETE |
| /ads | 广告管理 | GET, POST, PUT, DELETE |
| /audiences | 受众管理 | GET, POST, PUT, DELETE |
| /insights | 数据洞察 | GET |
| /creatives | 创意管理 | GET, POST |
| /gmv_max | GMV Max管理 | GET, POST, PUT, DELETE |

### 3.5 GMV Max API (2025年新增)

**概述**：
GMV Max是TikTok在2025年推出的AI自动化广告解决方案，旨在最大化GMV（总交易额）。自2025年7月起，GMV Max成为Shop Ads唯一支持的广告类型。

**两种类型**：
1. **Product GMV Max** - 商品推广
2. **LIVE GMV Max** - 直播推广

**核心特性**：
- 基于信号协同的增强型投放
- 同时利用自然流量和付费流量信号
- AI自动化优化，无需手动调整
- 以总交易额最大化为目标

**API端点**：

| 端点 | 功能 | 方法 | 说明 |
|------|------|------|------|
| /gmv_max/campaigns | GMV Max系列管理 | GET, POST, PUT, DELETE | 创建和管理GMV Max广告系列 |
| /gmv_max/products | GMV Max商品管理 | GET, POST | 添加和管理推广商品 |
| /gmv_max/live | LIVE GMV Max管理 | GET, POST | 管理直播推广 |
| /gmv_max/insights | GMV Max数据洞察 | GET | 获取GMV Max效果报告 |

**创建GMV Max广告系列示例**：

```json
{
  "campaign_name": "Product GMV Max Campaign",
  "campaign_type": "product_gmv_max",
  "budget": {
    "daily_budget": 100.00,
    "currency": "USD"
  },
  "optimization_goal": "maximize_gmv",
  "target_audience": {
    "age_groups": ["18-24", "25-34", "35-44"],
    "genders": ["male", "female"],
    "interests": ["fashion", "electronics"]
  },
  "products": [
    {
      "product_id": "123456789",
      "bid_strategy": "auto"
    }
  ]
}
```

**注意事项**：
- 2025年6月起，新店铺无法手动创建传统Ads
- GMV Max需要通过TikTok Ads Manager API接入
- 支持在Seller Center和广告管理平台查看报告
- 需要适配新的自动化投放逻辑

---

## 4. API使用指南

### 4.1 前置条件

1. **注册TikTok Shop Partner账户**
2. **创建应用程序**
3. **获取应用程序密钥**
4. **配置回调URL**
5. **获取访问令牌**

### 4.2 TikTok Shop Partner注册流程

**注册地址**：[TikTok Shop Partner Center](https://partner.tiktokshop.com/)

**注册资格**：
- 企业开发者：需要提供企业营业执照、税务登记证等
- 个人开发者：需要提供个人身份证明
- 必须具备电子商务相关业务经验

**所需材料**：
1. 企业营业执照（企业开发者）
2. 税务登记证（企业开发者）
3. 法人身份证明
4. 联系方式（邮箱、电话）
5. 公司银行账户信息
6. 业务计划书（描述应用程序的功能和用途）

**注册步骤**：
1. 访问TikTok Shop Partner Center注册地址
2. 点击"Sign Up"按钮，创建合作伙伴账号
3. 填写注册信息，上传所需材料
4. 等待平台审核（通常1-3个工作日）
5. 审核通过后，登录Partner Center控制台
6. 创建应用，获取App Key和App Secret
7. 设置应用回调地址
8. 配置应用权限范围
9. 获取测试环境访问权限

**注意事项**：
- 确保提供真实有效的信息
- 保护好App Key和App Secret，避免泄露
- 遵守TikTok的使用条款和限制
- 定期更新API密钥以保证安全
- 如遇到注册问题，可联系TikTok Shop Partner支持

### 4.3 请求签名

对于TikTok Shop API，需要使用以下步骤生成签名：

1. 按字典顺序排序所有请求参数
2. 拼接参数名和参数值
3. 添加app_secret
4. 使用MD5或SHA256算法生成签名

### 4.4 错误处理

| 错误代码 | 说明 | 解决方案 |
|----------|------|----------|
| 400 | 请求参数错误 | 检查参数格式和必填项 |
| 401 | 未授权 | 检查访问令牌是否有效 |
| 403 | 权限不足 | 检查权限范围是否正确 |
| 429 | 请求频率过高 | 实现请求限流 |
| 500 | 服务器内部错误 | 稍后重试 |

### 4.5 最佳实践

1. **使用HTTPS**
2. **实现请求重试机制**
3. **设置合理的超时时间**
4. **缓存访问令牌**
5. **监控API使用情况**
6. **遵循TikTok API使用政策**

---

## 5. 接口调用示例

### 5.1 获取授权类别资产

**请求示例**

```bash
curl -X GET "https://partner.tiktokshop.com/api/authorization/202405/category_assets" \
  -H "content-type: application/json" \
  -H "x-tts-access-token: YOUR_ACCESS_TOKEN" \
  -d "{
    \"app_key\": \"YOUR_APP_KEY\",
    \"sign\": \"YOUR_SIGNATURE\",
    \"timestamp\": 1620000000
  }"
```

**响应示例**

```json
{
  "code": 0,
  "message": "success",
  "request_id": "20240501123456789",
  "data": {
    "category_assets": [
      {
        "category_id": "123",
        "category_name": "Electronics",
        "asset_cipher": "abcdef123456",
        "status": "authorized"
      }
    ]
  }
}
```

### 5.2 获取商品列表

**请求示例**

```bash
curl -X GET "https://partner.tiktokshop.com/api/product/202405/products" \
  -H "content-type: application/json" \
  -H "x-tts-access-token: YOUR_ACCESS_TOKEN" \
  -d "{
    \"app_key\": \"YOUR_APP_KEY\",
    \"sign\": \"YOUR_SIGNATURE\",
    \"timestamp\": 1620000000,
    \"page_size\": 20,
    \"page_no\": 1,
    \"status\": \"ONLINE"
  }"
```

### 5.3 获取订单列表

**请求示例**

```bash
curl -X GET "https://partner.tiktokshop.com/api/order/202405/orders" \
  -H "content-type: application/json" \
  -H "x-tts-access-token: YOUR_ACCESS_TOKEN" \
  -d "{
    \"app_key\": \"YOUR_APP_KEY\",
    \"sign\": \"YOUR_SIGNATURE\",
    \"timestamp\": 1620000000,
    \"page_size\": 20,
    \"page_no\": 1,
    \"start_time\": \"2024-01-01 00:00:00\",
    \"end_time\": \"2024-01-31 23:59:59"
  }"
```

### 5.4 获取账户余额

**请求示例**

```bash
curl -X GET "https://partner.tiktokshop.com/api/finance/202405/balance" \
  -H "content-type: application/json" \
  -H "x-tts-access-token: YOUR_ACCESS_TOKEN" \
  -d "{
    \"app_key\": \"YOUR_APP_KEY\",
    \"sign\": \"YOUR_SIGNATURE\",
    \"timestamp\": 1620000000
  }"
```

### 5.5 Business API示例

**获取广告系列列表**

```bash
curl -X GET "https://business-api.tiktok.com/open_api/v1.3/campaigns/get/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"advertiser_id\": \"YOUR_ADVERTISER_ID\",
    \"page\": 1,
    \"page_size\": 10
  }"
```

### 5.6 实际使用场景示例

#### 5.6.1 批量上传商品场景

**Python示例代码**

```python
import requests
import json
import hashlib
import time

def generate_signature(params, app_secret):
    # 按字典顺序排序参数
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    # 拼接参数
    sign_string = app_secret
    for key, value in sorted_params:
        sign_string += f"{key}{value}"
    sign_string += app_secret
    # 生成MD5签名
    signature = hashlib.md5(sign_string.encode()).hexdigest().upper()
    return signature

def batch_create_products(app_key, app_secret, access_token, products):
    results = []
    for product in products:
        timestamp = int(time.time())
        params = {
            "app_key": app_key,
            "timestamp": timestamp,
            "product_name": product["name"],
            "category_id": product["category_id"],
            "price": product["price"],
            "stock": product["stock"],
            "description": product["description"],
            "images": product["images"]
        }
        
        # 生成签名
        params["sign"] = generate_signature(params, app_secret)
        
        # 发送请求
        url = "https://partner.tiktokshop.com/api/product/202405/product/create"
        headers = {
            "content-type": "application/json",
            "x-tts-access-token": access_token
        }
        
        response = requests.post(url, json=params, headers=headers)
        results.append({
            "product": product["name"],
            "response": response.json()
        })
        
        # 避免请求频率过高
        time.sleep(1)
    
    return results

# 示例使用
app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
access_token = "YOUR_ACCESS_TOKEN"

products = [
    {
        "name": "Smartphone X",
        "category_id": "100001",
        "price": 999.99,
        "stock": 100,
        "description": "Latest smartphone with advanced features",
        "images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
    },
    {
        "name": "Wireless Earbuds",
        "category_id": "100002",
        "price": 199.99,
        "stock": 200,
        "description": "High-quality wireless earbuds with noise cancellation",
        "images": ["https://example.com/earbud1.jpg", "https://example.com/earbud2.jpg"]
    }
]

results = batch_create_products(app_key, app_secret, access_token, products)
print(json.dumps(results, indent=2))
```

#### 5.6.2 自动处理订单场景

**Python示例代码**

```python
import requests
import json
import hashlib
import time

def generate_signature(params, app_secret):
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    sign_string = app_secret
    for key, value in sorted_params:
        sign_string += f"{key}{value}"
    sign_string += app_secret
    signature = hashlib.md5(sign_string.encode()).hexdigest().upper()
    return signature

def get_orders(app_key, app_secret, access_token, start_time, end_time):
    timestamp = int(time.time())
    params = {
        "app_key": app_key,
        "timestamp": timestamp,
        "page_size": 100,
        "page_no": 1,
        "start_time": start_time,
        "end_time": end_time
    }
    params["sign"] = generate_signature(params, app_secret)
    
    url = "https://partner.tiktokshop.com/api/order/202405/orders"
    headers = {
        "content-type": "application/json",
        "x-tts-access-token": access_token
    }
    
    response = requests.get(url, json=params, headers=headers)
    return response.json()

def ship_order(app_key, app_secret, access_token, order_id, logistics_company, tracking_number):
    timestamp = int(time.time())
    params = {
        "app_key": app_key,
        "timestamp": timestamp,
        "order_id": order_id,
        "logistics_company": logistics_company,
        "tracking_number": tracking_number
    }
    params["sign"] = generate_signature(params, app_secret)
    
    url = "https://partner.tiktokshop.com/api/order/202405/order/ship"
    headers = {
        "content-type": "application/json",
        "x-tts-access-token": access_token
    }
    
    response = requests.post(url, json=params, headers=headers)
    return response.json()

# 示例使用：自动处理待发货订单
app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
access_token = "YOUR_ACCESS_TOKEN"

# 获取今天的订单
import datetime
today = datetime.datetime.now().strftime("%Y-%m-%d")
start_time = f"{today} 00:00:00"
end_time = f"{today} 23:59:59"

orders_response = get_orders(app_key, app_secret, access_token, start_time, end_time)

if orders_response.get("code") == 0:
    orders = orders_response.get("data", {}).get("orders", [])
    for order in orders:
        order_id = order.get("order_id")
        order_status = order.get("order_status")
        
        # 处理待发货订单
        if order_status == "PENDING_SHIPMENT":
            # 模拟物流信息
            logistics_company = "SF Express"
            tracking_number = f"SF{int(time.time())}"
            
            # 发货
            ship_response = ship_order(app_key, app_secret, access_token, order_id, logistics_company, tracking_number)
            print(f"Order {order_id} shipped: {ship_response.get('message')}")
```

#### 5.6.3 实时库存同步场景

**Python示例代码**

```python
import requests
import json
import hashlib
import time

def generate_signature(params, app_secret):
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    sign_string = app_secret
    for key, value in sorted_params:
        sign_string += f"{key}{value}"
    sign_string += app_secret
    signature = hashlib.md5(sign_string.encode()).hexdigest().upper()
    return signature

def update_inventory(app_key, app_secret, access_token, product_id, new_stock):
    timestamp = int(time.time())
    params = {
        "app_key": app_key,
        "timestamp": timestamp,
        "inventory_updates": [{
            "product_id": product_id,
            "stock": new_stock
        }]
    }
    params["sign"] = generate_signature(params, app_secret)
    
    url = "https://partner.tiktokshop.com/api/inventory/202405/inventory/update"
    headers = {
        "content-type": "application/json",
        "x-tts-access-token": access_token
    }
    
    response = requests.post(url, json=params, headers=headers)
    return response.json()

# 示例使用：同步库存
app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
access_token = "YOUR_ACCESS_TOKEN"

# 模拟从ERP系统获取的库存数据
inventory_data = [
    {"product_id": "123456", "stock": 50},
    {"product_id": "789012", "stock": 120},
    {"product_id": "345678", "stock": 0}
]

for item in inventory_data:
    response = update_inventory(app_key, app_secret, access_token, item["product_id"], item["stock"])
    print(f"Updated inventory for product {item['product_id']}: {response.get('message')}")
    time.sleep(0.5)  # 避免请求频率过高
```

---

## 6. 接口整理总结

### 6.1 TikTok Shop Partner API

**认证相关**
| 接口 | 方法 | 版本 | 功能 |
|------|------|------|------|
| /api/v2/token/get | GET | v2 | 获取访问令牌 |
| /api/v2/token/refresh | GET | v2 | 刷新访问令牌 |
| /authorization/202405/category_assets | GET | 202405 | 获取授权类别资产 |

**商品管理**
| 接口 | 方法 | 版本 | 功能 |
|------|------|------|------|
| /product/202405/products | GET | 202405 | 获取商品列表 |
| /product/202405/product/detail | GET | 202405 | 获取商品详情 |
| /product/202405/product/create | POST | 202405 | 创建商品 |
| /product/202405/product/update | POST | 202405 | 更新商品 |
| /product/202405/product/status/update | POST | 202405 | 上下架商品 |

**订单管理**
| 接口 | 方法 | 版本 | 功能 |
|------|------|------|------|
| /order/202405/orders | GET | 202405 | 获取订单列表 |
| /order/202405/order/detail | GET | 202405 | 获取订单详情 |
| /order/202405/order/ship | POST | 202405 | 发货 |
| /order/202405/order/cancel | POST | 202405 | 取消订单 |

**财务管理**
| 接口 | 方法 | 版本 | 功能 |
|------|------|------|------|
| /finance/202405/balance | GET | 202405 | 获取账户余额 |
| /finance/202405/transactions | GET | 202405 | 获取交易记录 |
| /finance/202405/settlements | GET | 202405 | 获取结算单 |
| /finance/202405/withdraw | POST | 202405 | 申请提现 |

**库存管理**
| 接口 | 方法 | 版本 | 功能 |
|------|------|------|------|
| /inventory/202405/inventory | GET | 202405 | 获取库存信息 |
| /inventory/202405/inventory/update | POST | 202405 | 更新库存 |
| /inventory/202405/inventory/batch/update | POST | 202405 | 批量更新库存 |

**物流管理**
| 接口 | 方法 | 版本 | 功能 |
|------|------|------|------|
| /logistics/202405/logistics/tracking | GET | 202405 | 获取物流信息 |
| /logistics/202405/logistics/companies | GET | 202405 | 获取物流公司列表 |

### 6.2 TikTok Business API (常见接口)
| 模块 | 接口 | 方法 | 功能 |
|------|------|------|------|
| 广告管理 | /campaigns | GET, POST, PUT, DELETE | 广告系列管理 |
| 广告管理 | /adgroups | GET, POST, PUT, DELETE | 广告组管理 |
| 广告管理 | /ads | GET, POST, PUT, DELETE | 广告管理 |
| 受众管理 | /audiences | GET, POST, PUT, DELETE | 受众管理 |
| 数据洞察 | /insights | GET | 广告效果分析 |
| 创意管理 | /creatives | GET, POST | 创意管理 |

---

## 7. 注意事项

1. **API版本控制**：TikTok API会定期更新，注意使用最新版本
2. **速率限制**：遵循TikTok的API调用频率限制
3. **权限管理**：确保应用程序具有必要的权限
4. **数据安全**：保护用户数据和API密钥
5. **合规性**：遵守TikTok的API使用条款和隐私政策
6. **错误处理**：实现完善的错误处理机制
7. **监控**：监控API调用状态和性能
8. **文档更新**：定期查看官方文档获取最新信息

---

## 8. 附录

### 8.1 授权链接格式

- **美国**：`https://services.tiktokshops.us/open/authorize?service_id=7369437808455026474`
- **世界其他地区**：`https://services.tiktokshop.com/open/authorize?service_id=7431458374265161478`

### 8.2 用户类型

| 用户类型 | 描述 |
|----------|------|
| 0 | 卖家 |
| 1 | 创作者 |
| 3 | 合作伙伴 |

### 8.3 权限范围

| 权限范围 | 描述 |
|----------|------|
| seller.product.read | 商品读取权限 |
| seller.product.write | 商品写入权限 |
| seller.order.read | 订单读取权限 |
| seller.order.write | 订单写入权限 |
| seller.finance.read | 财务读取权限 |
| seller.finance.write | 财务写入权限 |
| seller.inventory.read | 库存读取权限 |
| seller.inventory.write | 库存写入权限 |
| seller.logistics.read | 物流读取权限 |
| seller.logistics.write | 物流写入权限 |

### 8.4 参考文档

- [TikTok Shop Partner Center](https://partner.tiktokshop.com/docv2)
- [TikTok Business API](https://business-api.tiktok.com/portal/docs)

---

*文档基于TikTok官方API文档整理，如有更新请参考官方文档。*