TikTok官方-店铺ERP授权

TikTok Shop ERP（小店）专用授权与管理技能，固定 appType=erp，提供 OAuth 授权、已授权 ERP 店铺查询；可选查询已入库令牌与手动刷新。业务调用经 developerProxy 时 token 已后台化（按 openId 取库，401/过期自动刷新），一般无需手动 refresh。region 支持 global / us。当用户提到 TikTok Shop 授权、绑定 TikTok 小店、TikTok ERP 店铺授权、查询已授权 TikTok 小店、TikTok Shop ERP authorization, bind TikTok Shop, authorized TikTok shops 时触发。只要需求涉及 TikTok Shop 卖家 ERP 账号授权或令牌管理，也应触发。**仅 ERP**；不含联盟 affiliate、不含达人/视频号（creator，请用 linkfox-tiktok-video-auth）。

TikTok Shop ERP 授权与权限管理

本 skill 仅负责 TikTok Shop ERP（小店） 的 OAuth 授权、已授权店铺列表，以及可选的令牌查询/手动刷新。是后续通过 /tiktokShop/developerProxy（appType=erp）调用 TikTok Shop 开放接口的前置依赖（业务侧只需 openId）。底层经 LinkFox 网关对接紫鸟开放平台代理。

🔒 固定 appType=erp。脚本会强制写入 erp；传入 affiliate / creator 将拒绝。联盟授权、达人授权均不在本 skill 范围。

⚠️ 达人/视频号授权请用 linkfox-tiktok-video-auth（/tiktokVideo）。

📌 业务接口不在本 skill：商品、订单、履约、财务等按功能拆成独立 ERP 业务 skill（均依赖本 skill 选店拿 openId），经 /tiktokShop/developerProxy 调用。

ERP Skill 套件（按功能切换）

Skill	职责
linkfox-tiktok-shop-auth（本 skill）	ERP 授权 + 选店（+ 可选令牌查询/手动刷新）
linkfox-tiktok-shop-product	ERP 商品：刊登检查、类目、创建/编辑、上下架、价库
linkfox-tiktok-shop-order	ERP 订单：订单列表、订单详情
linkfox-tiktok-shop-fulfillment	ERP 履约：拆单属性（后续可扩发货/包裹）
linkfox-tiktok-shop-logistics	ERP 物流：仓库列表（后续可扩配送选项等）
linkfox-tiktok-shop-return-refund	ERP 售后：拒退/拒取消原因
linkfox-tiktok-shop-analytics	ERP 分析：店铺视频表现
linkfox-tiktok-shop-*（规划中）	finance 等

Agent 按用户意图切换 skill：先本 skill 拿到 openId，再进对应业务 skill（不必再取/刷新 accessToken）。

Core Concepts

授权流程：生成授权 URL → 用户浏览器完成 TikTok Shop 授权 → 紫鸟回调推送 Token → 按 state 落库。授权 URL 约 1 小时有效。

店铺标识：以卖家 openId 标识；本 skill 一律按 appType=erp 查询/刷新令牌。

令牌生命周期（后台化）：

• /tiktokShop/developerProxy 按 openId + appType 从库取 accessToken；ttsAccessToken 字段已废弃（传入也会被忽略）。
• 上游返回 HTTP 401 或 body 含 token expired/invalid 时，网关自动 refresh 一次并重试，同时回写库中的 accessToken / refreshToken / 过期时间。
• 无按 accessTokenExpireIn 提前刷新，也无定时刷新任务；/storeTokens 只读库，不校验过期。
• 业务 skill 不要在调用前手动 /refreshToken。手动刷新仅用于排查或用户明确要求。
• refreshToken 本身过期 → 须重新授权。

Data Fields

Authorization URL Response

Field	Type	Description
authorizeUrl	string	TikTok Shop ERP 授权链接（约 1 小时有效）

Authorized Store Item（本 skill 仅展示 erp）

Field	Type	Description
openId	string	卖家唯一标识
sellerName	string	店铺名称
sellerBaseRegion	string	店铺所在区域（如 ID）
appType	string	固定为 erp
region	string	global / us

Store Tokens

Field	Type	Description
accessToken	string	调用 TikTok Shop ERP 开放接口的凭证
refreshToken	string	续签用
accessTokenExpireIn	integer	accessToken 过期 Unix 时间戳
refreshTokenExpireIn	integer	refreshToken 过期 Unix 时间戳

Supported Regions

region	说明
global	全球（默认）
us	美国站

appType 固定为 erp，不可选。

API Usage

详见 references/api.md。

Available Scripts

• scripts/authorize_url.py — 生成 ERP 授权 URL（可选 shopName / region；强制 appType=erp）
• scripts/authorized_stores.py — 列出已授权店铺，仅返回 appType=erp
• scripts/store_tokens.py — （可选）按 openId 查 ERP 令牌；业务调用不需要
• scripts/refresh_token.py — （可选）手动刷新 ERP access_token；业务调用不需要（proxy 会自动刷新）

Usage Scenarios

Scenario 1: Authorize New ERP Shop

1. 确认 region（美国站 us，否则默认 global）。可选 shopName。
2. 调用 /tiktokShop/authorizeUrl（appType=erp）。
3. 把 authorizeUrl 给用户浏览器打开（约 1 小时有效）。
4. 授权完成后可选调 authorized_stores 确认。

Scenario 2: List ERP Shops

调用 /tiktokShop/authorizedStores，只展示 appType=erp 店铺。

Scenario 3: Manual Refresh Token（可选）

仅当用户明确要求手动刷新，或排查令牌问题时使用。传入 openId（脚本固定 appType=erp）。日常业务调用不要先刷新——developerProxy 遇 401/过期会自动 refresh 并重试。refreshToken 过期则重新授权。

Scenario 4: Query Tokens（可选 / 调试）

传入 openId，只读返回库中令牌与过期时间（不校验是否已过期，也不自动刷新）。业务 skill 不需要此步骤。

Scenario 5: Prepare for ERP Business Skill

1. authorized_stores 选店 → 得到 openId
2. 切换到对应 linkfox-tiktok-shop-* 业务 skill，脚本只传 openId（token 由网关解析）

Display Rules

1. 只呈现授权/店铺/令牌数据，不做业务建议。
2. 勿明文输出完整 token，仅掩码。
3. 授权链接须说明约 1 小时失效。
4. 过期字段为绝对 Unix 时间戳（仅供展示；业务侧勿据此主动 refresh）。
5. 用户提到达人/视频号/联盟授权时，勿用本 skill。

Important Limitations

• 仅 ERP：拒绝 affiliate / creator。
• 不含业务 API：商品/订单等进对应 shop 业务 skill。
• 达人授权 → linkfox-tiktok-video-auth。
• 授权链接约 1 小时有效；用户只能管理自己的店铺。
• 无提前/定时刷新；依赖 developerProxy 被动刷新。

User Expression & Scenario Quick Reference

Applicable：

User Says	Scenario
"授权我的 TikTok Shop / 小店 / ERP"	ERP 新店授权
"看看已授权的 TikTok 小店"	列 ERP 店铺
"TikTok 小店令牌过期了"	优先：直接重试业务 API（proxy 自动 refresh）；仅用户坚持手动时用 Scenario 3
"获取某 TikTok 小店访问令牌"	查 ERP 令牌（调试）

Not applicable：

User Says	应使用
达人/视频号授权	linkfox-tiktok-video-auth
联盟 affiliate 授权	不在本 skill（当前未提供专用 skill）
拉取 TikTok Shop 商品 / 订单 / 履约 / 仓库 / 售后 / 分析等业务数据	对应 linkfox-tiktok-shop-*（商品 product，订单 order，履约 fulfillment，仓库 logistics，售后 return-refund，分析 analytics）

Quick Reference

API	Path	Purpose
Get Authorization URL	/tiktokShop/authorizeUrl	生成 ERP 授权链接
List Authorized Stores	/tiktokShop/authorizedStores	店铺列表（本 skill 过滤 erp）
Query Store Tokens	/tiktokShop/storeTokens	（可选）查 ERP 令牌
Refresh Token	/tiktokShop/refreshToken	（可选）手动刷新；日常业务不需要

Feedback：见 references/api.md，skillName：linkfox-tiktok-shop-auth。

Handling Large Responses

text

python scripts/response_io.py run --script scripts/authorize_url.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"

Pick --out-dir outside any git working tree. Persisted responses may contain auth-sensitive data — do not commit them.

Entry scripts: authorize_url.py, authorized_stores.py, refresh_token.py, store_tokens.py.

---

For more skills, visit LinkFox Skills.