# 如何获取 TikTok 商品信息（导出 → 导入 → 看效果）

面板里的「SKU」「商品名」不是从广告接口来的——TikTok 广告 API 只给 `item_group_id`（SPU），
**SKU 编码、商品名称、价格这些只在卖家中心里**。所以要从卖家中心导出一份商品表，再导入插件。

---

## 三步上手（不想看长文只看这里）

```text
① 卖家中心导出 xlsx     → 商品 → 批量操作 → 编辑商品 → 选择商品 → 全部信息 → 生成模板 → 已下载
② 面板导入              → 左侧「商品信息」→ 选择文件 → 导入
③ 看效果                → 广告组 → 点某行下钻 → SKU 汇总 + 素材表「SKU」列
```

前提：`.xlsx` 里必须有 `product_id`（商品 ID）和 `seller_sku`（商家 SKU）两列——官方「全部信息」模板默认就有。

> 只想先试试？直接跳到 **二、怎么使用**，用你已经导出的文件导入即可；
> 还没导出过就看 **三、怎么导出**。

> 按步骤卡住或导不进去，扫码加飞书一起看看（备注「商品表」）；大家互相交流，共同富裕 🙂

<img src="images/contact-feishu-qr.png" width="120" alt="飞书二维码">

---

## 一、这套东西解决什么问题

| 没有导入商品表 | 导入之后 |
|---|---|
| 素材表「SKU」列全是 `-` | 每条素材显示所属 SKU（如 `SOM001UK`） |
| 只知道广告组消耗，不知道是哪个商品在花钱 | SKU 汇总：消耗 / 占比 / 订单 / ROI |
| 广告和商品数据两张皮 | 「商品 × 广告」合并：每个商品挂上广告消耗/订单/GMV/ROI |
| 导出 Excel 没有 SKU 维度 | 「商品明细」「SKU 销量」两个 sheet 有 SKU |

---

## 二、怎么使用（导入 + 在哪看）

### 2.1 导入

1. 打开面板：桌面快捷方式「TikTok广告监控面板」，或 `http://127.0.0.1:8795/`
   （DSH 运行时是 `http://127.0.0.1:8790/`）
2. 左侧点 **「商品信息」**
3. **店铺区域**选对（GB / DE / FR / IT / ES）
4. **选择文件** → 选卖家中心导出的 `.xlsx`
5. 点 **「导入」**

成功后页面会显示：`已导入 85 个商品（Tiktoksellercenter_batchedit_...xlsx，区域 GB，时间）`。

### 2.2 导入之后在哪看

| 位置 | 你会看到 |
|---|---|
| **广告组 → 点任意一行下钻** | 左上「商品 / SKU」表：每个 SKU 的消耗、占比、订单、ROI |
| 同上 → 右侧**素材表** | 「SKU」列：每条素材属于哪个 SKU |
| **商品信息** 页下半部 | 「商品 × 广告」：按 SPU 合并广告消耗/订单/GMV/ROI，可按 SKU/商品名搜索 |
| **数据导出** 页 | 导出的 xlsx 里「商品明细」「SKU 销量」两个 sheet |

### 2.3 命令行方式（可选，留档用）

```bash
python3 tools/parse-product-export.py "Tiktoksellercenter_batchedit_20261030_all_information_template.xlsx" products.json
```

解析器会自动找表头行（前面可能有说明行/中文标签行），同时认英文列名（`product_id` / `seller_sku`）
和中文列名（`商品 ID` / `商家 SKU`）。

### 2.4 文件里至少要有哪些列

| 列（英文 / 中文） | 用途 | 必需 |
|---|---|---|
| `product_id` / 商品 ID | 和广告的 SPU（item_group_id）对齐 | ✅ |
| `seller_sku` / 商家 SKU | 面板上显示的 SKU 编码 | ✅ |
| `product_name` / 商品名称 | 显示商品名 | 建议 |
| `price` / 零售价 | 商品页展示 | 可选 |
| `product_status` / 商品状态 | 过滤下架商品 | 可选 |
| `sku_id` / SKU ID | 多规格商品区分 | 可选 |

---

## 三、怎么导出（卖家中心，约 2 分钟）

### 第 1 步：菜单入口

**商品 → 批量操作 → 编辑商品**

![批量操作菜单](images/product-import/01-menu.png)

### 第 2 步：选择商品 + 模板类型

进入「批量编辑商品」页面后，点 **①「选择商品」**：

![批量编辑商品页面](images/product-import/02-batch-page.png)

在弹窗里筛选（一般选「在售」），勾选要导出的商品（或全选），点 **「选择筛选的商品」**：

![选择商品弹窗](images/product-import/03-pick-products.png)

回到页面后，**② 自定义模板 → 勾「全部信息」**，然后点 **「生成模板」**。

> ⚠️ 一定要选「全部信息」。选「基本信息」等子集文件更小，但可能少 `seller_sku` 列，
> 插件就无法建立 SPU → SKU 的映射。

### 第 3 步：下载生成的 xlsx

生成是异步的，等「下载记录」里的状态变成 **✅ 已完成**，点右侧 **「已下载」**：

![下载记录](images/product-import/04-download.png)

文件名类似：

```
Tiktoksellercenter_batchedit_20261030_all_information_template.xlsx
```

这个文件就是 **二、怎么使用** 里要导入的那份。

---

## 四、什么时候要重新导出

| 场景 | 要不要重导 |
|---|---|
| 上新商品 / 新 SKU | ✅ 要（否则新素材的 SKU 显示 `-`） |
| 改了商品名 / 价格 | ✅ 建议（面板显示会更新） |
| 只是广告数据变化 | ❌ 不用，广告数据是实时拉的 |
| 下架商品 | 可选（不影响已投放素材的历史映射） |

导出和导入都是本地的，不会改动店铺任何数据，随时可以重复做。

---

## 五、常见问题

**Q：素材表的 SKU 列显示 `-`？**
1. 有没有导入商品表？（商品信息页看有没有记录）
2. 这个 SPU 在商品表里存在吗？（导出时可能没勾到它，或它已下架不在「在售」里）
3. 素材属于该 SPU，但 SPU → SKU 映射缺失：重新导出「全部信息」再导入一次。

**Q：提示「每天最多只能发布 240 个商品」？**
那是新卖家试用期的限制，和导出/导入无关——只说明你当前在试用期，不影响本功能。

**Q：上传失败 / 解析失败？**
- 确认是 `.xlsx`（不要 xls 另存的旧格式，不要 PDF/CSV 混用）
- 文件里必须有 `product_id` 与 `seller_sku` 两列
- 解析需要 Python（openpyxl）：面板会优先用 DSH 自带 Python，找不到时用系统 `python3`/`python`；
  可用环境变量 `PYTHON_PATH` 指定解释器

**Q：导入的数据存在哪里？**
`%USERPROFILE%\.dsh\plugin-data\tiktok-ads\`
- `product-imports/`：原始 xlsx + 解析出的 JSON
- `sku-map-cache/`：SPU → SKU 的 CSV 缓存（插件各处共用的映射）