# TikTok Partner Campaign 开通与授权操作说明

本文档给运营同学使用，目标是完成 BeeX 调用 TikTok Shop Partner / TAP Campaign 接口所需的开通、授权和验证。

适用范围：

1. TikTok Shop Partner / TAP Campaign 授权。
2. Partner Campaign 列表查询。
3. Campaign 商品列表查询。
4. Campaign 商品推广链接生成。

不适用：

1. Creator 商品搜索 / Creator 商品转链。
2. CAP / MCN 订单查询。
3. Seller Center 店铺授权。

## 1. 本次要解决什么问题

BeeX 现在要接入 TikTok Shop Partner / TAP Campaign 相关能力：

1. 查询 Partner Campaign 列表。
2. 查询某个 Campaign 下的商品列表。
3. 为 Campaign 商品生成推广链接。

技术侧已经完成接口接入，但 TikTok 当前返回：

```text
16032001 Invalid parameter main_account_id, please ensure partner not found, please check the auth was in the right market.
```

这表示当前授权还缺 TikTok 认可的 Partner 主账号主体信息，或者授权账号不是对应市场的 TikTok Affiliate Partner / TAP 账号。BeeX 不再自动把 `partner_id`、`seller_id`、`authorized_account_id` 猜成 `main_account_id`，避免把错误 ID 传给 TikTok。

所以本次不是重新做普通 TikTok 授权，而是要开通并授权 Partner Campaign 对应的 Partner/TAP 账号。

## 2. 运营需要准备什么账号

请使用 TikTok Shop Partner / TAP 账号登录，不要使用普通达人账号、普通卖家账号、Creator 账号。

账号要求：

1. 市场必须是 Indonesia / ID。
2. 账号必须拥有 TikTok Shop Partner / TAP Campaign 相关权限。
3. 账号需要能看到 Partner Campaign / TAP Campaign 相关功能。
4. 账号最好是主账号或拥有完整 API 授权权限的管理员账号。

不要使用下面这些授权入口：

1. Creator 授权入口：`shop.tiktok.com/alliance/creator/auth`
2. Seller Center 普通卖家授权入口
3. CAP / MCN 订单授权入口

本次需要的是 Partner / TAP Campaign 授权。

## 3. 需要确认的 API 权限

请在 TikTok Partner Center 的 App API 权限里确认以下 scope 已经启用。

必需：

1. Read Affiliate Partner Campaigns
   - Scope Key 通常为：`partner.tap_campaign.read`
2. Generate / Manage Affiliate Partner Campaign Product Link
   - Scope Key 通常为：`partner.tap_campaign.link.write`
3. Partner Authorized Information
   - 用于确认授权账号主体信息，建议打开。

可选但建议打开：

1. Manage Affiliate Partner Campaigns
2. Manage Affiliate Partner Campaign Products

如果新开了 scope，需要重新授权一次，否则旧 token 不会自动拥有新权限。

## 4. 开通前检查清单

运营开始授权前，先确认下面 5 项：

1. App Key 是 BeeX 当前使用的 App Key：`6jpnqa49bjoie`。
2. 当前 App 的 API scope 里已经启用 Partner Campaign 相关权限。
3. 授权账号属于 Indonesia / ID 市场。
4. 授权账号不是 Creator、不是 Seller、不是 CAP 订单账号。
5. 浏览器当前登录的 TikTok 账号就是要授权的 Partner/TAP 账号。

如果浏览器登录过多个 TikTok 账号，建议用无痕窗口打开授权链接，避免授权到错误账号。

## 5. 授权操作步骤

### 第一步：获取 BeeX 授权链接

打开下面这个地址，系统会生成 TikTok Partner 授权链接：

```text
https://api-id-test.beexofficial.com/api/v1/integrations/tiktok/auth-url?countryCode=ID&accountType=PARTNER
```

返回内容里会有一个 `authorizationUrl` 字段，请复制这个地址打开。

正常情况下，这个地址会长得像：

```text
https://partner.tiktokshop.com/open/authorize?service_id=7630608661891090192&state=...
```

注意：

1. 不要自己手写授权 URL。
2. 不要复用 Creator / CAP / Seller 的授权 URL。
3. 每次重新授权建议重新生成一次 URL。

### 第二步：用正确的 TikTok Partner / TAP 账号登录

打开授权链接后：

1. 确认当前登录账号是 Indonesia 市场的 Partner / TAP 账号。
2. 如果浏览器里已经登录了错误账号，请先退出 TikTok，再重新打开授权链接。
3. 授权页面里如果能看到权限列表，请确认包含 Partner Campaign 相关权限。
4. 点击授权。

### 第三步：把回调地址发给技术

授权成功后，页面会跳转到类似下面的地址：

```text
https://www.beexofficial.com/tiktok-auth-callback.html?state=...&code=...&client_key=...
```

请把完整 URL 发给技术同学。

完整 URL 必须包含：

1. `state`
2. `code`
3. `client_key` 或 `app_key`

注意：

1. `code` 是一次性授权码，有时效。
2. 同一个 `code` 只能使用一次。
3. 发给技术后应尽快处理；如果处理失败或超时，需要重新生成授权链接并重新授权。

### 第四步：提供 main_account_id

如果 TikTok 后台能看到以下任意字段，请一起发给技术：

1. `main_account_id`
2. `main_account_id_cipher`
3. 页面明确标注为 Main Account ID 的字段
4. TikTok 技术/运营明确说明可以作为 Partner Campaign API `main_account_id` 参数的字段

不要把下面这些字段直接当成 `main_account_id`：

1. Partner ID
2. Seller ID
3. Account ID
4. Authorized Account ID
5. 普通达人 ID

如果后台页面没有明确字段，请截图以下页面给技术，由技术和 TikTok 支持一起确认：

1. TikTok Partner Center 当前账号信息页。
2. App 的 View access rights 页面。
3. Partner / TAP Campaign 页面顶部账号信息。
4. API Testing Tool 里能展示 account / partner / main account 的位置。

## 6. 技术侧处理回调

技术侧会先处理回调：

```text
https://api-id-test.beexofficial.com/api/v1/integrations/tiktok/callback?state=xxx&code=xxx
```

处理成功后，系统会把 token 保存到 `platform_account_config`：

1. `country_code = ID`
2. `platform = TIKTOK`
3. `account_type = PARTNER`
4. `status = ACTIVE`

技术侧只需要保存 token，不需要把 token 发到群里。

如果失败，接口会返回 TikTok 的错误 `code/message/request_id`，优先按错误信息排查。

## 7. 授权完成后的接口验证

### Category Asset Cipher 映射

TikTok 的 `Get Authorized Category Assets` 接口会返回多个 `category_assets`，不同 API 必须使用不同的 `cipher`。

已确认的 ID 市场映射如下：

| API 场景 | category.name | category_asset_cipher |
| --- | --- | --- |
| CAP 订单查询：`/affiliate_partner/202603/cap_order/search` | `Creator Management` | `ROW_L2lQaAAAAAAzXkQWIHTHFI_usF_y_j4j` |
| Partner Campaign 列表、Campaign 商品列表、Campaign 商品推广链接 | `Seller and Scalable Creator Match-Up` | `ROW_fyGlKwAAAAB6jCmj_Z8Zc6uknZJUdZAi` |

不要把 `Creator Management` 的 cipher 用在 `/affiliate_partner/202405/campaigns` 这组 Campaign 接口上，否则会出现权限或账号主体错误。

第一步，验证 Campaign 列表：

```text
https://api-id-test.beexofficial.com/api/v1/integrations/tiktok/partner-campaigns?countryCode=ID&pageSize=10
```

成功时应该返回 Campaign 数据。

Campaign 返回字段里的 `status` 是活动状态，不是审核状态。当前 TikTok 文档给出的枚举值为：

| status | 含义 |
| --- | --- |
| `READY` | 活动已准备好，通常可继续查询商品或进入后续流程 |
| `UPCOMING` | 活动未开始 |
| `ONGOING` | 活动进行中 |
| `CLOSED` | 活动已结束 |
| `UNSPECIFIED` | TikTok 未明确给出状态 |

BeeX 后端对 Partner Campaign 接口返回值做原样透传，前端和运营后台只允许展示以上状态，不再使用 `review_status` 判断 Campaign 是否可用。

第二步，拿 Campaign ID 查询商品列表：

```text
https://api-id-test.beexofficial.com/api/v1/integrations/tiktok/partner-campaigns/{campaignId}/products?countryCode=ID&pageSize=10
```

Campaign 商品列表里的 `review_status` 是商品审核状态，不是 Campaign 活动状态。BeeX 进入 C 端商品池时只保留：

| 字段 | 可进入 C 端商品池的条件 |
| --- | --- |
| `campaign.status` | `READY` 或 `ONGOING`。 |
| `product.review_status` | 必须为 `APPROVED`。 |
| `product_id` | 必须存在，并能生成 TikTok/Tokopedia PDP 链接。 |
| 商品价格 / 用户返现 | 都必须大于 0。 |
| 商品状态 | 如果 TikTok 返回售罄、下架、不可购买、活动过期等字段，则过滤。 |

注意：TikTok Campaign 商品列表不一定返回平台 PDP 链接，BeeX 会用 `product_id` 生成 `https://shop-id.tokopedia.com/view/product/{productId}?region=ID&local=en` 作为商品详情页兜底链接。但“能生成 PDP”不代表一定能购买，最终仍以平台接口返回状态和转链结果为准。

第三步，拿 Campaign ID + Product ID 生成推广链接：

```text
POST https://api-id-test.beexofficial.com/api/v1/integrations/tiktok/partner-campaigns/{campaignId}/products/{productId}/promotion-link?countryCode=ID&trackingId=beex_test
```

三个接口都成功，才算 Partner Campaign 链路开通完成。

失败时请重点看错误：

1. `16032001 Invalid parameter main_account_id`
   - 授权账号主体不对，或缺正确的 `main_account_id`。
   - 如果 BeeX 没有配置 `SEAHUB_TIKTOK_PARTNER_CAMPAIGN_MAIN_ACCOUNT_ID`，系统会先不传 `main_account_id` 调用；仍然返回 16032001 时，需要运营提供 TikTok 明确认可的 Main Account ID。
2. `16032012 only affiliate partner cipher can access this api`
   - 授权资产不是 Affiliate Partner / TAP 类型。
3. scope / permission 相关错误
   - App 没开对应 API scope，或 scope 开了但没有重新授权。

## 8. 常见错误排查

### 情况一：运营用了 Creator 授权链接

现象：

1. 授权能成功。
2. 但 Partner Campaign 接口无法访问。
3. 可能返回 Partner cipher 或 main account 错误。

处理：

重新使用 BeeX 生成的 `accountType=PARTNER` 授权链接。

### 情况二：运营账号不是 ID 市场账号

现象：

TikTok 返回：

```text
check the auth was in the right market
```

处理：

使用 Indonesia 市场的 TikTok Partner / TAP 账号重新授权。

### 情况三：App 新开 scope 后没有重新授权

现象：

后台显示 scope 已打开，但接口仍提示没权限。

处理：

重新生成授权链接，并用正确账号重新授权。

### 情况四：授权的是子账号，但子账号无 Campaign 权限

现象：

授权成功，但接口提示 partner not found 或 main_account_id 无效。

处理：

换主账号授权，或给子账号补 Partner / TAP Campaign API 权限后重新授权。

### 情况五：回调处理返回 code 已使用或过期

现象：

技术调用 callback 时，TikTok token API 返回授权码无效、已使用或过期。

处理：

重新打开 BeeX 授权链接生成接口，拿新的授权链接重新授权。不要复用旧回调 URL。

### 情况六：授权成功，但 Campaign 列表为空

现象：

接口返回成功，但 Campaign 列表为空。

处理：

这通常表示授权链路通了，但当前 Partner/TAP 账号没有可访问的 Campaign。请运营在 TikTok 后台确认 Campaign 是否存在、是否归当前 Partner 账号管理。

## 9. 运营交付给技术的信息清单

请一次性发下面这些信息：

1. 完整授权回调 URL。
2. 当前登录账号截图。
3. App API scope 截图。
4. View access rights 截图。
5. Partner / TAP Campaign 页面截图。
6. 如果能看到，提供 `main_account_id` 或 `main_account_id_cipher`；不要只发 Partner ID / Seller ID。
7. 授权账号所属市场：例如 ID。

如果 TikTok 支持确认了正确 `main_account_id`，技术侧在 id-test ECS 环境变量中配置：

```text
SEAHUB_TIKTOK_PARTNER_CAMPAIGN_MAIN_ACCOUNT_ID=正确的 main_account_id
```

然后重启/重新部署服务，再重新调用 Campaign 列表接口验证。

## 10. 验收标准

技术侧确认以下接口返回成功，即表示授权完成：

1. Campaign 列表能返回数据。
2. Campaign 商品列表能返回数据。
3. Campaign 商品推广链接能生成成功。

如果 Campaign 列表本身为空，但接口返回成功，也说明授权链路已经通了，只是当前账号没有可用 Campaign。

## 11. 当前这次授权的处理方式

如果运营发来类似下面的 URL：

```text
https://www.beexofficial.com/tiktok-auth-callback.html?state=sx:ID:pac_xxx:nonce_xxx&code=ROW_xxx&client_key=6jpnqa49bjoie
```

技术侧要做的是：

1. 取出 `state` 和 `code`。
2. 调用 BeeX id-test callback 接口。
3. 如果保存 token 成功，立即调用 Campaign 列表验证。
4. 如果失败，把接口返回的 TikTok `code/message/request_id` 反馈给运营。

不要只在浏览器打开 `www.beexofficial.com/tiktok-auth-callback.html` 后就结束；这个页面只是 TikTok 跳转落点，真正保存 token 的动作在 BeeX API 服务里。