Linkfox Wb Tiktok Official Api

[!IMPORTANT] 本 Skill 必须依赖 MCP “LinkFox”。如未安装该MCP，请明确通知用户： 请先安装 LinkFox 连接器：

• 在 WorkBuddy 左侧找到 “专家·技能·连接器” → “连接器”；
• 搜索关键词 “LinkFox”，并安装连接器 “LinkFox”（注意：是 linkfox，不是 linkfox-product-selection），按指引完成登录授权；
• 返回 WorkBuddy 重试。

LinkFox TikTok官方运营API（LinkFox TikTok Official Operations API）

为 TikTok Shop 卖家和达人运营提供统一的官方接口执行能力：完成店铺授权与选店，管理商品和库存，查询订单与仓库，判断订单拆单属性，读取售后拒因并分析店铺视频表现；达人商品与可购物视频工作流保留接口契约，但当前存在授权映射阻塞。当前归档 8 个业务域、45 个 API operation；35 个 ERP operation 可通过 proxy_call 执行，storeTokens 仅保留响应契约且不得用于读取凭证，1 个 ERP multipart 文件上传 operation 仅保留官方参数参考；8 个达人 operation 在网关实现 WorkBuddy 授权上下文到上游达人授权的自动映射前均不可执行，其中视频文件上传另受 multipart 限制。各业务域标识、完整 operation、端点、本地辅助脚本和参数参考见下方路由表。

MCP 调用

• toolName 精确匹配且区分大小写；共享 developerProxy 的 appType、openId、path、method、queryString、body 等继续放在 arguments。
• WorkBuddy 自动注入 MCP Authorization；禁止在 MCP 配置或 arguments 中增加 LinkFox headers、API Key、token、JWT、手机号或其他凭证。
• 禁止 curl、urllib、requests、httpx 或其他 HTTP 方式直连工具网关；MCP 缺失时停止，不得静默 fallback。
• 收费调用失败、空结果或不理想时不得自动重试；同一任务内相同 toolName + arguments 不得重复调用。网关对 TikTok 店铺令牌的内部续签不等于 Agent 重试。
• 先检查 MCP/schema/isError，再读取 text/structured content；text 为 JSON 字符串时只解析一次。随后检查下游 errcode/errorCode/code/errmsg/message，最后读取业务字段。
• 新 MCP 链路不提供旧脚本的 24 小时缓存、响应落盘或 stdout 摘要；仅记录非敏感调用摘要和状态用于追溯。

能力边界

能力范围

• 授权与店铺上下文（linkfox-tiktok-shop-auth）：生成 TikTok Shop ERP OAuth 授权链接、列出已授权 ERP 店铺，并在用户明确要求或排查授权异常时手动刷新后台授权；storeTokens 仅保留响应契约，不用于读取或展示凭证。region 支持 global 和 us，appType 固定为 erp。
• 达人资料与带货内容（linkfox-tiktok-creator）：归档达人档案、绑定店铺商品、橱窗/直播袋商品以及可购物视频预检、发布和状态查询契约；当前不得调用，授权映射阻塞见 references/linkfox-tiktok-creator--api.md。
• ERP 商品运营（linkfox-tiktok-shop-product）：通过 product/ 与 authorization/ 路径完成刊登前置检查、类目树/类目规则/属性/品牌、类目推荐、商品搜索与详情、创建/全量编辑/部分编辑、刊登校验、上下架、改价、改库存、删除/恢复；本地商品主图可用 upload_product_image.py 转为 TikTok URI。
• ERP 订单查询（linkfox-tiktok-shop-order）：按状态、时间和分页查询订单，并以订单 ID 获取 202507（推荐）或 202309 详情；订单查询结果可继续交给 linkfox-tiktok-shop-fulfillment 判断拆单属性。
• ERP 履约准备（linkfox-tiktok-shop-fulfillment）：查询订单是否可拆单、是否必须拆单及原因；使用 fulfillment/202309/orders/split_attributes，订单 ID 通常来自订单查询。
• ERP 物流仓库（linkfox-tiktok-shop-logistics）：查询店铺销售仓/退货仓等仓库的 ID、类型、状态和地址摘要，为商品库存或多仓运营取得 warehouse_id。
• ERP 售后信息（linkfox-tiktok-shop-return-refund）：根据退货或取消单的 return_or_cancel_id 查询可用拒退/拒取消原因和本地化文案。
• ERP 经营分析（linkfox-tiktok-shop-analytics）：按 start_date、end_date 查询店铺视频的浏览、点击、订单、GMV 等表现指标，支持分页、币种、排序和粒度参数。
• 统一网关与脚本执行：ERP 业务经 POST tiktokShop/developerProxy 转发，使用非凭证店铺标识 openId 选择后台授权上下文。达人来源契约要求单独的上游凭证请求字段，但当前没有证据表明 MCP 会自动映射该字段；不得读取、保存或放入 arguments，因此达人 operation 暂停调用。新 MCP 链路不提供旧脚本的缓存、响应落盘或 stdout 摘要。

边界与限制

• 凭证不得进入参数：ERP 业务使用非凭证店铺标识 openId 选择后台授权上下文，appType 固定 erp。达人来源没有定义可替代凭证的账号标识，不能把 ERP openId 臆造成达人参数；在后端支持 WorkBuddy 授权上下文自动映射前停止达人调用。
• 接口范围固定：仅执行路由表中的授权、creator、product、order、fulfillment、logistics、return/refund 和 analytics operation；不能借助通用 proxy 任意调用未收录的 TikTok 路径。
• multipart 上传限制：达人 Upload Shoppable Video File（affiliate_creator/202505/videos/video_files）和商品 Upload Product File（product/202309/files/upload）需要二进制 multipart/form-data，当前仅有官方参考，没有可执行上传脚本；达人接口还受授权映射阻塞。商品主图上传另有 upload_product_image.py 的 Base64 网关适配链路。
• 写操作需谨慎：商品创建、编辑、上下架、改价、改库存、删除/恢复和达人视频发布会改变店铺状态；先确认 openId、shop_cipher、商品/视频 ID 和请求体，再执行，不能因失败自动换参数连续试探。
• 店铺标识与路径：多店时必须显式提供正确的 shop_cipher；单店也应显式传入，可先调用 Get Authorized Shops 获取。不要自行传 app_key、sign、timestamp，由代理注入；网关 errcode=1005 表示对应路径尚未放行。
• 数据与结论边界：返回值是 TikTok Shop 官方接口或 LinkFox 网关透传数据，不保证字段在所有站点均可用；本能力不替代平台规则、财务核算、法律意见、客服裁决或人工运营决策。

工具选择指南

按用户目标先确定身份上下文（ERP 店铺或达人），再按读/写、单对象/列表、同步/异步和参数位置选择入口。相近需求按下表选择，必要时把候选入口和额外调用成本告知用户后再继续。

选择思路

• ERP 业务统一先确认授权店铺和 openId，再按功能使用 product、order、fulfillment、logistics、return-refund 或 analytics 的专用入口。
• 达人数据和可购物视频的归档请求形态保留 appType=creator，但不包含任何凭证或臆造账号标识；授权映射阻塞解除前不得调用，也不要切换到 ERP 商品或分析接口规避阻塞。
• 对同一结果既可用专用脚本又可用 proxy_call/proxy_call 时，默认使用具名脚本；只有需要完整 path/method 或复用已收录 operation 时才使用通用入口。
• 需要跨域编排时按数据依赖顺序执行：授权/选店 → shop_cipher → 订单/商品/仓库查询 → 履约或维护；每一步先检查当前 MCP 响应，再决定是否继续。

业务需求路由速查

路由表中的 reference 文件包含对应 operation 的完整参数、响应、错误码和官方示例。authorization/202309/shops 在每个 ERP 业务域中都保留了独立适配脚本，用于取得该域调用所需的 shop_cipher。

调用方式

1. 先按身份选择 ERP 店铺或 Creator，并从路由表打开对应 reference。
2. ERP 授权能力使用其专属 toolName；ERP 业务使用 tiktokShop/developerProxy，保留 reference 定义的 path、method、queryString 和字符串化 body。达人 operation 仅保留契约，授权映射阻塞解除前不得执行。
3. shop_cipher、路径参数、分页和请求体均严格按 reference 构造。写操作先展示目标与副作用并取得确认；异步查询每次均视为新的收费调用。
4. 本地商品图片可先运行 scripts/upload_product_image.py 生成 Base64 arguments，再由 Agent 调 proxy_call；脚本不联网、不读取凭证。

展示规则

1. 客观呈现：按接口返回展示字段、状态、时间和计数，区分网关 httpStatus 与 TikTok body 内 code / message，不把接口数据扩写成平台保证或法律/财务结论。
2. 来源标注：说明数据来自 TikTok Shop ERP 授权、商品、订单、履约、物流、售后、分析或达人接口，并在必要时标注接口版本（如订单 202507/202309、分析 202403）。
3. 敏感信息：授权响应中存在的凭证字段仅用于契约识别，不得读取后展示、保存或转发；shop_cipher 只在业务需要时展示。授权链接约 1 小时有效，过期时间字段是 Unix 时间戳。
4. 授权结果：店铺列表只展示 appType=erp 店铺的 openId、名称、区域等；授权链接和授权维护结果明确标记其 ERP 限定，凭证字段不得读取后展示、保存或转发。
5. 达人工作流：当前仅保留响应契约；授权映射阻塞解除后，预检展示 task_id、result 和 issues[]，只有 SUCCESS 才建议发布。发布状态区分 SUCCESS、FAIL、PROCESSING，不把异步任务创建当作发布完成。
6. 商品结果：刊登检查逐条展示 check_item 和 fail_reasons；搜索/详情展示商品 ID、标题、状态、SKU、价格、库存和更新时间；写操作返回失败时先确认商品 ID、SKU、仓库和店铺。
7. 订单与履约：订单列表优先展示订单号、状态、金额、创建/更新时间和分页游标；详情再展开地址、包裹和行项目。拆单结果优先展示 can_split、must_split 与原因，不能把拆单判断描述为已发货。
8. 仓库、售后、分析：仓库展示 id/name/type/effect_status/is_default 和地址摘要；拒因展示 reason_code 与本地化文本；视频分析展示 video_id、指标、时间窗、币种、排序和分页信息。
9. 不可用字段：空值、缺失值或接口未返回的字段标记为 N/A 或省略，不猜测默认值；分页游标只在响应明确返回时继续使用。
10. 错误处理：根据 HTTP 状态、errcode、TikTok code/message 给出可操作修正。1005 提示路径未白名单；ERP 401/过期由网关自动刷新一次。达人 operation 当前在调用前即因授权映射未确认而停止，不通过传入凭证尝试修复。
11. 不可执行限制：商品文件上传明确说明“需要 multipart、当前无脚本”；8 个达人 operation 明确说明授权映射阻塞，其中视频文件上传还受 multipart 限制。不伪造成功结果，也不把普通 JSON 示例当成可上传文件。

解决认证和积分问题

• MCP 或 proxy_call 缺失：停止调用，配置 LinkFox（https://mcp-tool-gateway.linkfox.com/mcp/any-tool）并重启或重载客户端。
• MCP 连接 401：提示重新登录 WorkBuddy、重载连接或联系 WorkBuddy 管理员；不得要求用户手填 Authorization。
• 代理成功但下游 JSON 为 401：按 WorkBuddy 自动授权或 TikTok 店铺/达人业务授权失败处理，不得加入 LinkFox Key/token。
• 下游 402 或积分不足：引导访问 https://agent.linkfox.com/；不得自动选套餐、下单、支付或轮询。403 和其他错误按业务 reference 处理。

积分消耗说明

用户会因积分消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对积分消耗量预期不足时，务必提醒用户，由用户决定是否继续。