v1.0 · April 2026

TKstore API
白皮书

面向 TikTok 生态的一体化数据中台 — 整合 Developer (Display)、Shop Partner、Business (Marketing) 三套官方 API，提供统一的 OAuth、Webhook 接收与店铺指标聚合服务。

快速接入 API 索引 健康检查 →

概览

TKstore 把 TikTok 三套独立 API 收敛成一个对外契约，让上层业务专注数据应用而非协议适配。

Developer

Display + Content Posting

用户授权登录、视频列表、内容发布、Webhook 事件 (粉丝/点赞/视频更新)。

Shop Partner

Shop Open API

店铺授权、订单/商品/库存同步、店铺事件 Webhook、多区域 (US / SEA / Global)。

Business

Marketing API

广告账户、Campaign / AdGroup / Ad、投放数据回流（规划中）。

Aggregation

店铺指标

跨数据源聚合店铺级 KPI，统一暴露 /api/shops/:id/metrics。

快速接入

下面是把店铺接进 TKstore 的最小步骤。

1. 健康检查

# 验证服务可达
curl https://tk.evageek.com/healthz
# → ok

2. 发起店铺授权

# 浏览器打开授权入口，TikTok Shop 完成授权后回调 TKstore
open https://tk.evageek.com/oauth/shop/start

# 回调 URL (TikTok 后台填写)
https://tk.evageek.com/oauth/shop/callback

3. 拉取店铺列表

curl https://tk.evageek.com/api/shops

# 响应示例
{
  "shops": [
    { "id": 1, "name": "Demo Shop", "region": "us", "connected_at": "2026-04-23T01:00:00Z" }
  ]
}

4. 查看指标

curl https://tk.evageek.com/api/shops/1/metrics

OAuth 接入

TKstore 实现了 TikTok Shop 与 Developer Display 两条 OAuth 流程。Token (access / refresh) 经 AES-256 加密入库，绝不出现在日志中。

Shop OAuth

GET
/oauth/shop/start
生成 state、跳转到 TikTok Shop 授权页。
GET
/oauth/shop/callback?code=...&state=...
TikTok 回调；交换 access_token + refresh_token，加密入库，建立 shop 记录。

Display OAuth

GET
/oauth/display/start
用户登录授权入口，scopes: user.info.basic, user.info.profile, user.info.stats, video.list。
GET
/oauth/display/callback?code=...&state=...
回调换 token，落库后跳转回前端。

密钥管理

Token 加密
AES-256 加密存储，不出现在任何日志中
Refresh 时机
周期检查，过期前 10 分钟主动刷新
State 校验
5 分钟有效期的一次性 state，防 CSRF

Webhook

TKstore 接收两类官方事件，进入队列异步处理，避免阻塞 TikTok 重试。

POST
/webhook/developer
Developer (Display / Content Posting) 事件：粉丝变动、视频审核结果、点赞数据。签名校验通过 client_secret。
POST
/webhook/shop
Shop 事件：订单状态、退款、商品审核、库存。多区域路由按 shop_id → region。

TikTok 后台填写

# Developer Console
Callback URL: https://tk.evageek.com/oauth/display/callback
Webhook URL : https://tk.evageek.com/webhook/developer

# Shop Partner Center
Redirect URI: https://tk.evageek.com/oauth/shop/callback
Webhook URL : https://tk.evageek.com/webhook/shop

REST API 索引

所有 endpoint base = https://tk.evageek.com。

MethodPath说明
GET/healthz存活探针，返回 ok
GET/oauth/shop/start启动 Shop 授权
GET/oauth/shop/callbackShop 授权回调
GET/oauth/display/start启动 Display 授权
GET/oauth/display/callbackDisplay 授权回调
POST/webhook/developerDeveloper 事件接收
POST/webhook/shopShop 事件接收
GET/api/shops已授权店铺列表
GET/api/shops/:id/metrics店铺指标聚合

FAQ

Webhook 多久重试一次？

TKstore 收到事件即返回 200，重试由 TikTok 侧策略决定。处理失败的事件会自动重试，最多 10 次指数退避。

Token 过期怎么办？

系统会定期检查即将过期的 token 并提前刷新；如刷新失败，会在下次数据同步时按需刷新。