linkfox-amazon-store-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Amazon 店铺授权与管理

Amazon Store Authorization and Management

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

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

This skill is responsible for OAuth authorization of Amazon seller stores, authorized store list management, access token acquisition and refresh, and is a prerequisite for all downstream operations such as report pulling, inventory query, order synchronization, etc.

📌 Related skill: If the user needs to pull Amazon store reports (inventory / order / sales / financial reports, etc.), please switch to
linkfox-amazon-store-report
. This skill depends on the authorization and token capabilities provided by this skill.

Core Concepts

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

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

店铺名（
sellerName
）必填：调用

/spApi/authorizeUrl

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

令牌生命周期：

accessToken

通常 1 小时过期；

refreshToken

用于在不重新授权的前提下续签新的

accessToken

。

The Selling Partner API is the official interface provided by Amazon for sellers. This skill is responsible for OAuth 2.0 authorization process and token lifecycle management:

Authorization Process: Generate authorization URL → User completes authorization on Amazon → Amazon calls back with authorization code → System exchanges authorization code for tokens → Tokens are securely stored.

Store Name (
sellerName
) is Required: Before calling

/spApi/authorizeUrl

, you must ask the user for a clear, non-empty store name. It is used to mark the account in the "Authorized Stores List"; do not leave it blank or use an empty string.

Token Lifecycle:

accessToken

usually expires in 1 hour;

refreshToken

is used to renew a new

accessToken

without re-authorization.

Data Fields

Authorization URL Response

Field	Type	Description
authorizeUrl	string	让用户在浏览器打开的 Amazon 授权链接

Field	Type	Description
authorizeUrl	string	Amazon authorization link for the user to open in a browser

Authorized Store Item

Field	Type	Description
sellerId	string	Amazon Seller ID (Merchant ID)
sellerName	string	店铺名（授权时必填）
region	string	市场区域代码 NA / EU / FE

Field	Type	Description
sellerId	string	Amazon Seller ID (Merchant ID)
sellerName	string	Store name (required during authorization)
region	string	Market region code NA / EU / FE

Store Tokens

Field	Type	Description
accessToken	string	调用亚马逊开放接口的凭证
refreshToken	string	用于续签 accessToken
expiresIn	integer	accessToken 过期秒数
tokenType	string	通常为 "bearer"

Field	Type	Description
accessToken	string	Credential for calling Amazon open APIs
refreshToken	string	Used to renew accessToken
expiresIn	integer	Expiration time of accessToken in seconds
tokenType	string	Usually "bearer"

Supported Regions

Code	Name	Marketplaces
NA	北美	美国、加拿大、墨西哥
EU	欧洲	英国、德国、法国、意大利、西班牙、荷兰等
FE	远东	日本、澳大利亚、新加坡、印度

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

Code	Name	Marketplaces
NA	North America	United States, Canada, Mexico
EU	Europe	United Kingdom, Germany, France, Italy, Spain, Netherlands, etc.
FE	Far East	Japan, Australia, Singapore, India

The default region is NA. Use NA if the user does not specify a region.

API Usage

本 skill 经 LinkFox 网关调用店铺授权相关接口，详见

references/api.md

。

This skill calls store authorization-related interfaces via the LinkFox gateway. For details, see

references/api.md

Available Scripts

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

```
scripts/authorize_url.py
```
— Generate authorization URL for new stores (
```
sellerName
```
is required)
```
scripts/authorized_stores.py
```
— List all authorized stores
```
scripts/refresh_token.py
```
— Refresh access token for a specific store
```
scripts/store_tokens.py
```
— Query access token for a specific store (for downstream skills)

Usage Scenarios

Scenario 1: Authorize New Store

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

Steps：

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

User request: "I want to authorize my Amazon North America store"

Steps:

Ask for store name
sellerName
(if not provided by the user).
```
/spApi/authorizeUrl
```
requires
```
sellerName
```
to be a non-empty string; explain to the user that this is only a label for identifying the store in LinkFox, and it is recommended to keep it consistent with the name in Seller Central.
Call
```
/spApi/authorizeUrl
```
with
```
region
```
and
```
sellerName
```
Provide the returned
```
authorizeUrl
```
to the user and ask them to open it in a browser
User completes authorization on Amazon → Amazon calls back to the system → The system automatically saves the authorization
Optional: Call
```
/spApi/authorizedStores
```
to confirm successful authorization

Scenario 2: View Authorized Stores

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

Steps：

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

User request: "List my authorized Amazon stores"

Steps:

Call
```
/spApi/authorizedStores
```
Display the store list (sellerName / sellerId / region)
Sort by sellerId and region

Scenario 3: Refresh Expired Token

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

Steps：

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

User request: "My store's token has expired, help me refresh it"

Steps:

Call
```
/spApi/refreshToken
```
with
```
sellerId
```
(optional
```
region
```
)
Return the new
```
accessToken
```
/
```
refreshToken
```
The database automatically updates the token information

Scenario 4: Query Store Tokens

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

Steps：

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

User request: "Get the access token for store A123 in the North America region"

Steps:

Call
```
/spApi/storeTokens
```
with
```
sellerId
```
and
```
region
```
Return all token information (for downstream business calls)

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

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

Steps：

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

Why this workflow is critical：

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

When the user makes any request involving seller backend data (pulling reports, querying inventory, checking orders, etc.), this skill is responsible for the pre-workflow of "select store → get token", and the specific business is handled by the corresponding downstream skill.

Steps:

List authorized stores: Call
```
/spApi/authorizedStores
```
Ask the user to select a store: If there are multiple stores, ask the user to specify which one to use
Get the token for the selected store: Call
```
/spApi/storeTokens
```
with the
```
sellerId
```
and
```
region
```
of the selected store
Pass the
accessToken
to the downstream skill (e.g.,
```
linkfox-amazon-store-report
```
) to perform the specific operation

Why this workflow is critical:

Users may have authorized multiple stores in different regions at the same time
Tokens and permissions for each store are independent of each other
Calls must use tokens matching the store; skipping the "select store" step will lead to ambiguity and errors

Display Rules

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

Get store name before generating authorization link: If the user does not provide
```
sellerName
```
, you must ask for it first; do not call
```
/spApi/authorizeUrl
```
with an empty value.
Only present data: Display authorization results, store lists, and token information only; do not provide business suggestions.
Security awareness: Do not display the full
```
accessToken
```
/
```
refreshToken
```
in plain text; only show masked forms such as the first 10 characters.
Clear guidance: When returning the authorization link, clearly inform the user to open it in a browser and complete the authorization.
Error explanation: When authorization fails, explain the reason based on the error code and provide suggestions.
Success confirmation: Confirm with the user after authorization is completed, and optionally display basic information of the store.

Important Limitations

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

sellerName is required:
```
/spApi/authorizeUrl
```
must receive a non-empty
```
sellerName
```
; scripts and agents must verify this before calling.
Token validity period:
```
accessToken
```
expires in 1 hour and needs to be refreshed in a timely manner.
Region-specific: Each store authorization is bound to a specific region; separate authorization is required for different regions.
User isolation: Users can only view/manage stores they have authorized themselves.
Callback whitelist: The system callback URL must be added to the whitelist of the authorization party (Ziniao).

User Expression & Scenario Quick Reference

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

User Says	Scenario
"授权我的亚马逊店铺" / "Authorize my Amazon store"	新店铺授权
"看看已授权的亚马逊店铺" / "Show my authorized stores"	列出已授权店铺
"令牌过期了" / "My token expired"	刷新令牌
"获取 XXX 店铺的访问令牌" / "Get access token for store"	查询店铺令牌
"绑定我的亚马逊账号" / "Connect my Amazon seller account"	新店铺授权

Not applicable — 超出本 skill 的业务：

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

Boundary judgment：

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

Applicable — Authorization and token management scenarios:

User Says	Scenario
"Authorize my Amazon store" / "Authorize my Amazon store"	New store authorization
"Show my authorized Amazon stores" / "Show my authorized stores"	List authorized stores
"My token has expired" / "My token expired"	Refresh token
"Get access token for store XXX" / "Get access token for store"	Query store token
"Connect my Amazon seller account" / "Connect my Amazon seller account"	New store authorization

Not applicable — Business beyond the scope of this skill:

Pull Amazon reports → Please use
```
linkfox-amazon-store-report
```
Product listing management, order processing, inventory management, advertising → Handled by other skills

Boundary judgment:

This skill is only responsible for "authorization + store management + token management + preparing accessToken for downstream".
When the user wants to perform specific seller backend operations (such as pulling reports):
1. This skill executes the standard pre-workflow in Scenario 5
2. Then switch to the corresponding downstream skill to complete the business logic
Do not directly call specific Amazon open APIs bypassing this skill.

Quick Reference

Authorization & Token Management APIs

API	Path	Purpose	Auth Required
Get Authorization URL	/spApi/authorizeUrl	生成授权链接（需要 sellerName）	✅ Yes
List Authorized Stores	/spApi/authorizedStores	查询用户的店铺列表	✅ Yes
Refresh Token	/spApi/refreshToken	刷新访问令牌	✅ Yes
Query Store Tokens	/spApi/storeTokens	获取某店铺的令牌（给下游 skill 用）	✅ Yes

详细请求参数、响应结构、错误码，见

references/api.md

。完整授权流程图，见

references/authorization-flow.md

。快速上手示例，见

references/quick-start.md

。

Feedback：

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

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

按

references/api.md

中的规范调用 Feedback API，不要打断用户的主流程。

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

API	Path	Purpose	Auth Required
Get Authorization URL	/spApi/authorizeUrl	Generate authorization URL (requires sellerName)	✅ Yes
List Authorized Stores	/spApi/authorizedStores	Query user's store list	✅ Yes
Refresh Token	/spApi/refreshToken	Refresh access token	✅ Yes
Query Store Tokens	/spApi/storeTokens	Get token for a specific store (for downstream skills)	✅ Yes

For detailed request parameters, response structures, and error codes, see

references/api.md

. For the complete authorization flow chart, see

references/authorization-flow.md

. For quick start examples, see

references/quick-start.md

Feedback:

Automatically report feedback via the Feedback API when any of the following situations occur:

The function described by this skill does not match the actual behavior
The result of the skill does not match the user's intent
The user expresses dissatisfaction or appreciation for this skill
Any point you think can be improved

Call the Feedback API according to the specifications in

references/api.md

, and do not interrupt the user's main process.

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