Linkfox 亚马逊店铺运营

整合亚马逊店铺 SP-API，实现授权管理、订单处理、Listing 发布、定价查询、目录检索、报告下载、批量上传、买家反馈分析及A+内容管理。

Install

openclaw skills install @linkfox-ai/linkfox-amazon-store-operations

Linkfox 亚马逊店铺运营（Amazon Store Operations）

亚马逊店铺 SP-API 运营一站式 AI 工具集，整合 10 项子能力，覆盖授权与令牌、订单、Listing 刊登、定价、Catalog 目录、报告、Feeds 批量上传、买家反馈、文件上传与 A+ Content。各子能力完整参数、响应字段与错误码见 references/ 下对应文件，可执行脚本见 scripts/。

能力边界

✅ 能力范围

以下能力均经 tool_key amazon_sp_api（亚马逊 SP-API 网关 POST /spApi/developerProxy 转发上游 SP-API，授权类直连 POST /spApi/*）实现，整合 10 项子能力：

授权与令牌管理（linkfox-amazon-store-auth）：生成亚马逊店铺 OAuth 授权链接、查询已授权店铺列表、刷新令牌、查询指定店铺访问令牌；是所有下游 SP-API 操作的前置依赖（取 accessToken）。
订单管理（linkfox-amazon-store-orders）：订单列表检索、单笔订单详情、买家信息、收货地址、订单行项目、管制订单核验信息查询，以及发货状态更新、确认发货、管制订单核验状态更新（SP-API Orders）。
Listing 刊登管理（linkfox-amazon-store-listings）：单条/列表检索刊登、PATCH 部分更新、PUT 创建/全量更新、DELETE 删除刊登，查询 ASIN 刊登限制（是否可售）、Product Type 列表搜索与 JSON Schema 定义查询（SP-API Listings & Definitions）。
商品定价与比价（linkfox-amazon-store-pricing）：单条/批量获取 ASIN/SKU 定价、竞争性报价、Listing/Item 报价、购物车预期价（FOEP）与竞争摘要（SP-API Product Pricing，含 batch 接口）。
Catalog 目录检索（linkfox-amazon-store-catalog）：按 ASIN 获取商品目录详情、按关键词/标识符检索商品目录、查询商品所属类目节点，返回摘要/图片/销售排名等（SP-API Catalog Items）。
报告自动化（linkfox-amazon-store-report）：95+ 种卖家后台报告（库存/订单/销售流量/财务结算/FBA/Brand Analytics 等）的端到端获取——请求→轮询→下载→解压，并生成限时本机 HTTP 下载链接（SP-API Reports）。
Feeds 批量数据上传（linkfox-amazon-store-feeds）：库存或 Listing 批量文件的 Feed 文档创建、文件上传、Feed 任务创建、状态轮询、列表查询、取消与结果文档下载（SP-API Feeds）。
买家反馈洞察（linkfox-amazon-store-customer-feedback）：按 ASIN 或类目节点分析评论主题、评价趋势、退货原因与星级影响（MENTIONS / STAR_RATING_IMPACT）（SP-API Customer Feedback）。
文件预签名上传（linkfox-amazon-store-uploads）：创建上传目的地生成预签名 URL，再向该 URL 上传文件，供 A+ Content、Messaging 等下游 API 使用（SP-API Uploads）。
A+ Content 管理（linkfox-amazon-store-aplus-content）：A+ 文档检索、创建、获取、更新、ASIN 关联校验/全量替换、发布记录查询、审核提交与暂停展示（SP-API A+ Content Management）。
覆盖美国、英国、德国、日本、法国、意大利、西班牙等站点（marketplaceIds/marketplaceId 指定，region 取 NA/EU/FE 且须与授权区域一致）。

❌ 边界与限制

API Key 必需：所有工具均需环境变量 LINKFOX_AGENT_API_KEY（或 LINKFOXAGENT_API_KEY）；各子能力独立计费、独立限频。
授权前置：除 linkfox-amazon-store-auth 外，其余 9 项子能力均依赖店铺已授权——须先用 linkfox-amazon-store-auth（store_tokens.py / POST /spApi/storeTokens）取得 accessToken，并通过 check_auth_dependency.py 本地探测依赖是否就绪（未就绪以 exit 42 + DEPENDENCY_MISSING: 信号提示安装 linkfox-amazon-store-auth）。
计费约束：同一会话同一参数组合默认只调用一次（脚本带本地缓存）；失败或空结果不得自动改参数、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 skills-version.json 对应条目与 references 内 api.md 的 costToken 字段）。
不在范围内：选品/关键词/竞品/评论挖掘等选品调研（用 linkfox-amazon-product-selection 系列）；广告投放与管理（用 Amazon Ads 系列）；前台实时搜索/商品详情/前台评论（用 amazon_search / amazon_product_detail / amazon_reviews 系列）；物流与供应链规划、1688 找货源、其他平台运营、与平台或卖家的直接沟通、实时库存与订单的自动决策。
数据时效：SP-API 返回为亚马逊后台当前状态；报告类为按 dataStartTime/dataEndTime 拉取的历史快照；accessToken 约 1 小时过期，过期需 refresh_token.py 刷新或重新 store_tokens.py 获取。

工具选择指南

按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。

需求 / 用户说	默认推荐（子能力）	何时换用其他
授权/绑定亚马逊店铺、查已授权店铺、令牌过期	`linkfox-amazon-store-auth`	—
查订单列表 / 单笔订单详情 / 买家信息 / 收货地址 / 订单行	`linkfox-amazon-store-orders`	要批量下载历史订单报告用 `linkfox-amazon-store-report`（reportType 订单类）
确认发货 / 标记已发货 / 更新发货状态	`linkfox-amazon-store-orders`（confirm_shipment / update_shipment_status）	—
单条 Listing 改标题/价格/属性、新建/全量更新/删除刊登	`linkfox-amazon-store-listings`（PATCH/PUT/DELETE）	要批量上传/修改多条 Listing 文件用 `linkfox-amazon-store-feeds`（feedType=Listing 类）
查 ASIN 能不能卖 / 刊登限制	`linkfox-amazon-store-listings`（get_listings_restrictions）	—
Product Type 有哪些 / 某类型的字段 Schema	`linkfox-amazon-store-listings`（search/get_definitions_product_type）	—
查商品定价 / 这个 ASIN 多少钱 / 比价	`linkfox-amazon-store-pricing`（get_pricing / get_competitive_pricing）	要批量（≤20 ASIN/SKU）报价用 `post_item_offers_batch` / `post_listing_offers_batch`；要购物车预期价用 `post_featured_offer_expected_price_batch`；要竞争摘要用 `post_competitive_summary_batch`
批量查报价（多个 ASIN/SKU）	`linkfox-amazon-store-pricing`（post_item_offers_batch / post_listing_offers_batch）	仅 1 个用单条 `get_item_offers` / `get_listing_offers`
查商品目录 / 按 ASIN 查商品信息 / 关键词搜目录 / 类目节点	`linkfox-amazon-store-catalog`	要前台实时搜索结果（非店铺目录）用 amazon_search 系列（选品 skill）
下载卖家后台报告（库存/订单/销售流量/财务/FBA/Brand Analytics）	`linkfox-amazon-store-report`（get_report ⭐端到端）	要逐条查订单用 `linkfox-amazon-store-orders`
批量上传库存 / 批量改 Listing（Feed 文件）	`linkfox-amazon-store-feeds`（create_feed_document→upload→create_feed→get_feed）	单条 Listing 改用 `linkfox-amazon-store-listings`
查 Feed 处理状态 / 取消 Feed / 下载 Feed 结果	`linkfox-amazon-store-feeds`（get_feed / cancel_feed / get_feed_document）	—
这个 ASIN 评论主题/差评痛点/星级影响	`linkfox-amazon-store-customer-feedback`（get_item_review_topics，sortBy=STAR_RATING_IMPACT 看星级影响）	要前台逐条评论文本用 amazon_reviews 系列（选品 skill）；要类目级反馈用 `get_browse_node_review_topics`
这个 ASIN 评价趋势 / 类目评论趋势	`linkfox-amazon-store-customer-feedback`（get_item_review_trends / get_browse_node_review_trends）	—
退货原因 / 类目退货主题趋势	`linkfox-amazon-store-customer-feedback`（get_browse_node_return_topics / trends）	—
上传 A+ 图片 / Messaging 附件 / 生成预签名上传 URL	`linkfox-amazon-store-uploads`（create_upload_destination_for_resource→upload_to_destination）	—
A+ 页面检索/创建/获取/更新	`linkfox-amazon-store-aplus-content`	需先上传图片用 `linkfox-amazon-store-uploads` 取得 URL
A+ 关联 ASIN / 校验 ASIN / 审核提交 / 暂停展示 / 发布记录	`linkfox-amazon-store-aplus-content`	—

工具选择思路

重要：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参，从中调研出最合适的子能力，并推荐用户，让用户自己决定。
满足程度同等的前提下，向用户推荐"默认推荐子能力"。
单条 vs 批量：单条写操作优先 linkfox-amazon-store-listings；批量文件操作优先 linkfox-amazon-store-feeds。
店铺目录 vs 前台搜索：查自己店铺后台可售商品/类目用 linkfox-amazon-store-catalog；查前台实时 SERP/竞品用选品 skill 的 amazon_search 系列。

业务需求路由速查

按【工具选择指南】定到子能力后，下表查端点、脚本与 references 文件取参执行。所有 SP-API 业务调用统一经 POST ${LINKFOX_TOOL_GATEWAY}/spApi/developerProxy，请求体含 region + path（SP-API 相对路径，无前导 /）+ method + amzAccessToken（来自 linkfox-amazon-store-auth 的 store_tokens.py）+ 可选 queryString/body/contentType；授权类直连 POST /spApi/*。

子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（10 项）

amazon_sp_api

子能力	references 文件	端点	脚本
linkfox-amazon-store-auth	references/linkfox-amazon-store-auth.md	POST /spApi/authorizeUrl、/spApi/authorizedStores、/spApi/refreshToken、/spApi/storeTokens	authorize_url.py、authorized_stores.py、refresh_token.py、store_tokens.py
linkfox-amazon-store-orders	references/linkfox-amazon-store-orders.md	POST /spApi/developerProxy（orders/2026-01-01/、orders/v0/）	search_orders.py、get_order.py、get_order_address.py、get_order_buyer_info.py、get_order_items.py、get_order_items_buyer_info.py、get_order_regulated_info.py、update_shipment_status.py、update_verification_status.py、confirm_shipment.py
linkfox-amazon-store-listings	references/linkfox-amazon-store-listings.md	POST /spApi/developerProxy（listings/2021-08-01/、definitions/2020-09-01/）	get_listings_item.py、search_listings_items.py、patch_listings_item.py、put_listings_item.py、delete_listings_item.py、get_listings_restrictions.py、search_definitions_product_types.py、get_definitions_product_type.py
linkfox-amazon-store-pricing	references/linkfox-amazon-store-pricing.md	POST /spApi/developerProxy（products/pricing/v0/、batches/products/pricing/）	get_pricing.py、get_competitive_pricing.py、get_listing_offers.py、get_item_offers.py、post_item_offers_batch.py、post_listing_offers_batch.py、post_featured_offer_expected_price_batch.py、post_competitive_summary_batch.py
linkfox-amazon-store-catalog	references/linkfox-amazon-store-catalog.md	POST /spApi/developerProxy（catalog/2022-04-01/、catalog/v0/）	get_catalog_item.py、list_catalog_categories.py、search_catalog_items.py
linkfox-amazon-store-report	references/linkfox-amazon-store-report.md	POST /spApi/developerProxy（reports/2021-06-30/reports、/reports/{reportId}、/documents/{reportDocumentId}）	get_report.py（⭐端到端）、merge_report_type_values_from_cache.py（辅助）
linkfox-amazon-store-feeds	references/linkfox-amazon-store-feeds.md	POST /spApi/developerProxy（feeds/2021-06-30/documents、/feeds、/feeds/{feedId}）+ PUT 预签名 URL	create_feed_document.py、upload_feed_document.py、create_feed.py、get_feed.py、get_feeds.py、get_feed_document.py、cancel_feed.py
linkfox-amazon-store-customer-feedback	references/linkfox-amazon-store-customer-feedback.md	POST /spApi/developerProxy（customerFeedback/2024-06-01/items/{asin}/、/browseNodes/{browseNodeId}/）	get_item_review_topics.py、get_item_review_trends.py、get_item_browse_node.py、get_browse_node_review_topics.py、get_browse_node_review_trends.py、get_browse_node_return_topics.py、get_browse_node_return_trends.py
linkfox-amazon-store-uploads	references/linkfox-amazon-store-uploads.md	POST /spApi/developerProxy（uploads/2020-11-01/uploadDestinations/{resource}）+ PUT 预签名 URL	create_upload_destination_for_resource.py、upload_to_destination.py
linkfox-amazon-store-aplus-content	references/linkfox-amazon-store-aplus-content.md	POST /spApi/developerProxy（aplus/2020-11-01/contentDocuments/*、/contentPublishRecords、/contentAsinValidations）	search_content_documents.py、create_content_document.py、get_content_document.py、update_content_document.py、list_content_document_asin_relations.py、post_content_document_asin_relations.py、validate_content_document_asin_relations.py、search_content_publish_records.py、post_content_document_approval_submission.py、post_content_document_suspend_submission.py

各子能力脚本目录下另有共享模块（_spapi_<域>_common.py / _lf_output.py）与依赖检查脚本 check_auth_dependency.py，由业务脚本内部调用，不作为独立 CLI 使用。

调用方式

网关：${LINKFOX_TOOL_GATEWAY}/<端点>（默认 https://tool-gateway.linkfox.com，可用 LINKFOX_TOOL_GATEWAY 覆盖，兼容旧名 STORE_API_BASE_URL/SPAPI_BASE_URL），请求方式 POST、Content-Type application/json，认证 Header Authorization: <api_key>（api_key 从环境变量 LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件。
SP-API 请求体：业务接口统一 POST /spApi/developerProxy，JSON 体含 region（NA/EU/FE）、path（SP-API 相对路径，无前导 /）、method（GET/POST/PATCH/PUT/DELETE）、amzAccessToken（访问令牌）、可选 queryString/body/contentType；授权类直连 POST /spApi/authorizeUrl 等专用端点。
授权前置：首次或令牌过期时，先跑 linkfox-amazon-store-auth 的 store_tokens.py '{"region":"NA","sellerId":"A1..."}' 取 amzAccessToken，再传给下游业务脚本；业务脚本启动时会本地探测 check_auth_dependency.py，依赖缺失时以 exit 42 + DEPENDENCY_MISSING: 提示先安装 linkfox-amazon-store-auth。
Python 脚本：每项子能力对应 scripts/<脚本名>.py '<JSON 参数>' [--inline]（脚本名与端点见路由速查表）。脚本内部完成网关调用、鉴权与落盘。
输出策略（脚本默认行为）：始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill>-<timestamp>.json（<cwd> 为脚本执行时工作目录；<session> 取自环境变量 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错）；响应体 ≤ 8 KB 落盘后完整打印到 stdout，> 8 KB 仅打印摘要（顶层字段、常见计数、最大列表长度 + 前 3 条样本）；加 --inline 强制全量打印（同样落盘）。
读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq 或 PowerShell ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
完整参数：每个子能力的请求参数、响应字段、错误码、curl 示例见 references/<源skill>.md（文件内含该子能力 SKILL.md 正文与 api.md 全文）。

使用示例

以下按运营模块给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。region 取 NA/EU/FE（须与授权区域一致），marketplaceIds/marketplaceId 为站点 ID（美国 ATVPDKIKX0DER），sellerId 为卖家标识，amzAccessToken 由 linkfox-amazon-store-auth 的 store_tokens.py 取得。

授权层

1. 生成授权链接 / 取访问令牌（amazon_sp_api → authorize_url.py / store_tokens.py）

json

{"region": "NA", "sellerName": "My Store"}

出参：authorizeUrl（Amazon 授权链接）；store_tokens.py 出参 accessToken（约 1 小时过期）、refreshToken、tokenType、expiresIn、authRecordId。sellerName 必填，用于在已授权列表中识别账号。

订单层

2. 订单列表检索（amazon_sp_api → search_orders.py）

json

{"sellerId": "A1EC6SZ7XAMURH", "region": "NA", "marketplaceIds": ["ATVPDKIKX0DER"], "lastUpdatedAfter": "2026-05-01T00:00:00Z"}

出参：searchOrders（订单列表，含 AmazonOrderId/PurchaseDate/OrderStatus/OrderTotal/FulfillmentChannel 等）、paginationToken、developerProxy 的 errcode/httpStatus/body。lastUpdatedAfter/createdAfter 二选一，marketplaceIds ≤50。

Listing 刊登层

3. 创建/全量更新刊登（amazon_sp_api → put_listings_item.py）

json

{"sellerId": "A1BCDEFGHIJK2", "region": "NA", "sku": "My-Seller-SKU-001", "marketplaceIds": ["ATVPDKIKX0DER"], "productType": "LUGGAGE", "requirements": "LISTING", "attributes": {"item_name": [{"value": "Example Title", "marketplace_id": "ATVPDKIKX0DER"}]}}

出参：putResult（Amazon 返回的提交结果，含 sku/status/submissionId/issues）、httpStatus、errcode。marketplaceIds 官方约束 ≤1，requirements 必填（LISTING/LISTING_PRODUCT_ONLY/LISTING_OFFER_ONLY）。

定价层

4. 单条定价/比价（amazon_sp_api → get_pricing.py）

json

{"sellerId": "A1...", "region": "NA", "asin": "B08N5WRWNW", "marketplaceId": "ATVPDKIKX0DER", "itemType": "Asin", "asins": ["B08N5WRWNW"], "itemCondition": "New"}

出参：pricing（含 Identifier/Summary/Product，价格、竞品数、Buy Box 价等）、errcode/httpStatus/body。批量 ≤20 用 post_item_offers_batch.py；购物车预期价用 post_featured_offer_expected_price_batch.py（≤40）。

Catalog 目录层

5. 按 ASIN 查商品目录（amazon_sp_api → get_catalog_item.py）

json

{"sellerId": "A1...", "region": "NA", "asin": "B08N5WRWNW", "marketplaceIds": ["ATVPDKIKX0DER"], "includedData": ["summaries", "images"]}

出参：catalogItem（含 asin/summaries/images/attributes/salesRanks 等）、errcode/httpStatus/body。includedData 可选 summaries/images/attributes/salesRanks 等。

报告层

6. 端到端获取报告（amazon_sp_api → get_report.py ⭐）

json

{"sellerId": "A1EC6SZ7XAMURH", "region": "NA", "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA", "marketplaceIds": ["ATVPDKIKX0DER"]}

出参：reportId、processingStatus（IN_QUEUE/IN_PROGRESS/DONE/FATAL/CANCELLED）、reportDocumentId、downloadPath（解压后本地绝对路径）、extractedFileHttpUrl（限时本机 HTTP 直链，默认 300s）。支持 95+ 报告类型，详见 references/report-types.md 与 references/report-requests/。

Feeds 批量上传层

7. 创建 Feed 任务（amazon_sp_api → create_feed.py，需先 create_feed_document.py+upload_feed_document.py 上传文件）

json

{"sellerId": "A1EC6SZ7XAMURH", "region": "NA", "feedType": "POST_FLAT_FILE_INVLOADER_DATA", "marketplaceIds": ["ATVPDKIKX0DER"], "inputFeedDocumentId": "amzn1.tdoc.1.1.xxx"}

出参：feedId、processingStatus（IN_QUEUE/IN_PROGRESS/DONE/FATAL/CANCELLED）、resultFeedDocumentId、errcode/httpStatus。流程：create_feed_document 取 url → upload_feed_document PUT 上传 → create_feed 建任务 → get_feed 轮询 → get_feed_document 取结果。

买家反馈层

8. ASIN 评论主题（amazon_sp_api → get_item_review_topics.py）

json

{"sellerId": "A1...", "region": "NA", "asin": "B0...", "marketplaceId": "ATVPDKIKX0DER", "sortBy": "MENTIONS"}

出参：itemReviewTopics（评论主题及频次/星级影响）、errcode/httpStatus/body。sortBy 必填 MENTIONS（提及量）或 STAR_RATING_IMPACT（星级影响）；要趋势用 get_item_review_trends.py，类目级用 get_browse_node_review_topics.py（需先 get_item_browse_node.py 反查 browseNodeId）。

文件上传层

9. 创建上传目的地（amazon_sp_api → create_upload_destination_for_resource.py → upload_to_destination.py）

json

{"sellerId": "A1...", "region": "NA", "resource": "aplus/2020-11-01/contentDocuments", "marketplaceId": "ATVPDKIKX0DER", "filePath": "/path/to/banner.jpg", "contentType": "image/jpeg"}

出参：uploadDestination（含 uploadDestinationId/url/headers）、errcode/httpStatus。contentMD5 可由 filePath/content/contentBase64 自动计算；步骤 2 upload_to_destination.py 向返回的预签名 url PUT 文件（带 headers）。

A+ Content 层

10. 获取 A+ 文档详情（amazon_sp_api → get_content_document.py）

json

{"sellerId": "A1...", "region": "NA", "marketplaceId": "ATVPDKIKX0DER", "contentReferenceKey": "YOUR_KEY", "includedDataSet": ["CONTENTS", "METADATA"]}

出参：contentDocument（文档内容与元数据）、contentReferenceKey、warnings、errcode/httpStatus/body。includedDataSet 必填 ≥1（CONTENTS/METADATA）；创建/更新用 create_content_document.py/update_content_document.py，提交审核用 post_content_document_approval_submission.py。

展示规则

客观呈现数据：以清晰表格展示查询/操作结果，不做主观商业建议（除非用户主动要求）；展示价格/金额时务必提示币种与站点（响应字段标明本地币种与 marketplace）。
来源标注：展示数据时说明来自哪个 SP-API 模块（Orders/Listings/Pricing/Catalog/Reports/Feeds/Customer Feedback/Uploads/A+ Content/Auth）。
不可用数据：值为 0/-1/null 的字段表示数据不可用，标注"N/A"或省略，不作实际值展示。
写操作确认：Listing/Feeds/A+/订单发货等写操作（PATCH/PUT/POST/DELETE）执行前向用户确认关键参数（sellerId、sku、ASIN、marketplaceIds、reportType、feedType 等），避免误改误删；写操作多为异步，展示 submissionId/feedId/reportId/processingStatus 并提示需轮询确认最终结果。
错误处理与协同：查询失败时根据响应 errcode/errmsg/httpStatus 说明原因并建议修正（ASIN/SKU 格式、region 与授权区不一致、path 白名单未放行 1005、参数越界、令牌过期需刷新等）；连续使用多模块时将各结果汇总为连贯分析，标注数据来源与时间窗。

解决认证和积分问题

异常情况：未配置 LINKFOX_AGENT_API_KEY/LINKFOXAGENT_API_KEY；响应 401 或 402；消息含"积分余额不足/quota exceeded/insufficient balance/套餐到期/需充值"等；业务脚本 exit 42 且 stderr 含 DEPENDENCY_MISSING:（提示未安装 linkfox-amazon-store-auth）。

措施：优先用 skill 内 onboarding.md 引导；找不到则加载 /linkfox-onboarding skill（未安装先下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip 解压安装）。DEPENDENCY_MISSING: 时先安装并完成 linkfox-amazon-store-auth 店铺授权，再用 store_tokens.py 取得 amzAccessToken 后重试下游操作。