# TikTok 双 App 联调 Runbook

## 1. 目标

这个项目现在同时支持两条测试链路：

- `TikTok for Business`
- `TikTok for Developers`

适合你当前这种场景：

- Business App 已经在跑 Lead / Ads / Accounts API
- 现在还想注册一个 Developers App，把 `Login Kit` / `Display API` 一起测通

## 2. 两条链路的区别

### TikTok for Business

用途：

- Lead 订阅
- Ads / advertiser 相关接口
- 你现有的 `subscription/subscribe`
- 后续如果权限已开，也可继续测 `identity/live/get`、`business/get`、`business/video/list`

当前项目里的 Business 回调：

- 兼容旧地址：`/api/tiktok-callback`
- 新推荐地址：`/api/tiktok-business-callback`

### TikTok for Developers

用途：

- `Login Kit`
- `Display API`
- `Content Posting API`
- `Data Portability API`（若需数据导出能力，还要同时配置 `Webhooks`）

当前项目里的 Developers 回调：

- `/api/tiktok-developers-callback`
- `/api/tiktok-webhook`（给 `Webhooks` / `Data Portability API` 使用）

## 3. 环境变量

复制 `.env.example`，按实际值填入 `.env.local`。

关键变量：

- Business
  - `TIKTOK_BUSINESS_APP_ID`
  - `TIKTOK_BUSINESS_SECRET`
  - `TIKTOK_BUSINESS_REDIRECT_URI`
- Developers
  - `TIKTOK_DEV_CLIENT_KEY`
  - `TIKTOK_DEV_CLIENT_SECRET`
  - `TIKTOK_DEV_REDIRECT_URI`
  - `TIKTOK_DEV_SCOPES`

推荐默认回调：

- Business: `https://tiktok-vercel-callback.vercel.app/api/tiktok-business-callback`
- Developers: `https://tiktok-vercel-callback.vercel.app/api/tiktok-developers-callback`

## 4. 统一测试入口

打开：

```text
/api/tiktok-test
```

它会返回：

- 两条授权 URL
- 当前缺失的环境变量
- 推荐回调地址
- token exchange 入口

## 5. Business 联调步骤

### 5.1 发起授权

从 `/api/tiktok-test` 返回的 `business.authorizationUrl` 打开授权页。

### 5.2 获取回调 code

授权成功后，TikTok 会跳到：

```text
/api/tiktok-business-callback
```

你会看到：

- `auth_code`
- `state`
- 推荐下一步

兼容旧流程时，仍可继续使用：

```text
/api/tiktok-callback
```

### 5.3 换 Business access_token

调用：

```bash
curl -X POST 'https://tiktok-vercel-callback.vercel.app/api/tiktok-business-exchange' \
  -H 'Content-Type: application/json' \
  -d '{
    "auth_code": "PASTE_AUTH_CODE_HERE"
  }'
```

它会在服务端调用：

```text
POST https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/
```

### 5.4 继续测试 Business API

Business token 换出来后：

- Lead 相关：继续参考 [TIKTOK_SUBSCRIPTION_RUNBOOK.md](/Users/ardor/Desktop/work/TKlead/tiktok-vercel-callback/TIKTOK_SUBSCRIPTION_RUNBOOK.md)
- 直播/账号数据：参考 [tiktok-live-hq-business-account-guide.md](/Users/ardor/Desktop/work/TKlead/reports/tiktok-live-hq-business-account-guide.md)

最小直播测试接口建议：

```text
GET https://business-api.tiktok.com/open_api/v1.3/identity/live/get/
```

最小账号洞察测试接口建议：

```text
GET https://business-api.tiktok.com/open_api/v1.3/business/get/
```

## 6. Developers 联调步骤

### 6.1 在 Developers Portal 配置

产品至少加：

- `Login Kit`

如果你要测基本资料读取，再加：

- `Display API`

常用 scope：

- `user.info.basic`
- `video.list`（如果要读公开视频）

### 6.2 发起授权

从 `/api/tiktok-test` 返回的 `developers.authorizationUrl` 打开授权页。

根据本地归档的 `Login Kit for Web` 文档，Web 授权 URL 结构是：

```text
https://www.tiktok.com/v2/auth/authorize/?client_key=...&response_type=code&scope=...&redirect_uri=...&state=...
```

### 6.3 获取回调 code

授权成功后会跳到：

```text
/api/tiktok-developers-callback
```

你会看到：

- `code`
- `scopes`
- `state`

### 6.4 换 Developers access_token

调用：

```bash
curl -X POST 'https://tiktok-vercel-callback.vercel.app/api/tiktok-developers-exchange' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "PASTE_CODE_HERE"
  }'
```

它会在服务端调用：

```text
POST https://open.tiktokapis.com/v2/oauth/token/
```

### 6.5 验证 Developers API

拿到 `access_token` 后，先测用户资料：

```bash
curl 'https://tiktok-vercel-callback.vercel.app/api/tiktok-developers-user-info?access_token=PASTE_ACCESS_TOKEN_HERE&fields=open_id,union_id,avatar_url,display_name'
```

它会代理到：

```text
GET https://open.tiktokapis.com/v2/user/info/
```

这是最适合确认 `Login Kit + Display API` 是否真的打通的第一条接口。

## 7. 推荐的测试顺序

1. 先看 `/api/tiktok-test`
2. 先跑 Business，确认旧链路没坏
3. 再跑 Developers，确认新 App 的 `Login Kit` 正常
4. Developers token 拿到后，先测 `/api/tiktok-developers-user-info`
5. Business token 拿到后，继续按旧 runbook 或直播 runbook 往下测

## 8. 这次新增的测试路由

- `/api/tiktok-test`
- `/api/tiktok-business-callback`
- `/api/tiktok-developers-callback`
- `/api/tiktok-business-exchange`
- `/api/tiktok-developers-exchange`
- `/api/tiktok-developers-user-info`

## 9. 注意事项

1. Business 和 Developers 是两套不同凭证

- Business 用 `app_id` / `secret`
- Developers 用 `client_key` / `client_secret`

2. 两边的 callback code 字段不一样

- Business 常见是 `auth_code`
- Developers 是 `code`

3. 不要混用 token

- Business access token 不能拿去调 Developers 的 `/v2/user/info/`
- Developers access token 不能拿去调 Business 的 `/open_api/v1.3/...`

4. 建议把两个 redirect URI 分开

- 这样最不容易在 Portal 配置时混淆
- 回调页也能直接告诉你下一步该打哪条 token 接口