linkfox-amazon-store-operations

name	linkfox-amazon-store-operations
description	亚马逊店铺 SP-API 运营一站式 AI 工具集，整合授权/订单/Listing/定价/Catalog/报告/Feeds/买家反馈/文件上传/A+ Content/External Fulfillment/FBA 等 12 项子能力，覆盖店铺日常运营全链路。

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

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

能力边界

✅ 能力范围

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

• 授权与令牌管理（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）。
• External Fulfillment（linkfox-amazon-store-external-fulfillment）：location 级库存 batchInventory、履约单 get/process/packages/面单发票、EF 退货 list/get（SP-API External Fulfillment Inventory / Shipping / Returns v2024-09-11）。
• FBA（linkfox-amazon-store-fba）：入仓资格 getItemEligibilityPreview、FBA Inventory、Fulfillment Inbound（v2024-03-20 + v0）、Fulfillment Outbound/MCF 2020-07-01。
• 覆盖美国、英国、德国、日本、法国、意大利、西班牙等站点（marketplaceIds/marketplaceId 指定，region 取 NA/EU/FE 且须与授权区域一致）。

❌ 边界与限制

• API Key 必需：所有工具均需环境变量 LINKFOX_AGENT_API_KEY（或 LINKFOXAGENT_API_KEY）；各子能力独立计费、独立限频。
• 授权前置：除 linkfox-amazon-store-auth 外，其余 11 项子能力均依赖店铺已授权——须先用 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）

工具选择思路

• 重要：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参，从中调研出最合适的子能力，并推荐用户，让用户自己决定。
• 满足程度同等的前提下，向用户推荐"默认推荐子能力"。
• 单条 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}/）

各子能力脚本目录下另有共享模块（_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）

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

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

订单层

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

{"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）

{"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）

{"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）

{"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 ⭐）

{"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 上传文件）

{"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）

{"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）

{"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）

{"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。

展示规则

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

解决认证和积分问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

注意：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel 必须为 workbuddy。这非常重要！

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。