Amazon 店铺授权与管理

本 skill 负责 亚马逊卖家店铺的 OAuth 授权、已授权店铺列表、访问令牌获取与刷新，是拉取报告、查询库存、同步订单等所有下游操作的前置依赖。

📌 Related skill：如果用户需要 拉取亚马逊店铺报告（库存 / 订单 / 销售 / 财务报告等），请切换到 linkfox-amazon-store-report。该 skill 依赖本 skill 提供的授权与令牌能力。

Core Concepts

Selling Partner API 是亚马逊为卖家提供的官方接口。本 skill 负责 OAuth 2.0 授权流程与令牌生命周期管理：

授权流程：生成授权 URL → 用户在 Amazon 完成授权 → Amazon 回调并附带授权码 → 系统用授权码换取令牌 → 令牌安全保存。

店铺名（sellerName）必填：调用 /spApi/authorizeUrl 前必须向用户询问并获取一个清晰、非空的店铺名。它用来在"已授权店铺列表"中标记该账号；不要留空或使用空白字符串。

令牌生命周期：accessToken 通常 1 小时过期；refreshToken 用于在不重新授权的前提下续签新的 accessToken。

Data Fields

Authorization URL Response

Authorized Store Item

Store Tokens

Supported Regions

默认区域为 NA。当用户未指定区域时，使用 NA。

API Usage

本 skill 经 LinkFox 网关调用店铺授权相关接口，详见 references/api.md。

Available Scripts

• scripts/authorize_url.py — 为新店铺生成授权 URL（sellerName 必填）
• scripts/authorized_stores.py — 列出所有已授权店铺
• scripts/refresh_token.py — 刷新某店铺的访问令牌
• scripts/store_tokens.py — 查询某店铺的访问令牌（供下游 skill 使用）

Usage Scenarios

Scenario 1: Authorize New Store

User request：「我要授权我的亚马逊北美站点」

Steps：

1. 询问店铺名 sellerName（若用户未提供）。/spApi/authorizeUrl 要求 sellerName 为非空字符串；向用户说明这只是在 LinkFox 里识别店铺的标签，建议与 Seller Central 后台名字保持一致。
2. 调用 /spApi/authorizeUrl，传入 region 与 sellerName
3. 把返回的 authorizeUrl 给用户，让其在浏览器中打开
4. 用户在 Amazon 完成授权 → Amazon 回调系统 → 系统自动保存授权
5. 可选：调用 /spApi/authorizedStores 确认授权成功

Scenario 2: View Authorized Stores

User request：「列一下我已授权的亚马逊店铺」

Steps：

1. 调用 /spApi/authorizedStores
2. 展示店铺列表（sellerName / sellerId / region）
3. 按 sellerId、region 排序

Scenario 3: Refresh Expired Token

User request：「我店铺的令牌过期了，帮我刷新」

Steps：

1. 调用 /spApi/refreshToken，传入 sellerId（可选 region）
2. 返回新的 accessToken / refreshToken
3. 数据库自动更新令牌信息

Scenario 4: Query Store Tokens

User request：「获取北美站点 A123 店铺的访问令牌」

Steps：

1. 调用 /spApi/storeTokens，传入 sellerId 与 region
2. 返回全部令牌信息（供下游业务调用）

Scenario 5: Prepare Tokens for Any Store Operation (Standard Preparation Workflow)

当用户提出任何涉及卖家后台数据的请求（拉报告、查库存、看订单等），本 skill 负责前置的"选店 → 取令牌"流程，具体业务由相应的下游 skill 接手。

Steps：

1. 列出已授权店铺：调用 /spApi/authorizedStores
2. 让用户选择店铺：如果有多家店铺，请用户明确选哪一家
3. 获取该店铺令牌：调用 /spApi/storeTokens，传入所选店铺的 sellerId 与 region
4. 把 accessToken 交给下游 skill（例如 linkfox-amazon-store-report）执行具体操作

Why this workflow is critical：

• 用户可能同时授权了多家不同区域的店铺
• 每家店铺的令牌与权限彼此独立
• 调用必须使用与店铺匹配的令牌，跳过"选店"会导致歧义和错误

Display Rules

1. 先有店铺名再生成授权链接：若用户未提供 sellerName，必须先问，不允许带空值调用 /spApi/authorizeUrl。
2. 只呈现数据：展示授权结果、店铺列表、令牌信息即可，不做业务建议。
3. 安全意识：不要明文显示完整的 accessToken/refreshToken，只展示前 10 个字符等掩码形式。
4. 清晰引导：返回授权链接时，明确告知用户在浏览器中打开并完成授权。
5. 错误说明：授权失败时，基于错误码解释原因并给出建议。
6. 成功确认：授权完成后与用户确认，可选择展示该店铺基本信息。

Important Limitations

• sellerName 必填：/spApi/authorizeUrl 必须传入非空 sellerName；脚本与 agent 在调用前务必校验。
• 令牌有效期：accessToken 1 小时过期，需及时刷新。
• 区域专属：每次店铺授权都与具体区域绑定，不同区域需分别授权。
• 用户隔离：用户只能查看/管理自己授权的店铺。
• 回调白名单：系统回调 URL 必须在授权方（紫鸟）处加白名单。

User Expression & Scenario Quick Reference

Applicable — 授权与令牌管理场景：

Not applicable — 超出本 skill 的业务：

• 拉取亚马逊报告 → 请使用 linkfox-amazon-store-report
• 产品 listing 管理、订单处理、库存管理、广告投放 → 由其他 skill 负责

Boundary judgment：

• 本 skill 只负责「授权 + 管店铺 + 管令牌 + 为下游准备 accessToken」。
• 当用户要做具体卖家后台业务（如拉报告）时：
  1. 本 skill 执行 Scenario 5 的标准前置流程
  2. 随后切换到对应下游 skill 完成业务逻辑
• 不要直接越过本 skill 去调具体 Amazon 开放接口。

Quick Reference

Authorization & Token Management APIs

详细请求参数、响应结构、错误码，见 references/api.md。完整授权流程图，见 references/authorization-flow.md。快速上手示例，见 references/quick-start.md。

Feedback：

当出现以下任一情况时，自动通过 Feedback API 上报反馈：

1. 本 skill 描述的功能与实际行为不符
2. skill 的结果与用户意图不符
3. 用户表达了对本 skill 的不满或赞赏
4. 任何你认为可以改进的点

按 references/api.md 中的规范调用 Feedback API，不要打断用户的主流程。

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.