# TikTok Shop 管家 GA SOP — TikTok 电商运营能力接入指南

> 适用：GA 作为电商管家，需对 TikTok Shop 商家/达人/消费者场景提供运营、查询、自动化支持。
> 本 SOP 覆盖 TikTok Shop 开放平台 API 的核心能力，用于商品、订单、物流、达人、直播五大场景。

---

## 一、平台概览

| 维度 | TikTok Shop |
|------|-------------|
| 官网 | https://seller.tiktokglobalshop.com |
| API 文档 | https://partner.tiktokglobalshop.com/doc |
| 认证方式 | OAuth 2.0 / Access Token |
| 沙箱 | https://sandbox-xt.tiktok.com |
| 主要市场 | 英国、美国、东南亚（泰国/越南/马来/菲律宾/印尼）、沙特 |

### API Base URL
| 市场 | Base URL |
|------|---------|
| 全球（除印尼） | https://open.tiktokglobalshop.com |
| 印尼 | https://open.tiktokglobalshop.co.id |

### 授权流程
```
POST https://open.tiktokglobalshop.com/api/v2/oauth2/token/
{
  "app_key": "<YOUR_APP_KEY>",
  "app_secret": "<YOUR_APP_SECRET>",
  "grant_type": "client_credentials",
  "shop_id": "<SHOP_ID>"
}
→ { "access_token": "...", "expires_in": 7200 }
```

---

## 二、核心 API 能力（按场景）

### 场景 1：商品管理

**商品列表**：
```
GET /api/v2/product/search
参数：shop_id, page_size, page_number, product_name
```

**商品详情**：
```
GET /api/v2/product/get
参数：shop_id, product_id
```

**商品上架**：
```
POST /api/v2/product/add
参数：shop_id, product_name, description, category_id, sku_list[], images[]
```

**SKU 库存更新**：
```
POST /api/v2/product/sku/update_stock
参数：shop_id, sku_id, stock
```

---

### 场景 2：订单管理

**订单列表**：
```
GET /api/v2/order/search
参数：shop_id, create_time_from, create_time_to, order_status, page_size, page_number
```

**订单详情**：
```
GET /api/v2/order/get
参数：shop_id, order_id
```


**订单发货**：
```
POST /api/v2/order/ship
参数：shop_id, order_id, fulfillment_type, shipment_id, logistics_provider
```

**批量发货**：
```
POST /api/v2/order/ship_batch
```

---

### 场景 3：物流

**物流轨迹**：
```
GET /api/v2/logistics/track
参数：shop_id, shipment_id
```

**支持物流商**：CP（China Post）、YunExpress、J&T、DHL、UPS

---

### 场景 4：达人管理

**达人列表**：
```
GET /api/v2/tiktok/product/affiliate/list
参数：shop_id, page_number, page_size
```

**带货数据**：
```
GET /api/v2/tiktok/product/affiliate/stats
参数：shop_id, start_date, end_date, author_id
```

**创建合作计划**：
```
POST /api/v2/tiktok/product/affiliate/plan/create
参数：shop_id, product_id, commission_rate, plan_name
```

---

### 场景 5：直播数据

**直播列表**：
```
GET /api/v2/tiktok/live/list
参数：shop_id, status
```

**直播商品**：
```
GET /api/v2/tiktok/live/product/list
参数：shop_id, live_id
```

---

### 场景 6：数据分析

**店铺数据**：
```
GET /api/v2/shop/performance
参数：shop_id, date_from, date_to
返回：GMV、订单量、退款率、观看人数
```

**商品数据**：
```
GET /api/v2/product/performance
参数：shop_id, product_id, date_from, date_to
返回：曝光、点击、加购、成交
```

---

## 三、Webhook 事件

支持实时通知：ORDER_STATUS、ORDER_REFUND、ORDER_CANCEL、PRODUCT_STATUS、LIVE_END

配置：Seller Center → Settings → Webhooks

---

## 四、Python 示例

```python
import requests

BASE = "https://open.tiktokglobalshop.com"

def get_access_token(app_key, app_secret, shop_id):
    url = f"{BASE}/api/v2/oauth2/token/"
    resp = requests.post(url, json={
        "app_key": app_key,
        "app_secret": app_secret,
        "grant_type": "client_credentials",
        "shop_id": shop_id
    })
    return resp.json().get("data", {}).get("access_token")

def search_orders(shop_id, token, status="10"):
    url = f"{BASE}/api/v2/order/search"
    headers = {"Authorization": f"Bearer {token}"}
    params = {"shop_id": shop_id, "order_status": status, "page_size": 20}
    return requests.get(url, headers=headers, params=params).json()
```

---

## 五、常见错误

| 错误码 | 含义 | 处理 |
|--------|------|------|
| 10014 | token 过期 | 刷新 token |
| 40100 | 权限不足 | 检查 app 权限 |
| 11003 | shop_id 不匹配 | 确认 token 对应 shop |
| 20001 | 参数错误 | 检查格式 |

---

## 六、GA 管家检查清单

- [ ] 已配置 app_key / app_secret / shop_id
- [ ] 已测试商品列表 API
- [ ] 已测试订单查询
- [ ] 已配置 Webhook（可选）
- [ ] 429 限流处理
- [ ] token 过期自动刷新

---

## 七、参考资源

- Partner 文档：https://partner.tiktokglobalshop.com
- 沙箱：https://sandbox-xt.tiktok.com