{"id":"8d357ac2-6b61-4927-93d0-0819792075c1","entityType":"agent","slug":"clawhub-linkfox-ai-linkfox-amazon-store-operations","name":"Linkfox 亚马逊店铺运营","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linkfox-ai-linkfox-amazon-store-operations","canonicalPath":"/agent/clawhub-linkfox-ai-linkfox-amazon-store-operations","generatedAt":"2026-10-13T03:10:44.105Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:54:15.511Z","emptyReason":null},"description":"整合亚马逊店铺 SP-API，实现授权管理、订单处理、Listing 发布、定价查询、目录检索、报告下载、批量上传、买家反馈分析及A+内容管理。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 988 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-store-operations","sourceUrl":"https://clawhub.ai/linkfox-ai/linkfox-amazon-store-operations","homepage":"https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-store-operations","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linkfox-ai/linkfox-amazon-store-operations","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-store-operations","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Linkfox 亚马逊店铺运营 technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:54:15.511Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:54:15.511Z","emptyReason":null},"stars":null,"forks":null,"downloads":988,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.2.3","tractionLabel":"988 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:54:15.450Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T21:54:15.511Z","lastCrawledAt":"2026-10-11T21:54:15.450Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T21:54:15.450Z","lastVerifiedAt":null,"highlights":[{"version":"1.2.3","createdAt":"2026-08-14T14:47:28.603Z","changelog":"Update from 1.2.2 to 1.2.3","fileCount":225,"zipByteSize":489750},{"version":"1.2.2","createdAt":"2026-08-07T10:44:29.819Z","changelog":"Update from 1.2.1 to 1.2.2","fileCount":223,"zipByteSize":477614},{"version":"1.2.1","createdAt":"2026-08-05T08:59:42.602Z","changelog":"Update from 1.2.0 to 1.2.1","fileCount":223,"zipByteSize":477747},{"version":"1.2.0","createdAt":"2026-07-16T04:00:08.845Z","changelog":"Update from 1.0.1 to 1.2.0","fileCount":220,"zipByteSize":466867},{"version":"1.0.1","createdAt":"2026-07-16T03:29:58.889Z","changelog":"Update from 1.0.0 to 1.0.1","fileCount":220,"zipByteSize":466868},{"version":"1.0.0","createdAt":"2026-07-15T01:36:48.006Z","changelog":"Initial release","fileCount":221,"zipByteSize":468352}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-store-operations","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-store-operations` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/linkfox-ai/linkfox-amazon-store-operations before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-13T03:10:44.103Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-operations/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:54:15.511Z","emptyReason":null},"readme":"Skill: Linkfox 亚马逊店铺运营\n\nOwner: linkfox-ai\n\nSummary: 整合亚马逊店铺 SP-API，实现授权管理、订单处理、Listing 发布、定价查询、目录检索、报告下载、批量上传、买家反馈分析及A+内容管理。\n\nTags: latest:1.2.3\n\nVersion history:\n\nv1.2.3 | 2026-08-14T14:47:28.603Z | user\n\nUpdate from 1.2.2 to 1.2.3\n\nv1.2.2 | 2026-08-07T10:44:29.819Z | user\n\nUpdate from 1.2.1 to 1.2.2\n\nv1.2.1 | 2026-08-05T08:59:42.602Z | user\n\nUpdate from 1.2.0 to 1.2.1\n\nv1.2.0 | 2026-07-16T04:00:08.845Z | user\n\nUpdate from 1.0.1 to 1.2.0\n\nv1.0.1 | 2026-07-16T03:29:58.889Z | user\n\nUpdate from 1.0.0 to 1.0.1\n\nv1.0.0 | 2026-07-15T01:36:48.006Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.2.3: 225 files, 489750 bytes\n\nFiles: references/authorization-flow.md (13084b), references/linkfox-amazon-store-aplus-content.md (18222b), references/linkfox-amazon-store-auth.md (14451b), references/linkfox-amazon-store-catalog.md (8899b), references/linkfox-amazon-store-customer-feedback.md (9584b), references/linkfox-amazon-store-external-fulfillment.md (15783b), references/linkfox-amazon-store-fba.md (18685b), references/linkfox-amazon-store-feeds.md (11788b), references/linkfox-amazon-store-listings.md (41389b), references/linkfox-amazon-store-orders.md (15523b), references/linkfox-amazon-store-pricing.md (24167b), references/linkfox-amazon-store-report.md (19602b), references/linkfox-amazon-store-uploads.md (9692b), references/onboarding.md (2068b), references/quick-start.md (7115b), references/report-requests/accountHealthReport-2020-11-18.md (2723b), references/report-requests/b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.md (2731b), references/report-requests/b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.md (2670b), references/report-requests/endUserDataReport.md (3018b), references/report-requests/marketplaceAsinPageViewMetrics.md (3094b), references/report-requests/promotionReport.md (2938b), references/report-requests/README.md (7506b), references/report-requests/sellerCouponReport.md (2842b), references/report-requests/sellerSalesAndTrafficReport.md (3027b), references/report-requests/sellingPartnerMarketBasketAnalysisReport.md (3467b), references/report-requests/sellingPartnerRepeatPurchaseReport.md (2837b), references/report-requests/sellingPartnerSearchCatalogPerformanceReport.md (3184b), references/report-requests/sellingPartnerSearchQueryPerformanceReport.md (3194b), references/report-requests/sellingPartnerSearchTermsReport.md (2953b), references/report-requests/types/END_USER_DATA_REPORT.md (1751b), references/report-requests/types/FBA_BULK_INVOICE.md (4129b), references/report-requests/types/FEE_DISCOUNTS_REPORT.md (2793b), references/report-requests/types/GET_AFN_INVENTORY_DATA_BY_COUNTRY.md (2929b), references/report-requests/types/GET_AFN_INVENTORY_DATA.md (2656b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL.md (3340b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING.md (3130b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX.md (3090b), references/report-requests/types/GET_B2B_PRODUCT_OPPORTUNITIES_NOT_YET_ON_AMAZON.md (2044b), references/report-requests/types/GET_B2B_PRODUCT_OPPORTUNITIES_RECOMMENDED_FOR_YOU.md (1923b), references/report-requests/types/GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT.md (2021b), references/report-requests/types/GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT.md (1761b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT.md (2034b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT.md (2017b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT.md (1809b), references/report-requests/types/GET_CONVERGED_FLAT_FILE_PENDING_ORDERS_DATA.md (2645b), references/report-requests/types/GET_COUPON_PERFORMANCE_REPORT.md (1815b), references/report-requests/types/GET_CSV_MFN_PRIME_RETURNS_REPORT.md (3081b), references/report-requests/types/GET_DATE_RANGE_FINANCIAL_HOLDS_DATA.md (2919b), references/report-requests/types/GET_EASYSHIP_DOCUMENTS.md (2653b), references/report-requests/types/GET_EASYSHIP_PICKEDUP.md (2585b), references/report-requests/types/GET_EASYSHIP_WAITING_FOR_PICKUP.md (2657b), references/report-requests/types/GET_EPR_ANNUAL_REPORTS.md (2993b), references/report-requests/types/GET_EPR_MONTHLY_REPORTS.md (3016b), references/report-requests/types/GET_EPR_QUARTERLY_REPORTS.md (3011b), references/report-requests/types/GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA.md (2943b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_RETURNS_DATA.md (2816b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_PROMOTION_DATA.md (2894b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_REPLACEMENT_DATA.md (2768b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_SALES_DATA.md (2991b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_TAXES_DATA.md (2869b), references/report-requests/types/GET_FBA_FULFILLMENT_INBOUND_NONCOMPLIANCE_DATA.md (2769b), references/report-requests/types/GET_FBA_FULFILLMENT_LONGTERM_STORAGE_FEE_CHARGES_DATA.md (2911b), references/report-requests/types/GET_FBA_FULFILLMENT_REMOVAL_ORDER_DETAIL_DATA.md (2962b), references/report-requests/types/GET_FBA_FULFILLMENT_REMOVAL_SHIPMENT_DETAIL_DATA.md (2965b), references/report-requests/types/GET_FBA_INVENTORY_PLANNING_DATA.md (2846b), references/report-requests/types/GET_FBA_MYI_ALL_INVENTORY_DATA.md (2771b), references/report-requests/types/GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA.md (2772b), references/report-requests/types/GET_FBA_OVERAGE_FEE_CHARGES_DATA.md (2712b), references/report-requests/types/GET_FBA_RECOMMENDED_REMOVAL_DATA.md (2885b), references/report-requests/types/GET_FBA_REIMBURSEMENTS_DATA.md (2720b), references/report-requests/types/GET_FBA_STORAGE_FEE_CHARGES_DATA.md (2733b), references/report-requests/types/GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING.md (2948b), references/report-requests/types/GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL.md (3105b), references/report-requests/types/GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL.md (3082b), references/report-requests/types/GET_FLAT_FILE_ARCHIVED_ORDERS_DATA_BY_ORDER_DATE.md (3057b), references/report-requests/types/GET_FLAT_FILE_MFN_SKU_RETURN_ATTRIBUTES_REPORT.md (3133b), references/report-requests/types/GET_FLAT_FILE_OPEN_LISTINGS_DATA.md (3767b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING.md (3347b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING.md (3362b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_TAX.md (3295b)\n\nFile v1.2.3:SKILL.md\n\n---\nname: linkfox-amazon-store-operations\ndisplay_name: Linkfox 亚马逊店铺运营\ndisplay_name_en: LinkFox Amazon Store Operations\ndescription: 亚马逊店铺 SP-API 运营一站式 AI 工具集，整合授权/订单/Listing/定价/Catalog/报告/Feeds/买家反馈/文件上传/A+ Content/External Fulfillment/FBA 等 12 项子能力，覆盖店铺日常运营全链路。\ndescription_zh: 亚马逊店铺 SP-API 运营工具集，整合 12 项子能力：店铺授权与令牌管理、订单查询与发货确认、Listing 刊登与限制、定价与比价（含批量 FOEP/竞争摘要）、Catalog 目录检索、95+ 种后台报告下载、Feeds 批量上传、买家反馈洞察、文件预签名上传、A+ Content 管理、External Fulfillment（location 库存/履约单/面单发票/退货）、FBA（入仓资格/库存/Inbound/MCF）。经 LinkFox 网关调用 SP-API，需先授权取令牌。当用户需要亚马逊店铺运营、订单、Listing、定价、报告、批量上传、A+ 页面、买家反馈分析、External Fulfillment 或 FBA 入仓/库存/MCF 时触发。参数见 references/，脚本见 scripts/。\ndescription_en: One-stop Amazon store SP-API operations toolkit integrating 10 sub-capabilities: store OAuth authorization & token management, order query & shipment confirmation, Listings management (PATCH/PUT/DELETE/restrictions/Product Type definitions), product pricing & comparison (batch FOEP & competitive summary), Catalog retrieval, automated download of 95+ Seller Central report types (request→poll→download→extract), Feeds bulk data upload, customer feedback insights (review topics/trends/return reasons), presigned file upload, and A+ Content management. All routed through the LinkFox gateway POST /spApi/developerProxy to Amazon SP-API; requires prior store authorization to obtain an access token. Triggered when the user needs Amazon store operations, order management, listing, pricing, report download, bulk upload, A+ pages, or customer feedback analysis. Full params per sub-capability in references/, scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox 亚马逊店铺运营（Amazon Store Operations）\n\n亚马逊店铺 SP-API 运营一站式 AI 工具集，整合 **12 项子能力**，覆盖授权与令牌、订单、Listing 刊登、定价、Catalog 目录、报告、Feeds 批量上传、买家反馈、文件上传、A+ Content、External Fulfillment 与 FBA。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n\n以下能力均经 tool_key `amazon_sp_api`（亚马逊 SP-API 网关 `POST /spApi/developerProxy` 转发上游 SP-API，授权类直连 `POST /spApi/*`）实现，整合 12 项子能力：\n\n- **授权与令牌管理（linkfox-amazon-store-auth）**：生成亚马逊店铺 OAuth 授权链接、查询已授权店铺列表、刷新令牌、查询指定店铺访问令牌；是所有下游 SP-API 操作的前置依赖（取 `accessToken`）。\n- **订单管理（linkfox-amazon-store-orders）**：订单列表检索、单笔订单详情、买家信息、收货地址、订单行项目、管制订单核验信息查询，以及发货状态更新、确认发货、管制订单核验状态更新（SP-API Orders）。\n- **Listing 刊登管理（linkfox-amazon-store-listings）**：单条/列表检索刊登、PATCH 部分更新、PUT 创建/全量更新、DELETE 删除刊登，查询 ASIN 刊登限制（是否可售）、Product Type 列表搜索与 JSON Schema 定义查询（SP-API Listings & Definitions）。\n- **商品定价与比价（linkfox-amazon-store-pricing）**：单条/批量获取 ASIN/SKU 定价、竞争性报价、Listing/Item 报价、购物车预期价（FOEP）与竞争摘要（SP-API Product Pricing，含 batch 接口）。\n- **Catalog 目录检索（linkfox-amazon-store-catalog）**：按 ASIN 获取商品目录详情、按关键词/标识符检索商品目录、查询商品所属类目节点，返回摘要/图片/销售排名等（SP-API Catalog Items）。\n- **报告自动化（linkfox-amazon-store-report）**：95+ 种卖家后台报告（库存/订单/销售流量/财务结算/FBA/Brand Analytics 等）的端到端获取——请求→轮询→下载→解压，并生成限时本机 HTTP 下载链接（SP-API Reports）。\n- **Feeds 批量数据上传（linkfox-amazon-store-feeds）**：库存或 Listing 批量文件的 Feed 文档创建、文件上传、Feed 任务创建、状态轮询、列表查询、取消与结果文档下载（SP-API Feeds）。\n- **买家反馈洞察（linkfox-amazon-store-customer-feedback）**：按 ASIN 或类目节点分析评论主题、评价趋势、退货原因与星级影响（MENTIONS / STAR_RATING_IMPACT）（SP-API Customer Feedback）。\n- **文件预签名上传（linkfox-amazon-store-uploads）**：创建上传目的地生成预签名 URL，再向该 URL 上传文件，供 A+ Content、Messaging 等下游 API 使用（SP-API Uploads）。\n- **A+ Content 管理（linkfox-amazon-store-aplus-content）**：A+ 文档检索、创建、获取、更新、ASIN 关联校验/全量替换、发布记录查询、审核提交与暂停展示（SP-API A+ Content Management）。\n- **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）。\n- **FBA（linkfox-amazon-store-fba）**：入仓资格 getItemEligibilityPreview、FBA Inventory、Fulfillment Inbound（v2024-03-20 + v0）、Fulfillment Outbound/MCF 2020-07-01。\n- 覆盖美国、英国、德国、日本、法国、意大利、西班牙等站点（`marketplaceIds`/`marketplaceId` 指定，`region` 取 `NA`/`EU`/`FE` 且须与授权区域一致）。\n\n### ❌ 边界与限制\n\n- **API Key 必需**：所有工具均需环境变量 `LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）；各子能力独立计费、独立限频。\n- **授权前置**：除 `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`）。\n- **计费约束**：同一会话同一参数组合默认只调用一次（脚本带本地缓存）；失败或空结果不得自动改参数、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 `skills-version.json` 对应条目与 references 内 api.md 的 `costToken` 字段）。\n- **不在范围内**：选品/关键词/竞品/评论挖掘等选品调研（用 `linkfox-amazon-product-selection` 系列）；广告投放与管理（用 Amazon Ads 系列）；前台实时搜索/商品详情/前台评论（用 amazon_search / amazon_product_detail / amazon_reviews 系列）；物流与供应链规划、1688 找货源、其他平台运营、与平台或卖家的直接沟通、实时库存与订单的自动决策。\n- **数据时效**：SP-API 返回为亚马逊后台当前状态；报告类为按 `dataStartTime`/`dataEndTime` 拉取的历史快照；`accessToken` 约 1 小时过期，过期需 `refresh_token.py` 刷新或重新 `store_tokens.py` 获取。\n\n## 工具选择指南\n\n按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。\n\n| 需求 / 用户说 | 默认推荐（子能力） | 何时换用其他 |\n|---|---|---|\n| 授权/绑定亚马逊店铺、查已授权店铺、令牌过期 | `linkfox-amazon-store-auth` | — |\n| 查订单列表 / 单笔订单详情 / 买家信息 / 收货地址 / 订单行 | `linkfox-amazon-store-orders` | 要批量下载历史订单报告用 `linkfox-amazon-store-report`（reportType 订单类） |\n| 确认发货 / 标记已发货 / 更新发货状态 | `linkfox-amazon-store-orders`（confirm_shipment / update_shipment_status） | — |\n| 单条 Listing 改标题/价格/属性、新建/全量更新/删除刊登 | `linkfox-amazon-store-listings`（PATCH/PUT/DELETE） | 要批量上传/修改多条 Listing 文件用 `linkfox-amazon-store-feeds`（feedType=Listing 类） |\n| 查 ASIN 能不能卖 / 刊登限制 | `linkfox-amazon-store-listings`（get_listings_restrictions） | — |\n| Product Type 有哪些 / 某类型的字段 Schema | `linkfox-amazon-store-listings`（search/get_definitions_product_type） | — |\n| 查商品定价 / 这个 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` |\n| 批量查报价（多个 ASIN/SKU） | `linkfox-amazon-store-pricing`（post_item_offers_batch / post_listing_offers_batch） | 仅 1 个用单条 `get_item_offers` / `get_listing_offers` |\n| 查商品目录 / 按 ASIN 查商品信息 / 关键词搜目录 / 类目节点 | `linkfox-amazon-store-catalog` | 要前台实时搜索结果（非店铺目录）用 amazon_search 系列（选品 skill） |\n| 下载卖家后台报告（库存/订单/销售流量/财务/FBA/Brand Analytics） | `linkfox-amazon-store-report`（get_report ⭐端到端） | 要逐条查订单用 `linkfox-amazon-store-orders` |\n| 批量上传库存 / 批量改 Listing（Feed 文件） | `linkfox-amazon-store-feeds`（create_feed_document→upload→create_feed→get_feed） | 单条 Listing 改用 `linkfox-amazon-store-listings` |\n| 查 Feed 处理状态 / 取消 Feed / 下载 Feed 结果 | `linkfox-amazon-store-feeds`（get_feed / cancel_feed / get_feed_document） | — |\n| 这个 ASIN 评论主题/差评痛点/星级影响 | `linkfox-amazon-store-customer-feedback`（get_item_review_topics，sortBy=STAR_RATING_IMPACT 看星级影响） | 要前台逐条评论文本用 amazon_reviews 系列（选品 skill）；要类目级反馈用 `get_browse_node_review_topics` |\n| 这个 ASIN 评价趋势 / 类目评论趋势 | `linkfox-amazon-store-customer-feedback`（get_item_review_trends / get_browse_node_review_trends） | — |\n| 退货原因 / 类目退货主题趋势 | `linkfox-amazon-store-customer-feedback`（get_browse_node_return_topics / trends） | — |\n| 上传 A+ 图片 / Messaging 附件 / 生成预签名上传 URL | `linkfox-amazon-store-uploads`（create_upload_destination_for_resource→upload_to_destination） | — |\n| A+ 页面检索/创建/获取/更新 | `linkfox-amazon-store-aplus-content` | 需先上传图片用 `linkfox-amazon-store-uploads` 取得 URL |\n| A+ 关联 ASIN / 校验 ASIN / 审核提交 / 暂停展示 / 发布记录 | `linkfox-amazon-store-aplus-content` | — |\n| External Fulfillment location 库存查写 / Seller Flex Easy Ship 履约单 / 面单发票 / EF 退货 | `linkfox-amazon-store-external-fulfillment` | 普通订单用 `linkfox-amazon-store-orders`；Feed 批量库存用 `linkfox-amazon-store-feeds` |\n| FBA 入仓资格 / FBA 库存摘要 / Inbound Plan 入仓 / MCF 多渠道履约 | `linkfox-amazon-store-fba` | External Fulfillment 用 `linkfox-amazon-store-external-fulfillment`；普通订单用 orders |\n\n### 工具选择思路\n\n- **重要**：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参，从中调研出最合适的子能力，并推荐用户，让用户自己决定。\n- 满足程度同等的前提下，向用户推荐\"默认推荐子能力\"。\n- **单条 vs 批量**：单条写操作优先 `linkfox-amazon-store-listings`；批量文件操作优先 `linkfox-amazon-store-feeds`。\n- **店铺目录 vs 前台搜索**：查自己店铺后台可售商品/类目用 `linkfox-amazon-store-catalog`；查前台实时 SERP/竞品用选品 skill 的 amazon_search 系列。\n\n## 业务需求路由速查\n\n按【工具选择指南】定到子能力后，下表查端点、脚本与 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/*`。\n\n### 子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（10 项）\n\n**amazon_sp_api**\n\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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（辅助） |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| linkfox-amazon-store-external-fulfillment | references/linkfox-amazon-store-external-fulfillment.md | POST /spApi/developerProxy（externalFulfillment/inventory/2024-09-11/*、externalFulfillment/2024-09-11/shipments/*、externalFulfillment/2024-09-11/returns/*） | post_batch_inventory.py、get_shipments.py、get_shipment.py、process_shipment.py、create_packages.py、update_package.py、update_package_status.py、retrieve_shipping_options.py、generate_invoice.py、retrieve_invoice.py、generate_ship_labels.py、list_returns.py、get_return.py |\n| linkfox-amazon-store-fba | references/linkfox-amazon-store-fba.md | POST /spApi/developerProxy（fba/inbound/v1/*、fba/inventory/v1/*、fba/inbound/v0/*、inbound/fba/2024-03-20/*、fba/outbound/2020-07-01/*） | fba_api.py（统一入口）及 70 个 operation 脚本，见 capabilities |\n\n> 各子能力脚本目录下另有共享模块（`_spapi_<域>_common.py` / `_lf_output.py`）与依赖检查脚本 `check_auth_dependency.py`，由业务脚本内部调用，不作为独立 CLI 使用。\n\n## 调用方式\n\n- **网关**：`${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 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件。\n- **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` 等专用端点。\n- **授权前置**：首次或令牌过期时，先跑 `linkfox-amazon-store-auth` 的 `store_tokens.py '{\"region\":\"NA\",\"sellerId\":\"A1...\"}'` 取 `amzAccessToken`，再传给下游业务脚本；业务脚本启动时会本地探测 `check_auth_dependency.py`，依赖缺失时以 exit 42 + `DEPENDENCY_MISSING:` 提示先安装 `linkfox-amazon-store-auth`。\n- **Python 脚本**：每项子能力对应 `scripts/<脚本名>.py '' [--inline]`（脚本名与端点见路由速查表）。脚本内部完成网关调用、鉴权与落盘。\n- **输出策略（脚本默认行为）**：始终将完整响应写入 `/linkfox///data/-.json`（`` 为脚本执行时工作目录；`` 取自环境变量 `SESSION_ID`；禁止写入 /tmp，当前目录不可写则报错）；响应体 ≤ 8 KB 落盘后完整打印到 stdout，> 8 KB 仅打印摘要（顶层字段、常见计数、最大列表长度 + 前 3 条样本）；加 `--inline` 强制全量打印（同样落盘）。\n- **读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 PowerShell `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n- **完整参数**：每个子能力的请求参数、响应字段、错误码、curl 示例见 `references/<源skill>.md`（文件内含该子能力 SKILL.md 正文与 api.md 全文）。\n\n## 使用示例\n\n以下按运营模块给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。`region` 取 `NA`/`EU`/`FE`（须与授权区域一致），`marketplaceIds`/`marketplaceId` 为站点 ID（美国 `ATVPDKIKX0DER`），`sellerId` 为卖家标识，`amzAccessToken` 由 `linkfox-amazon-store-auth` 的 `store_tokens.py` 取得。\n\n### 授权层\n\n**1. 生成授权链接 / 取访问令牌（amazon_sp_api → authorize_url.py / store_tokens.py）**\n```json\n{\"region\": \"NA\", \"sellerName\": \"My Store\"}\n```\n出参：`authorizeUrl`（Amazon 授权链接）；`store_tokens.py` 出参 `accessToken`（约 1 小时过期）、`refreshToken`、`tokenType`、`expiresIn`、`authRecordId`。`sellerName` 必填，用于在已授权列表中识别账号。\n\n### 订单层\n\n**2. 订单列表检索（amazon_sp_api → search_orders.py）**\n```json\n{\"sellerId\": \"A1EC6SZ7XAMURH\", \"region\": \"NA\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"], \"lastUpdatedAfter\": \"2026-05-01T00:00:00Z\"}\n```\n出参：`searchOrders`（订单列表，含 AmazonOrderId/PurchaseDate/OrderStatus/OrderTotal/FulfillmentChannel 等）、`paginationToken`、developerProxy 的 `errcode`/`httpStatus`/`body`。`lastUpdatedAfter`/`createdAfter` 二选一，`marketplaceIds` ≤50。\n\n### Listing 刊登层\n\n**3. 创建/全量更新刊登（amazon_sp_api → put_listings_item.py）**\n```json\n{\"sellerId\": \"A1BCDEFGHIJK2\", \"region\": \"NA\", \"sku\": \"My-Seller-SKU-001\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"], \"productType\": \"LUGGAGE\", \"requirements\": \"LISTING\", \"attributes\": {\"item_name\": [{\"value\": \"Example Title\", \"marketplace_id\": \"ATVPDKIKX0DER\"}]}}\n```\n出参：`putResult`（Amazon 返回的提交结果，含 `sku`/`status`/`submissionId`/`issues`）、`httpStatus`、`errcode`。`marketplaceIds` 官方约束 ≤1，`requirements` 必填（`LISTING`/`LISTING_PRODUCT_ONLY`/`LISTING_OFFER_ONLY`）。\n\n### 定价层\n\n**4. 单条定价/比价（amazon_sp_api → get_pricing.py）**\n```json\n{\"sellerId\": \"A1...\", \"region\": \"NA\", \"asin\": \"B08N5WRWNW\", \"marketplaceId\": \"ATVPDKIKX0DER\", \"itemType\": \"Asin\", \"asins\": [\"B08N5WRWNW\"], \"itemCondition\": \"New\"}\n```\n出参：`pricing`（含 `Identifier`/`Summary`/`Product`，价格、竞品数、Buy Box 价等）、`errcode`/`httpStatus`/`body`。批量 ≤20 用 `post_item_offers_batch.py`；购物车预期价用 `post_featured_offer_expected_price_batch.py`（≤40）。\n\n### Catalog 目录层\n\n**5. 按 ASIN 查商品目录（amazon_sp_api → get_catalog_item.py）**\n```json\n{\"sellerId\": \"A1...\", \"region\": \"NA\", \"asin\": \"B08N5WRWNW\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"], \"includedData\": [\"summaries\", \"images\"]}\n```\n出参：`catalogItem`（含 `asin`/`summaries`/`images`/`attributes`/`salesRanks` 等）、`errcode`/`httpStatus`/`body`。`includedData` 可选 `summaries`/`images`/`attributes`/`salesRanks` 等。\n\n### 报告层\n\n**6. 端到端获取报告（amazon_sp_api → get_report.py ⭐）**\n```json\n{\"sellerId\": \"A1EC6SZ7XAMURH\", \"region\": \"NA\", \"reportType\": \"GET_MERCHANT_LISTINGS_ALL_DATA\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"]}\n```\n出参：`reportId`、`processingStatus`（IN_QUEUE/IN_PROGRESS/DONE/FATAL/CANCELLED）、`reportDocumentId`、`downloadPath`（解压后本地绝对路径）、`extractedFileHttpUrl`（限时本机 HTTP 直链，默认 300s）。支持 95+ 报告类型，详见 `references/report-types.md` 与 `references/report-requests/`。\n\n### Feeds 批量上传层\n\n**7. 创建 Feed 任务（amazon_sp_api → create_feed.py，需先 create_feed_document.py+upload_feed_document.py 上传文件）**\n```json\n{\"sellerId\": \"A1EC6SZ7XAMURH\", \"region\": \"NA\", \"feedType\": \"POST_FLAT_FILE_INVLOADER_DATA\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"], \"inputFeedDocumentId\": \"amzn1.tdoc.1.1.xxx\"}\n```\n出参：`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` 取结果。\n\n### 买家反馈层\n\n**8. ASIN 评论主题（amazon_sp_api → get_item_review_topics.py）**\n```json\n{\"sellerId\": \"A1...\", \"region\": \"NA\", \"asin\": \"B0...\", \"marketplaceId\": \"ATVPDKIKX0DER\", \"sortBy\": \"MENTIONS\"}\n```\n出参：`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`）。\n\n### 文件上传层\n\n**9. 创建上传目的地（amazon_sp_api → create_upload_destination_for_resource.py → upload_to_destination.py）**\n```json\n{\"sellerId\": \"A1...\", \"region\": \"NA\", \"resource\": \"aplus/2020-11-01/contentDocuments\", \"marketplaceId\": \"ATVPDKIKX0DER\", \"filePath\": \"/path/to/banner.jpg\", \"contentType\": \"image/jpeg\"}\n```\n出参：`uploadDestination`（含 `uploadDestinationId`/`url`/`headers`）、`errcode`/`httpStatus`。`contentMD5` 可由 `filePath`/`content`/`contentBase64` 自动计算；步骤 2 `upload_to_destination.py` 向返回的预签名 `url` PUT 文件（带 `headers`）。\n\n### A+ Content 层\n\n**10. 获取 A+ 文档详情（amazon_sp_api → get_content_document.py）**\n```json\n{\"sellerId\": \"A1...\", \"region\": \"NA\", \"marketplaceId\": \"ATVPDKIKX0DER\", \"contentReferenceKey\": \"YOUR_KEY\", \"includedDataSet\": [\"CONTENTS\", \"METADATA\"]}\n```\n出参：`contentDocument`（文档内容与元数据）、`contentReferenceKey`、`warnings`、`errcode`/`httpStatus`/`body`。`includedDataSet` 必填 ≥1（`CONTENTS`/`METADATA`）；创建/更新用 `create_content_document.py`/`update_content_document.py`，提交审核用 `post_content_document_approval_submission.py`。\n\n## 展示规则\n\n1. **客观呈现数据**：以清晰表格展示查询/操作结果，不做主观商业建议（除非用户主动要求）；展示价格/金额时务必提示币种与站点（响应字段标明本地币种与 marketplace）。\n2. **来源标注**：展示数据时说明来自哪个 SP-API 模块（Orders/Listings/Pricing/Catalog/Reports/Feeds/Customer Feedback/Uploads/A+ Content/Auth）。\n3. **不可用数据**：值为 `0`/`-1`/`null` 的字段表示数据不可用，标注\"N/A\"或省略，不作实际值展示。\n4. **写操作确认**：Listing/Feeds/A+/订单发货等写操作（PATCH/PUT/POST/DELETE）执行前向用户确认关键参数（sellerId、sku、ASIN、marketplaceIds、reportType、feedType 等），避免误改误删；写操作多为异步，展示 `submissionId`/`feedId`/`reportId`/`processingStatus` 并提示需轮询确认最终结果。\n5. **错误处理与协同**：查询失败时根据响应 `errcode`/`errmsg`/`httpStatus` 说明原因并建议修正（ASIN/SKU 格式、`region` 与授权区不一致、`path` 白名单未放行 `1005`、参数越界、令牌过期需刷新等）；连续使用多模块时将各结果汇总为连贯分析，标注数据来源与时间窗。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n**注意**：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel **必须**为 workbuddy。这非常重要！\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\nFile v1.2.3:references/report-requests/README.md\n\n# 报告请求与文档格式（按 GitHub schema 分文件）\n\n> 与 [amzn/selling-partner-api-models/schemas/reports](https://github.com/amzn/selling-partner-api-models/tree/main/schemas/reports) 中的 JSON Schema **一一对应**。\n\n## `reportType` 全覆盖（含无 JSON 的 Flat File）\n\n`references/report-types.md` 表格中的 **每一个** `reportType` 均有专页 → **[types/README.md](./types/README.md)**（109 个：`types/.md`）。 \n有 GitHub JSON 的条目会链回下表中的 `*.md`；其余条目给出最小 CreateReport 模板并指向 [Report type values](https://developer-docs.amazon.com/sp-api/docs/report-type-values)。\n\n## 索引（仅含官方 `schemas/reports/*.json`）\n\n| 文档 | 上游 Schema | 涉及 `reportType` |\n|------|-------------|-------------------|\n| [accountHealthReport-2020-11-18.md](./accountHealthReport-2020-11-18.md) | [`accountHealthReport-2020-11-18.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/accountHealthReport-2020-11-18.json) | 见专页（账户状况结果 JSON；`reportType` 以官方 Report Type Values 为准） |\n| [b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.md](./b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.md) | [`b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.json) | `GET_B2B_PRODUCT_OPPORTUNITIES_NOT_YET_ON_AMAZON` |\n| [b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.md](./b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.md) | [`b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.json) | `GET_B2B_PRODUCT_OPPORTUNITIES_RECOMMENDED_FOR_YOU` |\n| [endUserDataReport.md](./endUserDataReport.md) | [`endUserDataReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/endUserDataReport.json) | `END_USER_DATA_REPORT` |\n| [marketplaceAsinPageViewMetrics.md](./marketplaceAsinPageViewMetrics.md) | [`marketplaceAsinPageViewMetrics.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/marketplaceAsinPageViewMetrics.json) | `MARKETPLACE_ASIN_PAGE_VIEW_METRICS` |\n| [promotionReport.md](./promotionReport.md) | [`promotionReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/promotionReport.json) | `GET_PROMOTION_PERFORMANCE_REPORT` |\n| [sellerCouponReport.md](./sellerCouponReport.md) | [`sellerCouponReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellerCouponReport.json) | `GET_COUPON_PERFORMANCE_REPORT` |\n| [sellerSalesAndTrafficReport.md](./sellerSalesAndTrafficReport.md) | [`sellerSalesAndTrafficReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellerSalesAndTrafficReport.json) | `GET_SALES_AND_TRAFFIC_REPORT` |\n| [sellingPartnerMarketBasketAnalysisReport.md](./sellingPartnerMarketBasketAnalysisReport.md) | [`sellingPartnerMarketBasketAnalysisReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellingPartnerMarketBasketAnalysisReport.json) | `GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT`（搜索词见 `sellingPartnerSearchTermsReport`） |\n| [sellingPartnerRepeatPurchaseReport.md](./sellingPartnerRepeatPurchaseReport.md) | [`sellingPartnerRepeatPurchaseReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellingPartnerRepeatPurchaseReport.json) | `GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT` |\n| [sellingPartnerSearchCatalogPerformanceReport.md](./sellingPartnerSearchCatalogPerformanceReport.md) | [`sellingPartnerSearchCatalogPerformanceReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellingPartnerSearchCatalogPerformanceReport.json) | `GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT` |\n| [sellingPartnerSearchQueryPerformanceReport.md](./sellingPartnerSearchQueryPerformanceReport.md) | [`sellingPartnerSearchQueryPerformanceReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellingPartnerSearchQueryPerformanceReport.json) | `GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT` |\n| [sellingPartnerSearchTermsReport.md](./sellingPartnerSearchTermsReport.md) | [`sellingPartnerSearchTermsReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellingPartnerSearchTermsReport.json) | `GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT` |\n| [vendorCouponReport.md](./vendorCouponReport.md) | [`vendorCouponReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorCouponReport.json) | `GET_COUPON_PERFORMANCE_REPORT` |\n| [vendorForecastingReport.md](./vendorForecastingReport.md) | [`vendorForecastingReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorForecastingReport.json) | `GET_VENDOR_FORECASTING_REPORT` |\n| [vendorInventoryReport.md](./vendorInventoryReport.md) | [`vendorInventoryReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorInventoryReport.json) | `GET_VENDOR_INVENTORY_REPORT` |\n| [vendorNetPureProductMarginReport.md](./vendorNetPureProductMarginReport.md) | [`vendorNetPureProductMarginReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorNetPureProductMarginReport.json) | `GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT` |\n| [vendorRealTimeInventoryReport.md](./vendorRealTimeInventoryReport.md) | [`vendorRealTimeInventoryReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorRealTimeInventoryReport.json) | `GET_VENDOR_REAL_TIME_INVENTORY_REPORT` |\n| [vendorRealTimeSalesReport.md](./vendorRealTimeSalesReport.md) | [`vendorRealTimeSalesReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorRealTimeSalesReport.json) | `GET_VENDOR_REAL_TIME_SALES_REPORT` |\n| [vendorRealTimeTrafficReport.md](./vendorRealTimeTrafficReport.md) | [`vendorRealTimeTrafficReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorRealTimeTrafficReport.json) | `GET_VENDOR_REAL_TIME_TRAFFIC_REPORT` |\n| [vendorSalesReport.md](./vendorSalesReport.md) | [`vendorSalesReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorSalesReport.json) | `GET_VENDOR_SALES_REPORT` |\n| [vendorTrafficReport.md](./vendorTrafficReport.md) | [`vendorTrafficReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/vendorTrafficReport.json) | `GET_VENDOR_TRAFFIC_REPORT` |\n\n## 通用说明\n\n- **创建报告**：`references/api.md` 中的 `developerProxy` + `path=reports/2021-06-30/reports` + `method=POST`。\n- **本目录**：每个 `*.md` 对应一个 `*.json`，给出 `createReport` 请求体要点及 schema 摘要。\n- **未出现在上表中的 reportType**：见 **[types/](./types/)** 目录下按枚举命名的专页（全覆盖 `report-types.md`）。\n\nFile v1.2.3:references/report-requests/types/README.md\n\n# 按 `reportType` 全覆盖 — 请求说明专页\n\n本目录为 `references/report-types.md` 中**每一个**报告枚举提供一页说明：\n\n- 标注是否在 Amazon [`schemas/reports`](https://github.com/amzn/selling-partner-api-models/tree/main/schemas/reports) 有 JSON 结果 Schema，并链到 `references/report-requests/` 下对应专页。\n- 无独立 JSON 的类型：给出 **CreateReport 最小请求体** 与官方 [Report type values](https://developer-docs.amazon.com/sp-api/docs/report-type-values) 入口。\n- 每页顶部另有 **「官方说明」或「官方索引（Report type values）」**：从亚马逊各子类文档自动摘录；其中在 `report-requests/` 下**已有 GitHub Schema 专页**（`*.md` 与 `schemas/reports/*.json` 对应）的类型，仅保留 **Schema 链、Amazon 锚点、权限/站点类字段**，避免与专页中的 Schema 摘要、`reportOptions` 表重复。其余 Flat File 类型仍为完整「官方说明」。 \n 更新摘录：将 15 个子页 HTML 放入 `references/_spapi_docs_cache/`，运行 `scripts/merge_report_type_values_from_cache.py`（依赖见该脚本注释）。\n\n**共计**：109 个 `reportType`。\n\n## 索引\n\n| reportType | 分类（report-types.md） | 类型 | 专页 |\n|------------|-------------------------|------|------|\n| `FEE_DISCOUNTS_REPORT` | 1. Amazon Business Reports | Flat/XML（文档） | [FEE_DISCOUNTS_REPORT.md](./FEE_DISCOUNTS_REPORT.md) |\n| `GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT.md](./GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT.md) |\n| `GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT.md](./GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT.md) |\n| `GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT.md](./GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT.md) |\n| `GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT.md](./GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT.md) |\n| `GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT.md](./GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT.md) |\n| `GET_VENDOR_REAL_TIME_INVENTORY_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_REAL_TIME_INVENTORY_REPORT.md](./GET_VENDOR_REAL_TIME_INVENTORY_REPORT.md) |\n| `GET_VENDOR_REAL_TIME_TRAFFIC_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_REAL_TIME_TRAFFIC_REPORT.md](./GET_VENDOR_REAL_TIME_TRAFFIC_REPORT.md) |\n| `GET_VENDOR_REAL_TIME_SALES_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_REAL_TIME_SALES_REPORT.md](./GET_VENDOR_REAL_TIME_SALES_REPORT.md) |\n| `GET_VENDOR_SALES_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_SALES_REPORT.md](./GET_VENDOR_SALES_REPORT.md) |\n| `GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT.md](./GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT.md) |\n| `GET_VENDOR_TRAFFIC_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_TRAFFIC_REPORT.md](./GET_VENDOR_TRAFFIC_REPORT.md) |\n| `GET_VENDOR_FORECASTING_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_FORECASTING_REPORT.md](./GET_VENDOR_FORECASTING_REPORT.md) |\n| `GET_VENDOR_INVENTORY_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_INVENTORY_REPORT.md](./GET_VENDOR_INVENTORY_REPORT.md) |\n| `GET_SALES_AND_TRAFFIC_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_SALES_AND_TRAFFIC_REPORT.md](./GET_SALES_AND_TRAFFIC_REPORT.md) |\n| `GET_B2B_PRODUCT_OPPORTUNITIES_RECOMMENDED_FOR_YOU` | 3. B2B Product Opportunities | JSON Schema 专页 | [GET_B2B_PRODUCT_OPPORTUNITIES_RECOMMENDED_FOR_YOU.md](./GET_B2B_PRODUCT_OPPORTUNITIES_RECOMMENDED_FOR_YOU.md) |\n| `GET_B2B_PRODUCT_OPPORTUNITIES_NOT_YET_ON_AMAZON` | 3. B2B Product Opportunities | JSON Schema 专页 | [GET_B2B_PRODUCT_OPPORTUNITIES_NOT_YET_ON_AMAZON.md](./GET_B2B_PRODUCT_OPPORTUNITIES_NOT_YET_ON_AMAZON.md) |\n| `GET_XML_BROWSE_TREE_DATA` | 4. Browse Tree Reports | Flat/XML（文档） | [GET_XML_BROWSE_TREE_DATA.md](./GET_XML_BROWSE_TREE_DATA.md) |\n| `GET_EASYSHIP_DOCUMENTS` | 5. Easy Ship Reports | Flat/XML（文档） | [GET_EASYSHIP_DOCUMENTS.md](./GET_EASYSHIP_DOCUMENTS.md) |\n| `GET_EASYSHIP_PICKEDUP` | 5. Easy Ship Reports | Flat/XML（文档） | [GET_EASYSHIP_PICKEDUP.md](./GET_EASYSHIP_PICKEDUP.md) |\n| `GET_EASYSHIP_WAITING_FOR_PICKUP` | 5. Easy Ship Reports | Flat/XML（文档） | [GET_EASYSHIP_WAITING_FOR_PICKUP.md](./GET_EASYSHIP_WAITING_FOR_PICKUP.md) |\n| `GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL` | 6.1 FBA Shipments | Flat/XML（文档） | [GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL.md](./GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL.md) |\n| `GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING` | 6.1 FBA Shipments | Flat/XML（文档） | [GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING.md](./GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING.md) |\n| `GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX` | 6.1 FBA Shipments | Flat/XML（文档） | [GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX.md](./GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX.md) |\n| `GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_SALES_DATA` | 6.1 FBA Shipments | Flat/XML（文档） | [GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_SALES_DATA.md](./GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_SALES_DATA.md) |\n| `GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_PROMOTION_DATA` | 6.1 FBA Shipments | Flat/XML（文档） | [GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_PROMOTION_DATA.md](./GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_PROMOTION_DATA.md) |\n| `GET_FBA_FULFILLMENT_CUSTOMER_TAXES_DATA` | 6.1 FBA Shipments | Flat/XML（文档） | [GET_FBA_FULFILLMENT_CUSTOMER_TAXES_DATA.md](./GET_FBA_FULFILLMENT_CUSTOMER_TAXES_DATA.md) |\n| `GET_AFN_INVENTORY_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_AFN_INVENTORY_DATA.md](./GET_AFN_INVENTORY_DATA.md) |\n| `GET_AFN_INVENTORY_DATA_BY_COUNTRY` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_AFN_INVENTORY_DATA_BY_COUNTRY.md](./GET_AFN_INVENTORY_DATA_BY_COUNTRY.md) |\n| `GET_LEDGER_SUMMARY_VIEW_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_LEDGER_SUMMARY_VIEW_DATA.md](./GET_LEDGER_SUMMARY_VIEW_DATA.md) |\n| `GET_LEDGER_DETAIL_VIEW_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_LEDGER_DETAIL_VIEW_DATA.md](./GET_LEDGER_DETAIL_VIEW_DATA.md) |\n| `GET_RESERVED_INVENTORY_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_RESERVED_INVENTORY_DATA.md](./GET_RESERVED_INVENTORY_DATA.md) |\n| `GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA.md](./GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA.md) |\n| `GET_FBA_MYI_ALL_INVENTORY_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_FBA_MYI_ALL_INVENTORY_DATA.md](./GET_FBA_MYI_ALL_INVENTORY_DATA.md) |\n| `GET_RESTOCK_INVENTORY_RECOMMENDATIONS_REPORT` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_RESTOCK_INVENTORY_RECOMMENDATIONS_REPORT.md](./GET_RESTOCK_INVENTORY_RECOMMENDATIONS_REPORT.md) |\n| `GET_STRANDED_INVENTORY_UI_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_STRANDED_INVENTORY_UI_DATA.md](./GET_STRANDED_INVENTORY_UI_DATA.md) |\n| `GET_STRANDED_INVENTORY_LOADER_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_STRANDED_INVENTORY_LOADER_DATA.md](./GET_STRANDED_INVENTORY_LOADER_DATA.md) |\n| `GET_FBA_INVENTORY_PLANNING_DATA` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_FBA_INVENTORY_PLANNING_DATA.md](./GET_FBA_INVENTORY_PLANNING_DATA.md) |\n| `GET_REMOTE_FULFILLMENT_ELIGIBILITY` | 6.2 FBA Inventory | Flat/XML（文档） | [GET_REMOTE_FULFILLMENT_ELIGIBILITY.md](./GET_REMOTE_FULFILLMENT_ELIGIBILITY.md) |\n| `GET_FBA_STORAGE_FEE_CHARGES_DATA` | 6.3 FBA Fees & Charges | Flat/XML（文档） | [GET_FBA_STORAGE_FEE_CHARGES_DATA.md](./GET_FBA_STORAGE_FEE_CHARGES_DATA.md) |\n| `GET_FBA_OVERAGE_FEE_CHARGES_DATA` | 6.3 FBA Fees & Charges | Flat/XML（文档） | [GET_FBA_OVERAGE_FEE_CHARGES_DATA.md](./GET_FBA_OVERAGE_FEE_CHARGES_DATA.md) |\n| `GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA` | 6.3 FBA Fees & Charges | Flat/XML（文档） | [GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA.md](./GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA.md) |\n| `GET_FBA_FULFILLMENT_LONGTERM_STORAGE_FEE_CHARGES_DATA` | 6.3 FBA Fees & Charges | Flat/XML（文档） | [GET_FBA_FULFILLMENT_LONGTERM_STORAGE_FEE_CHARGES_DATA.md](./GET_FBA_FULFILLMENT_LONGTERM_STORAGE_FEE_CHARGES_DATA.md) |\n| `GET_FBA_FULFILLMENT_CUSTOMER_RETURNS_DATA` | 6.4 FBA Returns & Reimbursements | Flat/XML（文档） | [GET_FBA_FULFILLMENT_CUSTOMER_RETURNS_DATA.md](./GET_FBA_FULFILLMENT_CUSTOMER_RETURNS_DATA.md) |\n| `GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_REPLACEMENT_DATA` | 6.4 FBA Returns & Reimbursements | Flat/XML（文档） | [GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_REPLACEMENT_DATA.md](./GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_REPLACEMENT_DATA.md) |\n| `GET_FBA_REIMBURSEMENTS_DATA` | 6.4 FBA Returns & Reimbursements | Flat/XML（文档） | [GET_FBA_REIMBURSEMENTS_DATA.md](./GET_FBA_REIMBURSEMENTS_DATA.md) |\n| `GET_FBA_RECOMMENDED_REMOVAL_DATA` | 6.5 FBA Removals | Flat/XML（文档） | [GET_FBA_RECOMMENDED_REMOVAL_DATA.md](./GET_FBA_RECOMMENDED_REMOVAL_DATA.md) |\n| `GET_FBA_FULFILLMENT_REMOVAL_ORDER_DETAIL_DATA` | 6.5 FBA Removals | Flat/XML（文档） | [GET_FBA_FULFILLMENT_REMOVAL_ORDER_DETAIL_DATA.md](./GET_FBA_FULFILLMENT_REMOVAL_ORDER_DETAIL_DATA.md) |\n| `GET_FBA_FULFILLMENT_REMOVAL_SHIPMENT_DETAIL_DATA` | 6.5 FBA Removals | Flat/XML（文档） | [GET_FBA_FULFILLMENT_REMOVAL_SHIPMENT_DETAIL_DATA.md](./GET_FBA_FULFILLMENT_REMOVAL_SHIPMENT_DETAIL_DATA.md) |\n| `GET_FBA_FULFILLMENT_INBOUND_NONCOMPLIANCE_DATA` | 6.6 FBA Compliance | Flat/XML（文档） | [GET_FBA_FULFILLMENT_INBOUND_NONCOMPLIANCE_DATA.md](./GET_FBA_FULFILLMENT_INBOUND_NONCOMPLIANCE_DATA.md) |\n| `GET_FLAT_FILE_OPEN_LISTINGS_DATA` | 7. Inventory Reports | Flat/XML（文档） | [GET_FLAT_FILE_OPEN_LISTINGS_DATA.md](./GET_FLAT_FILE_OPEN_LISTINGS_DATA.md) |\n| `GET_MERCHANT_LISTINGS_ALL_DATA` | 7. Inventory Reports | Flat/XML（文档） | [GET_MERCHANT_LISTINGS_ALL_DATA.md](./GET_MERCHANT_LISTINGS_ALL_DATA.md) |\n| `GET_MERCHANT_LISTINGS_DATA` | 7. Inventory Reports | Flat/XML（文档） | [GET_MERCHANT_LISTINGS_DATA.md](./GET_MERCHANT_LISTINGS_DATA.md) |\n| `GET_MERCHANT_LISTINGS_INACTIVE_DATA` | 7. Inventory Reports | Flat/XML（文档） | [GET_MERCHANT_LISTINGS_INACTIVE_DATA.md](./GET_MERCHANT_LISTINGS_INACTIVE_DATA.md) |\n| `GET_MERCHANT_LISTINGS_DATA_BACK_COMPAT` | 7. Inventory Reports | Flat/XML（文档） | [GET_MERCHANT_LISTINGS_DATA_BACK_COMPAT.md](./GET_MERCHANT_LISTINGS_DATA_BACK_COMPAT.md) |\n| `GET_MERCHANT_LISTINGS_DATA_LITE` | 7. Inventory Reports | Flat/XML（文档） | [GET_MERCHANT_LISTINGS_DATA_LITE.md](./GET_MERCHANT_LISTINGS_DATA_LITE.md) |\n| `GET_MERCHANT_LISTINGS_DATA_LITER` | 7. Inventory Reports | Flat/XML（文档） | [GET_MERCHANT_LISTINGS_DATA_LITER.md](./GET_MERCHANT_LISTINGS_DATA_LITER.md) |\n| `GET_MERCHANT_CANCELLED_LISTINGS_DATA` | 7. Inventory Reports | Flat/XML（文档） | [GET_MERCHANT_CANCELLED_LISTINGS_DATA.md](./GET_MERCHANT_CANCELLED_LISTINGS_DATA.md) |\n| `GET_MERCHANTS_LISTINGS_FYP_REPORT` | 7. Inventory Reports | Flat/XML（文档） | [GET_MERCHANTS_LISTINGS_FYP_REPORT.md](./GET_MERCHANTS_LISTINGS_FYP_REPORT.md) |\n| `GET_PAN_EU_OFFER_STATUS` | 7. Inventory Reports | Flat/XML（文档） | [GET_PAN_EU_OFFER_STATUS.md](./GET_PAN_EU_OFFER_STATUS.md) |\n| `GET_MFN_PANEU_OFFER_STATUS` | 7. Inventory Reports | Flat/XML（文档） | [GET_MFN_PANEU_OFFER_STATUS.md](./GET_MFN_PANEU_OFFER_STATUS.md) |\n| `GET_REFERRAL_FEE_PREVIEW_REPORT` | 7. Inventory Reports | Flat/XML（文档） | [GET_REFERRAL_FEE_PREVIEW_REPORT.md](./GET_REFERRAL_FEE_PREVIEW_REPORT.md) |\n| `GET_FLAT_FILE_VAT_INVOICE_DATA_REPORT` | 8. Invoice Reports | Flat/XML（文档） | [GET_FLAT_FILE_VAT_INVOICE_DATA_REPORT.md](./GET_FLAT_FILE_VAT_INVOICE_DATA_REPORT.md) |\n| `GET_XML_VAT_INVOICE_DATA_REPORT` | 8. Invoice Reports | Flat/XML（文档） | [GET_XML_VAT_INVOICE_DATA_REPORT.md](./GET_XML_VAT_INVOICE_DATA_REPORT.md) |\n| `GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING` | 9. Order Reports | Flat/XML（文档） | [GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING.md](./GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING.md) |\n| `GET_ORDER_REPORT_DATA_INVOICING` | 9. Order Reports | Flat/XML（文档） | [GET_ORDER_REPORT_DATA_INVOICING.md](./GET_ORDER_REPORT_DATA_INVOICING.md) |\n| `GET_ORDER_REPORT_DATA_TAX` | 9. Order Reports | Flat/XML（文档） | [GET_ORDER_REPORT_DATA_TAX.md](./GET_ORDER_REPORT_DATA_TAX.md) |\n| `GET_ORDER_REPORT_DATA_SHIPPING` | 9. Order Reports | Flat/XML（文档） | [GET_ORDER_REPORT_DATA_SHIPPING.md](./GET_ORDER_REPORT_DATA_SHIPPING.md) |\n| `GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING` | 9. Order Reports | Flat/XML（文档） | [GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING.md](./GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING.md) |\n| `GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING` | 9. Order Reports | Flat/XML（文档） | [GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING.md](./GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING.md) |\n| `GET_FLAT_FILE_ORDER_REPORT_DATA_TAX` | 9. Order Reports | Flat/XML（文档） | [GET_FLAT_FILE_ORDER_REPORT_DATA_TAX.md](./GET_FLAT_FILE_ORDER_REPORT_DATA_TAX.md) |\n| `GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL` | 9. Order Reports | Flat/XML（文档） | [GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL.md](./GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL.md) |\n| `GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL` | 9. Order Reports | Flat/XML（文档） | [GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL.md](./GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL.md) |\n| `GET_FLAT_FILE_ARCHIVED_ORDERS_DATA_BY_ORDER_DATE` | 9. Order Reports | Flat/XML（文档） | [GET_FLAT_FILE_ARCHIVED_ORDERS_DATA_BY_ORDER_DATE.md](./GET_FLAT_FILE_ARCHIVED_ORDERS_DATA_BY_ORDER_DATE.md) |\n| `GET_XML_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL` | 9. Order Reports | Flat/XML（文档） | [GET_XML_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL.md](./GET_XML_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL.md) |\n| `GET_XML_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL` | 9. Order Reports | Flat/XML（文档） | [GET_XML_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL.md](./GET_XML_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL.md) |\n| `GET_FLAT_FILE_PENDING_ORDERS_DATA` | 9. Order Reports | Flat/XML（文档） | [GET_FLAT_FILE_PENDING_ORDERS_DATA.md](./GET_FLAT_FILE_PENDING_ORDERS_DATA.md) |\n| `GET_PENDING_ORDERS_DATA` | 9. Order Reports | Flat/XML（文档） | [GET_PENDING_ORDERS_DATA.md](./GET_PENDING_ORDERS_DATA.md) |\n| `GET_CONVERGED_FLAT_FILE_PENDING_ORDERS_DATA` | 9. Order Reports | Flat/XML（文档） | [GET_CONVERGED_FLAT_FILE_PENDING_ORDERS_DATA.md](./GET_CONVERGED_FLAT_FILE_PENDING_ORDERS_DATA.md) |\n| `GET_DATE_RANGE_FINANCIAL_HOLDS_DATA` | 10. Payment Reports | Flat/XML（文档） | [GET_DATE_RANGE_FINANCIAL_HOLDS_DATA.md](./GET_DATE_RANGE_FINANCIAL_HOLDS_DATA.md) |\n| `GET_SELLER_FEEDBACK_DATA` | 11. Performance Reports | Flat/XML（文档） | [GET_SELLER_FEEDBACK_DATA.md](./GET_SELLER_FEEDBACK_DATA.md) |\n| `GET_V1_SELLER_PERFORMANCE_REPORT` | 11. Performance Reports | Flat/XML（文档） | [GET_V1_SELLER_PERFORMANCE_REPORT.md](./GET_V1_SELLER_PERFORMANCE_REPORT.md) |\n| `GET_V2_SELLER_PERFORMANCE_REPORT` | 11. Performance Reports | Flat/XML（文档） | [GET_V2_SELLER_PERFORMANCE_REPORT.md](./GET_V2_SELLER_PERFORMANCE_REPORT.md) |\n| `GET_PROMOTION_PERFORMANCE_REPORT` | 11. Performance Reports | JSON Schema 专页 | [GET_PROMOTION_PERFORMANCE_REPORT.md](./GET_PROMOTION_PERFORMANCE_REPORT.md) |\n| `GET_COUPON_PERFORMANCE_REPORT` | 11. Performance Reports | JSON Schema 专页 | [GET_COUPON_PERFORMANCE_REPORT.md](./GET_COUPON_PERFORMANCE_REPORT.md) |\n| `END_USER_DATA_REPORT` | 12. Regulatory Compliance Reports | JSON Schema 专页 | [END_USER_DATA_REPORT.md](./END_USER_DATA_REPORT.md) |\n| `FBA_BULK_INVOICE` | 12. Regulatory Compliance Reports | Flat/XML（文档） | [FBA_BULK_INVOICE.md](./FBA_BULK_INVOICE.md) |\n| `MARKETPLACE_ASIN_PAGE_VIEW_METRICS` | 12. Regulatory Compliance Reports | JSON Schema 专页 | [MARKETPLACE_ASIN_PAGE_VIEW_METRICS.md](./MARKETPLACE_ASIN_PAGE_VIEW_METRICS.md) |\n| `GET_EPR_MONTHLY_REPORTS` | 12. Regulatory Compliance Reports | Flat/XML（文档） | [GET_EPR_MONTHLY_REPORTS.md](./GET_EPR_MONTHLY_REPORTS.md) |\n| `GET_EPR_QUARTERLY_REPORTS` | 12. Regulatory Compliance Reports | Flat/XML（文档） | [GET_EPR_QUARTERLY_REPORTS.md](./GET_EPR_QUARTERLY_REPORTS.md) |\n| `GET_EPR_ANNUAL_REPORTS` | 12. Regulatory Compliance Reports | Flat/XML（文档） | [GET_EPR_ANNUAL_REPORTS.md](./GET_EPR_ANNUAL_REPORTS.md) |\n| `GET_XML_RETURNS_DATA_BY_RETURN_DATE` | 13. Returns Reports | Flat/XML（文档） | [GET_XML_RETURNS_DATA_BY_RETURN_DATE.md](./GET_XML_RETURNS_DATA_BY_RETURN_DATE.md) |\n| `GET_FLAT_FILE_RETURNS_DATA_BY_RETURN_DATE` | 13. Returns Reports | Flat/XML（文档） | [GET_FLAT_FILE_RETURNS_DATA_BY_RETURN_DATE.md](./GET_FLAT_FILE_RETURNS_DATA_BY_RETURN_DATE.md) |\n| `GET_XML_MFN_PRIME_RETURNS_REPORT` | 13. Returns Reports | Flat/XML（文档） | [GET_XML_MFN_PRIME_RETURNS_REPORT.md](./GET_XML_MFN_PRIME_RETURNS_REPORT.md) |\n| `GET_CSV_MFN_PRIME_RETURNS_REPORT` | 13. Returns Reports | Flat/XML（文档） | [GET_CSV_MFN_PRIME_RETURNS_REPORT.md](./GET_CSV_MFN_PRIME_RETURNS_REPORT.md) |\n| `GET_XML_MFN_SKU_RETURN_ATTRIBUTES_REPORT` | 13. Returns Reports | Flat/XML（文档） | [GET_XML_MFN_SKU_RETURN_ATTRIBUTES_REPORT.md](./GET_XML_MFN_SKU_RETURN_ATTRIBUTES_REPORT.md) |\n| `GET_FLAT_FILE_MFN_SKU_RETURN_ATTRIBUTES_REPORT` | 13. Returns Reports | Flat/XML（文档） | [GET_FLAT_FILE_MFN_SKU_RETURN_ATTRIBUTES_REPORT.md](./GET_FLAT_FILE_MFN_SKU_RETURN_ATTRIBUTES_REPORT.md) |\n| `GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE` | 14. Settlement/Payments Reports | Flat/XML（文档） | [GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE.md](./GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE.md) |\n| `GET_V2_SETTLEMENT_REPORT_DATA_XML` | 14. Settlement/Payments Reports | Flat/XML（文档） | [GET_V2_SETTLEMENT_REPORT_DATA_XML.md](./GET_V2_SETTLEMENT_REPORT_DATA_XML.md) |\n| `GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2` | 14. Settlement/Payments Reports | Flat/XML（文档） | [GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2.md](./GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2.md) |\n| `GST_MTR_STOCK_TRANSFER_REPORT` | 15. Tax Reports | Flat/XML（文档） | [GST_MTR_STOCK_TRANSFER_REPORT.md](./GST_MTR_STOCK_TRANSFER_REPORT.md) |\n| `GST_MTR_B2B` | 15. Tax Reports | Flat/XML（文档） | [GST_MTR_B2B.md](./GST_MTR_B2B.md) |\n| `GST_MTR_B2C` | 15. Tax Reports | Flat/XML（文档） | [GST_MTR_B2C.md](./GST_MTR_B2C.md) |\n| `GET_FLAT_FILE_SALES_TAX_DATA` | 15. Tax Reports | Flat/XML（文档） | [GET_FLAT_FILE_SALES_TAX_DATA.md](./GET_FLAT_FILE_SALES_TAX_DATA.md) |\n| `SC_VAT_TAX_REPORT` | 15. Tax Reports | Flat/XML（文档） | [SC_VAT_TAX_REPORT.md](./SC_VAT_TAX_REPORT.md) |\n| `GET_VAT_TRANSACTION_DATA` | 15. Tax Reports | Flat/XML（文档） | [GET_VAT_TRANSACTION_DATA.md](./GET_VAT_TRANSACTION_DATA.md) |\n| `GET_GST_MTR_B2B_CUSTOM` | 15. Tax Reports | Flat/XML（文档） | [GET_GST_MTR_B2B_CUSTOM.md](./GET_GST_MTR_B2B_CUSTOM.md) |\n| `GET_GST_MTR_B2C_CUSTOM` | 15. Tax Reports | Flat/XML（文档） | [GET_GST_MTR_B2C_CUSTOM.md](./GET_GST_MTR_B2C_CUSTOM.md) |\n| `GET_GST_STR_ADHOC` | 15. Tax Reports | Flat/XML（文档） | [GET_GST_STR_ADHOC.md](./GET_GST_STR_ADHOC.md) |\n\nFile v1.2.3:_meta.json\n\n{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-amazon-store-operations\",\n \"version\": \"1.2.3\",\n \"publishedAt\": 1786718848603\n}\n\nFile v1.2.3:references/authorization-flow.md\n\n# 亚马逊店铺授权流程详细说明\n\n本文档提供所有授权相关接口的详细说明，包括请求参数、返回值、错误处理等。\n\n---\n\n## 1. 获取授权URL\n\n### 接口信息\n\n- **路径**: `/spApi/authorizeUrl`\n- **方法**: POST (RouteMapping)\n- **鉴权**: 需要（从 Token 中获取 userId）\n- **实现**: `SpApiController.java:52`\n\n### 请求参数 (SpApiAuthorizeUrlReq)\n\n| 参数 | 类型 | 必填 | 说明 | 示例 |\n|------|------|------|------|------|\n| region | String | ✅ 是 | 区域代码：NA/EU/FE | \"NA\" |\n| sellerName | String | ✅ **是（必填）** | 店铺名 / 卖家展示名称，用于在已授权店铺列表中区分账号；**调用前必须向用户确认并传入非空字符串**，不可省略 | \"My Amazon Store\" |\n| central | String | ❌ 否 | 中心站点 | - |\n| marketplace | String | ❌ 否 | 市场代码 | - |\n\n### 返回结果 (SpApiAuthorizeUrlVo)\n\n```json\n{\n \"authorizeUrl\": \"https://sellercentral.amazon.com/...\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| authorizeUrl | String | 亚马逊授权链接，用户需在浏览器中打开 |\n\n### 业务逻辑\n\n1. 校验 region 参数（必须为 NA/EU/FE）；**本 Skill 约定**：`sellerName` 须为非空字符串（与用户在 LinkFox 侧展示、区分店铺一致），AI/脚本在调用前应向用户确认店铺名。\n2. 构建 state 参数：\n - 包含 gateway.url + /spApi/oauth/callback\n - 附加 userId, region, sellerName\n3. 调用紫鸟代理接口 `/developer-proxy/v1/authorize/url`\n4. 返回授权链接给用户\n\n### 错误码\n\n| 错误码 | 说明 | 处理建议 |\n|--------|------|----------|\n| 1002 | 缺少 region 参数 | 必须提供 region (NA/EU/FE) |\n| 1003 | 获取授权地址失败 | 检查网络连接和白名单配置，稍后重试 |\n\n### 使用示例\n\n**请求**:\n```json\n{\n \"region\": \"NA\",\n \"sellerName\": \"MyStore\"\n}\n```\n\n**响应**:\n```json\n{\n \"authorizeUrl\": \"https://sellercentral.amazon.com/apps/authorize/consent?application_id=xxx&state=xxx\"\n}\n```\n\n**后续操作**:\n用户在浏览器中打开 `authorizeUrl`，在亚马逊页面完成授权后，会自动重定向到回调地址。\n\n---\n\n## 2. 授权回调处理（服务端内部）\n\n### 接口信息\n\n- **路径**: 服务端内部回调接口（不对客户端/Agent暴露）\n- **方法**: POST (RouteMapping)\n- **鉴权**: 不需要（auth=false）\n- **实现**: `SpApiController.java:111`\n\n### 请求参数 (SpApiAuthorizeCallbackReq)\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| userId | String | ✅ 是 | 用户ID（从 state 中解析） |\n| sellingPartnerId | String | ✅ 是 | 亚马逊卖家ID |\n| accessToken | String | ✅ 是 | 访问令牌 |\n| refreshToken | String | ✅ 是 | 刷新令牌 |\n| tokenType | String | ❌ 否 | 令牌类型（默认 bearer） |\n| expiresIn | String | ❌ 否 | 过期时间（秒） |\n| region | String | ✅ 是 | 区域代码 |\n| sellerName | String | ❌ 否 | 卖家名称 |\n| mwsAuthToken | String | ❌ 否 | MWS 授权令牌 |\n\n### 返回结果 (SpApiAuthorizeCallbackVo)\n\n```json\n{\n \"saved\": true,\n \"authRecordId\": 123,\n \"bindUserId\": 456,\n \"message\": \"已新增授权\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| saved | Boolean | 是否保存成功 |\n| authRecordId | Long | 授权记录ID（sp_api_amazon_auth 表） |\n| bindUserId | Long | 绑定记录ID（sp_api_bind_user 表） |\n| message | String | 处理结果消息 |\n\n### 业务逻辑\n\n1. 检查是否已存在同一店铺的授权（sellingPartnerId + region）\n2. 如果存在，更新原有授权记录；否则新增\n3. 创建或更新用户与授权的绑定关系\n4. 返回保存结果\n\n### 注意事项\n\n- 此接口无需鉴权，因为是亚马逊重定向回调\n- userId 从 state 参数中解析，必须在获取授权URL时正确设置\n- 同一店铺的授权会更新而非重复创建\n\n---\n\n## 3. 查看已授权店铺列表\n\n### 接口信息\n\n- **路径**: `/spApi/authorizedStores`\n- **方法**: POST (RouteMapping)\n- **鉴权**: 需要（从 Token 中获取 userId）\n- **实现**: `SpApiController.java:126`\n\n### 请求参数\n\n无（从 Token 中自动获取当前用户 userId）\n\n### 返回结果 (SpApiAuthorizedStoresVo)\n\n```json\n{\n \"stores\": [\n {\n \"sellerName\": \"My Store\",\n \"sellerId\": \"A1234567890\",\n \"region\": \"NA\"\n },\n {\n \"sellerName\": \"EU Store\",\n \"sellerId\": \"A9876543210\",\n \"region\": \"EU\"\n }\n ],\n \"total\": 2\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| stores | Array | 店铺列表 |\n| stores[].sellerName | String | 卖家名称 |\n| stores[].sellerId | String | 卖家ID |\n| stores[].region | String | 区域代码 |\n| total | Integer | 店铺总数 |\n\n### 业务逻辑\n\n1. 根据 gatewayUserId 查询 sp_api_bind_user 表\n2. 获取所有关联的 amazonAuthId\n3. 查询对应的授权记录\n4. 去重并按 sellerId 和 region 排序\n5. 返回店铺列表\n\n### 错误码\n\n| 错误码 | 说明 | 处理建议 |\n|--------|------|----------|\n| 1002 | 无法识别当前用户 | 请重新登录 |\n\n---\n\n## 4. 刷新访问令牌\n\n### 接口信息\n\n- **路径**: `/spApi/refreshToken`\n- **方法**: POST (RouteMapping)\n- **鉴权**: 需要（从 Token 中获取 userId）\n- **实现**: `SpApiController.java:134`\n\n### 请求参数 (SpApiRefreshTokenReq)\n\n| 参数 | 类型 | 必填 | 说明 | 示例 |\n|------|------|------|------|------|\n| sellerId | String | ✅ 是 | 卖家ID | \"A1234567890\" |\n| region | String | ❌ 否 | 区域代码（用于精确匹配） | \"NA\" |\n\n### 返回结果 (SpApiRefreshTokenVo)\n\n```json\n{\n \"authRecordId\": 123,\n \"accessToken\": \"Atza|IwEBIA...\",\n \"refreshToken\": \"Atzr|IwEBIJ...\",\n \"tokenType\": \"bearer\",\n \"expiresIn\": \"3600\",\n \"message\": \"刷新成功并已更新数据库\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| authRecordId | Long | 授权记录ID |\n| accessToken | String | 新的访问令牌 |\n| refreshToken | String | 新的刷新令牌（可能更新） |\n| tokenType | String | 令牌类型 |\n| expiresIn | String | 过期时间（秒） |\n| message | String | 处理结果 |\n\n### 业务逻辑\n\n1. 根据 sellerId + region 查询授权记录\n2. 校验该授权是否属于当前用户\n3. 调用紫鸟代理接口 `/developer-proxy/{region}/auth/o2/token`\n4. 使用 refresh_token 换取新的 access_token\n5. 更新数据库中的令牌信息\n6. 返回新令牌\n\n### 错误码\n\n| 错误码 | 说明 | 处理建议 |\n|--------|------|----------|\n| 1002 | 请指定 sellerId | 必须提供卖家ID |\n| 1004 | 未找到授权记录或不属于当前用户 | 检查 sellerId 是否正确，或重新授权 |\n| 1004 | 缺少 refresh_token | 授权记录异常，需重新授权 |\n| 1003 | 刷新令牌请求失败 | 检查网络连接，稍后重试 |\n\n### 注意事项\n\n- refresh_token 可能在刷新时更新，需保存新的 refresh_token\n- 如果 region 未提供，会匹配该 sellerId 的第一条记录\n\n---\n\n## 5. 查询店铺令牌\n\n### 接口信息\n\n- **路径**: `/spApi/storeTokens`\n- **方法**: POST (RouteMapping)\n- **鉴权**: 需要（从 Token 中获取 userId）\n- **实现**: `SpApiController.java:142`\n\n### 请求参数 (SpApiStoreTokensReq)\n\n| 参数 | 类型 | 必填 | 说明 | 示例 |\n|------|------|------|------|------|\n| sellerId | String | ✅ 是 | 卖家ID | \"A1234567890\" |\n| region | String | ✅ 是 | 区域代码 | \"NA\" |\n\n### 返回结果 (SpApiStoreTokensVo)\n\n```json\n{\n \"sellerId\": \"A1234567890\",\n \"region\": \"NA\",\n \"authRecordId\": 123,\n \"accessToken\": \"Atza|IwEBIA...\",\n \"refreshToken\": \"Atzr|IwEBIJ...\",\n \"tokenType\": \"bearer\",\n \"expiresIn\": \"3600\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| sellerId | String | 卖家ID |\n| region | String | 区域代码 |\n| authRecordId | Long | 授权记录ID |\n| accessToken | String | 访问令牌 |\n| refreshToken | String | 刷新令牌 |\n| tokenType | String | 令牌类型 |\n| expiresIn | String | 过期时间（秒） |\n\n### 业务逻辑\n\n1. 根据 sellerId + region 查询授权记录\n2. 校验该授权是否属于当前用户\n3. 直接从数据库读取令牌信息（不调用刷新）\n4. 返回令牌数据\n\n### 错误码\n\n| 错误码 | 说明 | 处理建议 |\n|--------|------|----------|\n| 1002 | 请指定 sellerId 或 region | 必须同时提供卖家ID和区域 |\n| 1004 | 未找到授权记录或不属于当前用户 | 检查参数或重新授权 |\n\n### 使用场景\n\n- 在调用亚马逊卖家开放接口前获取访问令牌\n- 检查令牌是否即将过期（根据 expiresIn）\n- 如果令牌过期，调用 refreshToken 接口更新\n\n---\n\n## 区域与站点映射\n\n### 北美 (NA)\n\n- 美国: amazon.com\n- 加拿大: amazon.ca\n- 墨西哥: amazon.com.mx\n\n### 欧洲 (EU)\n\n- 英国: amazon.co.uk\n- 德国: amazon.de\n- 法国: amazon.fr\n- 意大利: amazon.it\n- 西班牙: amazon.es\n- 荷兰: amazon.nl\n- 瑞典: amazon.se\n- 波兰: amazon.pl\n\n### 远东 (FE)\n\n- 日本: amazon.co.jp\n- 澳大利亚: amazon.com.au\n- 新加坡: amazon.sg\n\n---\n\n## 数据库表结构\n\n### sp_api_amazon_auth (授权信息表)\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | Long | 主键 |\n| region | String | 区域代码 (NA/EU/FE) |\n| accessToken | String | 访问令牌 |\n| refreshToken | String | 刷新令牌 |\n| tokenType | String | 令牌类型 |\n| expiresIn | String | 过期时间（秒） |\n| sellingPartnerId | String | 卖家ID |\n| sellerName | String | 卖家名称 |\n| mwsAuthToken | String | MWS 授权令牌 |\n| createDate | Date | 创建时间 |\n| createTime | Long | 创建时间戳 |\n| lastUpdateDate | Date | 更新时间 |\n| lastUpdateTime | Long | 更新时间戳 |\n\n### sp_api_bind_user (用户绑定表)\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | Long | 主键 |\n| gatewayUserId | String | 网关用户ID |\n| amazonAuthId | Long | 授权记录ID（外键） |\n| createDate | Date | 创建时间 |\n| createTime | Long | 创建时间戳 |\n| lastUpdateDate | Date | 更新时间 |\n| lastUpdateTime | Long | 更新时间戳 |\n\n---\n\n## 完整授权示例\n\n### 步骤 1: 获取授权链接\n\n**请求**:\n```bash\nPOST /spApi/authorizeUrl\nHeaders: Authorization: Bearer \nBody: {\n \"region\": \"NA\",\n \"sellerName\": \"MyStore\"\n}\n```\n\n**响应**:\n```json\n{\n \"authorizeUrl\": \"https://sellercentral.amazon.com/apps/authorize/consent?...\"\n}\n```\n\n### 步骤 2: 用户授权\n\n用户在浏览器中打开 `authorizeUrl`，登录亚马逊卖家中心并同意授权。\n\n### 步骤 3: 自动回调\n\n亚马逊重定向到:\n```\nhttps:///spApi/oauth/callback?\n userId=&\n region=NA&\n sellerName=MyStore&\n selling_partner_id=A1234567890&\n access_token=Atza|...&\n refresh_token=Atzr|...&\n token_type=bearer&\n expires_in=3600\n```\n\n系统自动保存授权信息。\n\n### 步骤 4: 查看授权结果\n\n**请求**:\n```bash\nPOST /spApi/authorizedStores\nHeaders: Authorization: Bearer \n```\n\n**响应**:\n```json\n{\n \"stores\": [\n {\n \"sellerName\": \"MyStore\",\n \"sellerId\": \"A1234567890\",\n \"region\": \"NA\"\n }\n ],\n \"total\": 1\n}\n```\n\n### 步骤 5: 使用令牌调用卖家开放接口\n\n**请求**:\n```bash\nPOST /spApi/storeTokens\nHeaders: Authorization: Bearer \nBody: {\n \"sellerId\": \"A1234567890\",\n \"region\": \"NA\"\n}\n```\n\n**响应**:\n```json\n{\n \"accessToken\": \"Atza|...\",\n \"refreshToken\": \"Atzr|...\",\n \"expiresIn\": \"3600\"\n}\n```\n\n使用 `accessToken` 作为 `x-amz-access-token` header 调用亚马逊卖家开放接口。\n\n---\n\n## 故障排查\n\n### 问题 1: 授权链接无法访问\n\n**可能原因**:\n- 网络连接问题\n- 紫鸟代理服务异常\n- 白名单配置错误\n\n**解决方案**:\n1. 检查网络连接\n2. 确认白名单配置\n3. 稍后重试或联系技术支持\n\n### 问题 2: 回调未保存授权信息\n\n**可能原因**:\n- state 参数中缺少 userId\n- 数据库连接异常\n\n**解决方案**:\n1. 确认获取授权URL时正确传入用户信息\n2. 检查数据库连接\n3. 查看服务日志\n\n### 问题 3: 刷新令牌失败\n\n**可能原因**:\n- refresh_token 已过期或失效\n- 紫鸟代理服务异常\n\n**解决方案**:\n1. 如果 refresh_token 失效，需重新授权\n2. 检查紫鸟服务状态\n3. 确认白名单配置\n\n### 问题 4: 查询令牌返回 1004 错误\n\n**可能原因**:\n- sellerId 或 region 错误\n- 授权记录不属于当前用户\n\n**解决方案**:\n1. 调用 /spApi/authorizedStores 确认店铺信息\n2. 确认 sellerId 和 region 正确\n3. 如果确实未授权，需先完成授权流程\n\n---\n\n## 安全最佳实践\n\n1. **令牌存储**:\n - 令牌存储在数据库中，不暴露给前端\n - 仅通过后端接口访问令牌\n\n2. **访问控制**:\n - 所有接口都进行用户鉴权\n - 用户只能访问自己授权的店铺\n\n3. **令牌刷新**:\n - 定期检查令牌是否即将过期\n - 自动刷新即将过期的令牌\n\n4. **日志记录**:\n - 记录所有授权操作\n - 记录令牌刷新操作\n - 不记录令牌明文内容\n\n5. **错误处理**:\n - 不在错误消息中暴露敏感信息\n - 提供清晰的错误码和处理建议\n\nFile v1.2.3:references/linkfox-amazon-store-aplus-content.md\n\n---\nname: linkfox-amazon-store-aplus-content\ndescription: 亚马逊店铺 A+ Content（增强图文页）管理。支持 A+ 页面检索、创建、更新、ASIN 关联验证、审核提交与暂停展示等 SP-API A+ 功能。\n---\n\n# Amazon 店铺 A+ Content 管理\n\n本 skill 与 **`linkfox-amazon-store-auth`**、**`linkfox-amazon-store-listings`** 同属 Amazon Store 系列：使用 `POST /spApi/storeTokens` 取 `accessToken`，再经 `POST /spApi/developerProxy` 转发上游 SP-API A+ Content Management v2020-11-01。完整参数、响应与错误码见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- A+ 文档检索（`searchContentDocuments`）、创建（`createContentDocument`）、获取（`getContentDocument`）、更新（`updateContentDocument`）。\n- ASIN 关联管理：列出（`listContentDocumentAsinRelations`）、全量替换（`postContentDocumentAsinRelations`）、校验（`validateContentDocumentAsinRelations`）。\n- 发布记录查询（`searchContentPublishRecords`，按 ASIN）。\n- 提交审核发布（`postContentDocumentApprovalSubmission`）、暂停前台展示（`postContentDocumentSuspendSubmission`）。\n\n### ❌ 边界与限制\n\n- **前置依赖**：须先安装并完成 **`linkfox-amazon-store-auth`** 授权；本 skill 不内置授权逻辑。运行 `python scripts/check_auth_dependency.py`，若 exit code **42** 且 stderr 含 `DEPENDENCY_MISSING:`，请先安装该依赖。\n- **应用权限**：Seller Central 应用须具备 A+ Content 相关角色/权限，否则 **403**。\n- **网关白名单**：`aplus/2020-11-01/` 须在网关 developerProxy 放行；`errcode=1005` 需运维配置。\n- **内容结构**：`contentDocument` 结构复杂，须符合 Amazon 官方模型；本 skill 只做透传，不内置模板校验。\n- **marketplaceId 单数**：A+ 接口 Query 使用单数 `marketplaceId`（与 Listings 的 `marketplaceIds` 不同）。\n- **contentReferenceKey 非永久**：官方说明该 key 非永久链接，未来可能变化。\n- **不在范围内**：店铺授权与令牌管理（用 `linkfox-amazon-store-auth`）；Listing 与商品管理（用 `linkfox-amazon-store-listings`）；A+ 模板设计与内容创作建议；图片素材制作。\n\n## 执行流程\n\nA+ 内容管理通常为多步编排，按需选择下列步骤。\n\n### 步骤 1：前置依赖检查\n- 【输入】本 skill 所在目录\n- 【动作】运行 `python scripts/check_auth_dependency.py`，确认 `linkfox-amazon-store-auth` 已安装并完成授权\n- 【输出】依赖通过则继续；exit code 42 则先安装依赖\n\n### 步骤 2：获取 A+ 文档列表\n- 【输入】`sellerId`、`region`、`marketplaceId`（可选 `pageToken`）\n- 【动作】运行 `scripts/search_content_documents.py`，调用 `searchContentDocuments`\n- 【输出】文档元数据列表，获取目标文档的 `contentReferenceKey`\n\n### 步骤 3：获取或创建文档内容\n- 【输入】`contentReferenceKey`（获取）或 `contentDocument` 对象（创建）\n- 【动作】运行 `scripts/get_content_document.py`（含 `includedDataSet`：`CONTENTS`/`METADATA`）读取内容，或 `scripts/create_content_document.py` 新建\n- 【输出】完整 A+ 文档内容与元数据\n\n### 步骤 4：更新文档与 ASIN 关联\n- 【输入】`contentReferenceKey`、更新后的 `contentDocument`；关联所需的 `asinSet`\n- 【动作】按需运行 `scripts/update_content_document.py` 更新内容；`scripts/post_content_document_asin_relations.py` 全量替换关联 ASIN；`scripts/validate_content_document_asin_relations.py` 校验可用性\n- 【输出】更新结果与 ASIN 校验结果\n\n### 步骤 5：提交审核或暂停展示\n- 【输入】`contentReferenceKey`\n- 【动作】运行 `scripts/post_content_document_approval_submission.py` 提交审核发布，或 `scripts/post_content_document_suspend_submission.py` 暂停前台展示\n- 【输出】提交结果；可用 `scripts/search_content_publish_records.py`（按 `asin`）查询发布记录\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）。\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`。\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-amazon-store-aplus-content-.json`（`` 为脚本执行时的工作目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）。\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout。\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）。\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）。\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"\"\n\n# 搜索 A+ 文档列表\npython scripts/search_content_documents.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceId\":\"ATVPDKIKX0DER\"}'\n\n# 获取单篇文档（含内容与元数据）\npython scripts/get_content_document.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceId\":\"ATVPDKIKX0DER\",\"contentReferenceKey\":\"YOUR_KEY\",\"includedDataSet\":[\"CONTENTS\",\"METADATA\"]}'\n\n# 全量替换关联 ASIN\npython scripts/post_content_document_asin_relations.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceId\":\"ATVPDKIKX0DER\",\"contentReferenceKey\":\"YOUR_KEY\",\"asinSet\":[\"B0XXXXXXXXXX\"]}'\n\n# 按 ASIN 查发布记录\npython scripts/search_content_publish_records.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceId\":\"ATVPDKIKX0DER\",\"asin\":\"B0XXXXXXXXXX\"}'\n\n# 提交审核发布\npython scripts/post_content_document_approval_submission.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceId\":\"ATVPDKIKX0DER\",\"contentReferenceKey\":\"YOUR_KEY\"}'\n```\n\n## 展示规则\n\n1. 先展示网关 `errcode` / `httpStatus`；成功后再解析 `developerProxy.body` 或各脚本附带的 `*Response` 字段。\n2. 说明 `contentReferenceKey` 与前台「A+ ID」不一定一致。\n3. 写操作（创建/更新/关联/校验/提交/暂停）前确认用户意图；替换 ASIN 与暂停展示影响线上详情页。\n4. `postContentDocumentAsinRelations` 为全量替换 `asinSet`，从集合中移除 ASIN 会导致该 ASIN 上内容被 suspend，须提示用户。\n\n## 用户表达与场景速查\n\n**适用** —— 亚马逊店铺 A+ Content 管理：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"查一下我店铺的 A+ 页面\"、\"A+ 文档列表\" | 搜索 A+ 文档 |\n| \"新建一个 A+ 页面\"、\"创建 A+ Content\" | 创建文档 |\n| \"看下这个 A+ 的内容\"、\"获取 A+ 详情\" | 获取文档 |\n| \"更新 A+ 页面\"、\"修改 A+ Content\" | 更新文档 |\n| \"这个 A+ 关联了哪些 ASIN\"、\"给 A+ 加 ASIN\" | ASIN 关联管理 |\n| \"校验 A+ 能不能用这些 ASIN\" | ASIN 校验 |\n| \"这个 ASIN 的 A+ 发布记录\" | 发布记录查询 |\n| \"提交 A+ 审核\"、\"发布 A+ Content\" | 提交审核 |\n| \"暂停这个 A+ 的展示\" | 暂停展示 |\n\n不适用场景见上方【能力边界】。\n\n## 解决认证和积分问题\n\n发生以下异常情况时，采用以下措施来处理：\n\n### 异常情况\n- **未配置 API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应 401 或 402 状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n### 措施\n- 优先采用 skill 内的 onboarding.md 引导解决问题。\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个 skill 并根据它的引导来处理。如未安装请先安装：\n - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个 skill。\n\n---\n\n# Amazon 店铺 A+ Content Management API 参考（v2020-11-01）\n\n本文档描述通过 **LinkFox 店铺网关** 调用 Selling Partner API **A+ Content Management v2020-11-01**：`searchContentDocuments`、`createContentDocument`、`getContentDocument`、`updateContentDocument`、`listContentDocumentAsinRelations`、`postContentDocumentAsinRelations`、`validateContentDocumentAsinRelations`、`searchContentPublishRecords`、`postContentDocumentApprovalSubmission`、`postContentDocumentSuspendSubmission`。流程与 **`linkfox-amazon-store-report`** / **`linkfox-amazon-store-listings`** 一致：先 **`POST /spApi/storeTokens`**，再 **`POST /spApi/developerProxy`** 转发上游 **GET** 或 **POST**。\n\n> 官方参考：[searchContentDocuments](https://developer-docs.amazon.com/sp-api/reference/searchcontentdocuments) · [createContentDocument](https://developer-docs.amazon.com/sp-api/reference/createcontentdocument) · [getContentDocument](https://developer-docs.amazon.com/sp-api/reference/getcontentdocument) · [updateContentDocument](https://developer-docs.amazon.com/sp-api/reference/updatecontentdocument) · [listContentDocumentAsinRelations](https://developer-docs.amazon.com/sp-api/reference/listcontentdocumentasinrelations) · [postContentDocumentAsinRelations](https://developer-docs.amazon.com/sp-api/reference/postcontentdocumentasinrelations) · [validateContentDocumentAsinRelations](https://developer-docs.amazon.com/sp-api/reference/validatecontentdocumentasinrelations) · [searchContentPublishRecords](https://developer-docs.amazon.com/sp-api/reference/searchcontentpublishrecords) · [postContentDocumentApprovalSubmission](https://developer-docs.amazon.com/sp-api/reference/postcontentdocumentapprovalsubmission) · [postContentDocumentSuspendSubmission](https://developer-docs.amazon.com/sp-api/reference/postcontentdocumentsuspendsubmission)\n\n> ⚠️ **依赖**：需已安装 **`linkfox-amazon-store-auth`** 并完成店铺授权。\n\n---\n\n## 调用规范\n\n| 项 | 说明 |\n|----|------|\n| **Base URL** | `${LINKFOX_TOOL_GATEWAY}`（可用 `STORE_API_BASE_URL` 或 `SPAPI_BASE_URL` 覆盖） |\n| **网关认证** | Header `Authorization: `，环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\n| **店铺令牌** | `POST /spApi/storeTokens`，Body：`{\"sellerId\":\"...\",\"region\":\"NA\\|EU\\|FE\"}` → `accessToken` |\n| **SP-API 转发** | `POST /spApi/developerProxy` |\n\n---\n\n## `POST /spApi/developerProxy`\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| region | string | 是 | `NA` / `EU` / `FE` |\n| path | string | 是 | **不含**主机名；本 API 统一前缀 **`aplus/2020-11-01/...`**（见各节） |\n| method | string | 是 | **`GET`** 或 **`POST`**（A+ 的创建/更新/校验/关联/提交均为 **POST**） |\n| amzAccessToken | string | 是 | `storeTokens` 返回的 `accessToken` |\n| queryString | string | 视操作 | **无 `?` 前缀**；Query 键名与官方一致（注意单数 **`marketplaceId`**） |\n| body | string | 视操作 | **POST** 且带 JSON body 时，为 JSON 字符串；**GET** 不传 |\n| contentType | string | 视操作 | 有 body 时建议 **`application/json`** |\n\n**网关响应**（与其它店铺 skill 一致）：解析 **`errcode`**、**`httpStatus`**，再将 **`body`** 字符串 `JSON.parse`。\n\n### 白名单\n\n`path` 须在网关 **`sp-api.developer-proxy.allowed-path-prefixes`** 内。若 **`errcode=1005`**，需运维放行前缀（常见）：**`aplus/2020-11-01/`**。\n\n### 速率（文档默认值）\n\n各操作文档默认多为 **10 req/s**，burst **10**；以响应头 `x-amzn-RateLimit-Limit` 及账号实际配额为准。\n\n### 错误码\n\n- **401**：HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- **402**：HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n\n---\n\n## 路径与 Query 总览\n\n| 操作 | Method | `developerProxy.path` 模板 |\n|------|--------|---------------------------|\n| searchContentDocuments | GET | `aplus/2020-11-01/contentDocuments` |\n| createContentDocument | POST | `aplus/2020-11-01/contentDocuments` |\n| getContentDocument | GET | `aplus/2020-11-01/contentDocuments/{contentReferenceKey}` |\n| updateContentDocument | POST | `aplus/2020-11-01/contentDocuments/{contentReferenceKey}` |\n| listContentDocumentAsinRelations | GET | `aplus/2020-11-01/contentDocuments/{contentReferenceKey}/asins` |\n| postContentDocumentAsinRelations | POST | `aplus/2020-11-01/contentDocuments/{contentReferenceKey}/asins` |\n| validateContentDocumentAsinRelations | POST | `aplus/2020-11-01/contentAsinValidations` |\n| searchContentPublishRecords | GET | `aplus/2020-11-01/contentPublishRecords` |\n| postContentDocumentApprovalSubmission | POST | `aplus/2020-11-01/contentDocuments/{contentReferenceKey}/approvalSubmissions` |\n| postContentDocumentSuspendSubmission | POST | `aplus/2020-11-01/contentDocuments/{contentReferenceKey}/suspendSubmissions` |\n\n**Path 编码**：`contentReferenceKey` 等路径段须 **百分号编码**（脚本已处理）。\n\n---\n\n## searchContentDocuments（GET）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n| pageToken | 否 | 分页 |\n\n返回文档列表（**元数据**为主）；完整内容需 **`getContentDocument`**。\n\n---\n\n## createContentDocument（POST）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n\n| Body JSON | 必填 | 说明 |\n|-----------|------|------|\n| contentDocument | 是 | A+ 文档对象（结构以 Amazon 模型为准） |\n\n---\n\n## getContentDocument（GET）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n| includedDataSet | **是**（≥1） | 可重复键；取值：**`CONTENTS`**、**`METADATA`** |\n\n---\n\n## updateContentDocument（POST）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n\n| Body JSON | 必填 | 说明 |\n|-----------|------|------|\n| contentDocument | 是 | 更新后的 A+ 文档 |\n\n---\n\n## listContentDocumentAsinRelations（GET）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n| includedDataSet | 否 | 可选 **`METADATA`**；不传则通常仅返回关联 ASIN |\n| asinSet | 否 | 可重复；筛选指定 ASIN |\n| pageToken | 否 | 分页 |\n\n---\n\n## postContentDocumentAsinRelations（POST）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n\n| Body JSON | 必填 | 说明 |\n|-----------|------|------|\n| asinSet | 是 | **替换**该文档关联的全部 ASIN（官方语义为全量替换；移除 ASIN 会 suspend 该 ASIN 上的内容）。可为 **字符串数组**，或与官方 schema 一致的对象数组 |\n\n---\n\n## validateContentDocumentAsinRelations（POST）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n| asinSet | 否 | 可重复；待校验 ASIN 集合 |\n\n| Body JSON | 必填 | 说明 |\n|-----------|------|------|\n| contentDocument | 是 | 待校验的 A+ 文档 |\n\n---\n\n## searchContentPublishRecords（GET）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n| asin | 是 | ASIN，文档要求 **length ≥ 10** |\n| pageToken | 否 | 分页 |\n\n---\n\n## postContentDocumentApprovalSubmission（POST）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n\n**Body**：官方无必填 body；本仓库脚本 **不传** `developerProxy.body`。\n\n---\n\n## postContentDocumentSuspendSubmission（POST）\n\n| Query | 必填 | 说明 |\n|-------|------|------|\n| marketplaceId | 是 | 目标站点 id |\n\n请求暂停详情页可见 A+；**不删除**文档与 ASIN 关联。脚本 **不传** body。\n\n---\n\n## 脚本入参约定（JSON 一行）\n\n各脚本均需 **`sellerId`**、**`region`**；站点 id 使用 **`marketplaceId`** 或 **`marketplaceIds`**（数组时仅取第一个，与其它店铺 skill 一致）。\n\n| 脚本 | 额外必填 | 可选 |\n|------|----------|------|\n| `search_content_documents.py` | — | `pageToken` |\n| `create_content_document.py` | `contentDocument` | — |\n| `get_content_document.py` | `contentReferenceKey`, `includedDataSet` | — |\n| `update_content_document.py` | `contentReferenceKey`, `contentDocument` | — |\n| `list_content_document_asin_relations.py` | `contentReferenceKey` | `includedDataSet`, `asinSet`, `pageToken` |\n| `post_content_document_asin_relations.py` | `contentReferenceKey`, `asinSet` | — |\n| `validate_content_document_asin_relations.py` | `contentDocument` | `asinSet`（写入 Query） |\n| `search_content_publish_records.py` | `asin` | `pageToken` |\n| `post_content_document_approval_submission.py` | `contentReferenceKey` | — |\n| `post_content_document_suspend_submission.py` | `contentReferenceKey` | — |\n\n全局可选：**`skipDepCheck`: true**（跳过本地依赖探测，不建议常规使用）。\n\n---\n\n## curl 示例（网关层示意）\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"\"\n\n# 1) 取令牌（示意）\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/storeTokens\" \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"sellerId\":\"A1...\",\"region\":\"NA\"}'\n\n# 2) 转发 searchContentDocuments（将 ACCESS_TOKEN 替换为上一步 accessToken）\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\n \"region\":\"NA\",\n \"path\":\"aplus/2020-11-01/contentDocuments\",\n \"method\":\"GET\",\n \"amzAccessToken\":\"ACCESS_TOKEN\",\n \"queryString\":\"marketplaceId=ATVPDKIKX0DER\"\n }'\n```\n\nFile v1.2.3:references/linkfox-amazon-store-auth.md\n\n---\nname: linkfox-amazon-store-auth\ndescription: 亚马逊店铺授权与管理。提供完整的店铺授权流程、令牌刷新、已授权店铺查询及访问令牌获取能力。\n---\n\n# 亚马逊店铺授权与管理（Amazon Store Auth）\n\n本 skill 负责亚马逊卖家店铺的 OAuth 授权、已授权店铺列表、访问令牌获取与刷新，是拉取报告、查询库存、同步订单等所有下游操作的前置依赖。请求参数与响应字段详见 [references/api.md](references/api.md)，完整授权流程见 [references/authorization-flow.md](references/authorization-flow.md)，快速上手见 [references/quick-start.md](references/quick-start.md)。\n\n> 相关 skill：若用户需要拉取亚马逊店铺报告（库存/订单/销售/财务报告等），请切换到 `linkfox-amazon-store-report`，该 skill 依赖本 skill 提供的授权与令牌能力。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 生成亚马逊卖家授权链接，引导用户完成 OAuth 授权。\n- 查询当前用户已授权的亚马逊店铺列表（sellerName / sellerId / region）。\n- 获取指定店铺的访问令牌（accessToken / refreshToken / expiresIn）。\n- 刷新过期令牌，续签新的 accessToken。\n- 作为下游 skill 的前置依赖，负责\"选店 → 取令牌\"标准流程。\n\n### ❌ 边界与限制\n\n- **sellerName 必填**：调用 `/spApi/authorizeUrl` 前必须向用户询问并传入非空 `sellerName`，用于在已授权店铺列表中区分账号；不允许带空值调用。\n- **令牌有效期**：`accessToken` 通常 1 小时过期，使用前需检查并按需刷新；`refreshToken` 失效后需重新授权。\n- **区域专属**：每次店铺授权都与具体区域（NA/EU/FE）绑定，同一卖家在不同区域需分别授权。\n- **用户隔离**：用户只能查看/管理自己授权的店铺。\n- **回调白名单**：系统回调 URL 必须在授权方（紫鸟）处加白名单。\n- **不在范围内**：拉取亚马逊报告（用 `linkfox-amazon-store-report`）；产品 listing 管理、订单处理、库存管理、广告投放由其他 skill 负责。\n\n## 执行流程\n\n### 流程一：新店铺授权\n\n**步骤 1：获取授权链接**\n- 【输入】`region`（默认 NA）、`sellerName`（必填，向用户询问非空店铺名）\n- 【动作】调用 `POST /spApi/authorizeUrl`，传入 `region` 与 `sellerName`\n- 【输出】`authorizeUrl`（Amazon 授权链接）\n\n**步骤 2：用户浏览器授权**\n- 【输入】`authorizeUrl`\n- 【动作】把链接给用户，让其在浏览器打开并完成 Amazon 授权同意\n- 【输出】Amazon 回调系统服务端，系统自动保存授权记录与令牌\n\n**步骤 3：验证授权成功**\n- 【输入】无\n- 【动作】调用 `POST /spApi/authorizedStores`\n- 【输出】已授权店铺列表，确认新店铺已出现（sellerName / sellerId / region）\n\n### 流程二：为下游操作准备令牌（标准前置流程）\n\n当用户提出任何涉及卖家后台数据的请求（拉报告、查库存、看订单等），本 skill 负责前置的\"选店 → 取令牌\"流程，具体业务由下游 skill 接手。\n\n**步骤 1：列出已授权店铺**\n- 【输入】无\n- 【动作】调用 `POST /spApi/authorizedStores`\n- 【输出】店铺列表（sellerName / sellerId / region）\n\n**步骤 2：选择店铺**\n- 【输入】店铺列表\n- 【动作】若有多家店铺，请用户明确选哪一家\n- 【输出】确定的 `sellerId` 与 `region`\n\n**步骤 3：获取该店铺令牌**\n- 【输入】`sellerId`、`region`\n- 【动作】调用 `POST /spApi/storeTokens`；若 `expiresIn` 过短或令牌已过期，先调用 `POST /spApi/refreshToken` 续签\n- 【输出】`accessToken`（及 `refreshToken` / `expiresIn`）\n\n**步骤 4：交付下游 skill**\n- 【输入】`accessToken`\n- 【动作】把 `accessToken` 交给下游 skill（如 `linkfox-amazon-store-report`）\n- 【输出】下游 skill 使用令牌执行具体业务\n\n## 核心概念\n\nSelling Partner API 是亚马逊为卖家提供的官方接口。本 skill 负责 OAuth 2.0 授权流程与令牌生命周期管理：\n\n- **授权流程**：生成授权 URL → 用户在 Amazon 完成授权 → Amazon 回调并附带授权码 → 系统用授权码换取令牌 → 令牌安全保存。\n- **店铺名（`sellerName`）必填**：调用 `/spApi/authorizeUrl` 前必须向用户询问并获取一个清晰、非空的店铺名，用于在已授权店铺列表中标记该账号；不要留空或使用空白字符串。\n- **令牌生命周期**：`accessToken` 通常 1 小时过期；`refreshToken` 用于在不重新授权的前提下续签新的 `accessToken`。\n\n**支持区域**：\n\n| 代码 | 名称 | 覆盖市场 |\n|------|------|----------|\n| NA | 北美 | 美国、加拿大、墨西哥 |\n| EU | 欧洲 | 英国、德国、法国、意大利、西班牙、荷兰等 |\n| FE | 远东 | 日本、澳大利亚、新加坡、印度 |\n\n默认区域为 NA，用户未指定时使用 NA。\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/{authorizeUrl|storeTokens|authorizedStores|refreshToken}`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- 始终将完整响应写入 `/linkfox///data/-.json`（`` 取自环境变量 `SESSION_ID`；禁止写入 /tmp，当前目录不可写则报错）。\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout。\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数、最大列表字段的长度 + 前 3 条样本）。\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）。\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n### 示例 1：授权新店铺\n> 「我要授权我的亚马逊北美站点」\n\n1. 询问店铺名 `sellerName`（若用户未提供），说明这只是在 LinkFox 里识别店铺的标签，建议与 Seller Central 后台名字保持一致。\n2. 调用 `/spApi/authorizeUrl`，传入 `region` 与 `sellerName`。\n3. 把返回的 `authorizeUrl` 给用户，让其在浏览器中打开。\n4. 用户在 Amazon 完成授权 → Amazon 回调系统 → 系统自动保存授权。\n5. 可选：调用 `/spApi/authorizedStores` 确认授权成功。\n\n### 示例 2：查看已授权店铺\n> 「列一下我已授权的亚马逊店铺」\n\n1. 调用 `/spApi/authorizedStores`。\n2. 展示店铺列表（sellerName / sellerId / region），按 sellerId、region 排序。\n\n### 示例 3：刷新过期令牌\n> 「我店铺的令牌过期了，帮我刷新」\n\n1. 调用 `/spApi/refreshToken`，传入 `sellerId`（可选 `region`）。\n2. 返回新的 `accessToken` / `refreshToken`，数据库自动更新。\n\n### 示例 4：查询店铺令牌\n> 「获取北美站点 A123 店铺的访问令牌」\n\n1. 调用 `/spApi/storeTokens`，传入 `sellerId` 与 `region`。\n2. 返回全部令牌信息，供下游业务调用。\n\n## 展示规则\n\n1. **先有店铺名再生成授权链接**：若用户未提供 `sellerName`，必须先问，不允许带空值调用 `/spApi/authorizeUrl`。\n2. **只呈现数据**：展示授权结果、店铺列表、令牌信息即可，不做业务建议。\n3. **安全意识**：不要明文显示完整的 `accessToken`/`refreshToken`，只展示前 10 个字符等掩码形式。\n4. **清晰引导**：返回授权链接时，明确告知用户在浏览器中打开并完成授权。\n5. **错误说明**：授权失败时，基于错误码解释原因并给出建议。\n6. **成功确认**：授权完成后与用户确认，可选择展示该店铺基本信息。\n\n## 用户表达与场景速查\n\n**适用** —— 授权与令牌管理场景：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"授权我的亚马逊店铺\" / \"Authorize my Amazon store\" | 新店铺授权 |\n| \"看看已授权的亚马逊店铺\" / \"Show my authorized stores\" | 列出已授权店铺 |\n| \"令牌过期了\" / \"My token expired\" | 刷新令牌 |\n| \"获取 XXX 店铺的访问令牌\" / \"Get access token for store\" | 查询店铺令牌 |\n| \"绑定我的亚马逊账号\" / \"Connect my Amazon seller account\" | 新店铺授权 |\n\n不适用场景见上方【能力边界】。\n\n## 解决认证和积分问题\n\n发生以下异常情况时，采用以下措施来处理：\n\n### 异常情况\n- **未配置 API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应 401 或 402 状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n### 措施\n- 优先采用 skill 内的 onboarding.md 引导解决问题。\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个 skill 并根据它的引导来处理。如未安装请先安装：\n - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个 skill。\n\n---\n\n# 亚马逊店铺授权 API 参考\n\n本文档描述授权与店铺/令牌管理相关的 API。若需经网关代理拉取报告或 Listing 单条查询等，请参考 `linkfox-amazon-store-report`、`linkfox-amazon-store-listings` skill。\n\n## 调用规范\n\n- **Base URL**：`${LINKFOX_TOOL_GATEWAY}`（默认 `https://tool-gateway.linkfox.com`；可用 `LINKFOX_TOOL_GATEWAY` 覆盖，兼容旧名 `STORE_API_BASE_URL` / `SPAPI_BASE_URL`）\n- **请求方式**：所有接口均为 POST\n- **Content-Type**：`application/json`\n- **认证方式**：Header `Authorization: `，API key 优先读取环境变量 `LINKFOX_AGENT_API_KEY`，未设置时回退到兼容旧名 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 接口列表\n\n### 1. 获取授权链接\n\n**端点**：`/spApi/authorizeUrl`\n\n**请求参数**（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 | 示例 |\n|-----------|------|----------|-------------|---------|\n| region | string | 是 | 区域代码：NA / EU / FE | \"NA\" |\n| sellerName | string | **是** | 店铺展示名（店铺名）— **必填，非空**；用于在已授权店铺列表中识别账号 | \"My Store\" |\n\n**响应**：\n\n```json\n{\n \"authorizeUrl\": \"https://sellercentral.amazon.com/apps/authorize/consent?...\"\n}\n```\n\n> 说明：授权完成后的回调由 Amazon 直接回调服务端内部接口处理，属于系统内部流程，不作为本 skill 的用户调用接口。\n\n---\n\n### 2. 查询已授权店铺列表\n\n**端点**：`/spApi/authorizedStores`\n\n**请求参数**：无（使用当前用户上下文）\n\n**响应**：\n\n```json\n{\n \"stores\": [\n {\n \"sellerName\": \"My Store\",\n \"sellerId\": \"A1234567890\",\n \"region\": \"NA\"\n }\n ],\n \"total\": 1\n}\n```\n\n---\n\n### 3. 刷新令牌\n\n**端点**：`/spApi/refreshToken`\n\n**请求参数**（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----------|------|----------|-------------|\n| sellerId | string | 是 | Seller ID |\n| region | string | 否 | 区域代码（精确匹配可选） |\n\n**响应**：\n\n```json\n{\n \"authRecordId\": 123,\n \"accessToken\": \"Atza|IwEBIA...\",\n \"refreshToken\": \"Atzr|IwEBIJ...\",\n \"tokenType\": \"bearer\",\n \"expiresIn\": \"3600\",\n \"message\": \"Token refreshed and updated\"\n}\n```\n\n---\n\n### 4. 查询店铺令牌\n\n**端点**：`/spApi/storeTokens`\n\n**请求参数**（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----------|------|----------|-------------|\n| sellerId | string | 是 | Seller ID |\n| region | string | 是 | 区域代码 |\n\n**响应**：\n\n```json\n{\n \"sellerId\": \"A1234567890\",\n \"region\": \"NA\",\n \"authRecordId\": 123,\n \"accessToken\": \"Atza|IwEBIA...\",\n \"refreshToken\": \"Atzr|IwEBIJ...\",\n \"tokenType\": \"bearer\",\n \"expiresIn\": \"3600\"\n}\n```\n\n返回的 `accessToken` 可交给下游 skill（如 `linkfox-amazon-store-report`）用于调用亚马逊开放接口。\n\n---\n\n## 错误码\n\n| errcode | 含义 | 建议动作 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 1002 | 缺参数或认证失败 | 检查必填参数与认证 |\n| 1003 | 第三方服务调用失败 | 稍后重试，检查网络与白名单 |\n| 1004 | 授权记录不存在或不属于当前用户 | 核对 sellerId/region 或重新授权 |\n\n**错误响应示例**：\n\n```json\n{\n \"errcode\": 1002,\n \"errmsg\": \"Missing required parameter: region\"\n}\n```\n\n---\n\n## curl 示例\n\n### 获取授权链接\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/spApi/authorizeUrl \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"region\": \"NA\", \"sellerName\": \"My Store\"}'\n```\n\n### 查询已授权店铺列表\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/spApi/authorizedStores \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n### 刷新令牌\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/spApi/refreshToken \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sellerId\": \"A1234567890\", \"region\": \"NA\"}'\n```\n\n### 查询店铺令牌\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/spApi/storeTokens \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sellerId\": \"A1234567890\", \"region\": \"NA\"}'\n```\n\n---\n\n## 重要事项\n\n1. **令牌安全**：不要打印完整 accessToken/refreshToken，仅展示前 10 字符掩码。\n2. **令牌生命周期**：accessToken 1 小时过期，使用前检查并按需刷新。\n3. **区域专属**：同一卖家在不同区域需要分别授权。\n4. **用户隔离**：所有 API 都强制用户级访问控制。\n5. **回调白名单**：系统回调 URL 必须在授权提供方（紫鸟）处加白名单。\n\n完整授权流程与实现细节：见 `authorization-flow.md`。\n\nFile v1.2.3:references/linkfox-amazon-store-catalog.md\n\n---\nname: linkfox-amazon-store-catalog\ndescription: 亚马逊店铺商品目录检索。支持按 ASIN、关键词查询商品目录、类目节点、商品图片及摘要等信息。\n---\n\n# 亚马逊店铺商品目录（Catalog Items）\n\n本 skill 查询亚马逊店铺商品目录（Catalog），与 `linkfox-amazon-store-auth` 等同属 Amazon Store 系列：先 `POST /spApi/storeTokens`，再 `POST /spApi/developerProxy` 转发 GET。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- **listCatalogCategories**（v0）：按 `asin` 或 `sellerSku` 查询某商品所属的类目节点。\n- **searchCatalogItems**（`2022-04-01` 默认 / `2020-12-01`）：按 `keywords` 或 `identifiers + identifiersType` 检索商品目录，可附带 `includedData`（summaries/images/attributes/salesRanks 等）。\n- **getCatalogItem**（`2022-04-01` 默认 / `2020-12-01`）：按 `asin` 获取单个商品目录详情。\n- 支持通过 `catalogItemsVersion` 切换 Catalog Items API 版本。\n\n### ❌ 边界与限制\n\n- **前置依赖**：依赖 `linkfox-amazon-store-auth`；运行 `python scripts/check_auth_dependency.py`，exit **42** 时需先安装授权 skill。\n- **权限要求**：应用需具备 Catalog Items 相关角色；`searchCatalogItems` 按 `identifiers+SKU` 检索时 query 须带 `sellerId`（脚本在 `identifiersType=SKU` 时自动使用入参 `sellerId`）。\n- **网关白名单**：path 白名单需包含 `catalog/v0/` 与 `catalog/2022-04-01/`（或 `2020-12-01`）。\n- **数据口径**：本 skill 读的是 Amazon 商品目录（Catalog），**不是卖家订单**；订单见 `linkfox-amazon-store-orders`。\n- **字段定义**：`includedData` 及返回字段以 Amazon schema 为准，详见 `references/api.md`。\n- **成本约束**：本工具消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`\n- **默认 Catalog Items 版本**：`2022-04-01`；入参 `catalogItemsVersion` 可改为 `2020-12-01`。\n- **共享模块**：`_spapi_catalog_common.py`。\n\n**输出策略（脚本默认行为）**：\n- 始终将完整响应写入 `/linkfox///data/linkfox-amazon-store-catalog-.json`（`` 取自环境变量 `SESSION_ID`；禁止写入 /tmp，当前目录不可写则报错）。\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout。\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）。\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）。\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n### 官方参考索引\n\n| 能力 | 文档 |\n|------|------|\n| listCatalogCategories | [listCatalogCategories](https://developer-docs.amazon.com/sp-api/reference/listcatalogcategories) |\n| searchCatalogItems | [searchCatalogItems](https://developer-docs.amazon.com/sp-api/reference/searchcatalogitems) |\n| getCatalogItem | [getCatalogItem](https://developer-docs.amazon.com/sp-api/reference/getcatalogitem) |\n\n## 使用示例\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"\"\n\npython scripts/list_catalog_categories.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceId\":\"ATVPDKIKX0DER\",\"asin\":\"B08N5WRWNW\"}'\n\npython scripts/search_catalog_items.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"keywords\":[\"wireless mouse\"]}'\n\npython scripts/get_catalog_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B08N5WRWNW\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"includedData\":[\"summaries\",\"images\"]}'\n```\n\n## 展示规则\n\n1. 先看 `developerProxy.errcode` / `httpStatus`，再读 `categories` / `catalogItems` / `catalogItem`。\n2. **listCatalogCategories** 使用 v0 查询键 `MarketplaceId`（单数），与 search/get 的 `marketplaceIds` 不同。\n3. 网关 path 白名单需包含 `catalog/v0/` 与 `catalog/2022-04-01/`（或 `2020-12-01`）。\n4. 仅呈现数据，不做主观商业建议。\n\n## 用户表达与场景速查\n\n**适用** —— 亚马逊商品目录检索：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"查这个 ASIN 的目录信息\"、\"按 ASIN 查商品\" | getCatalogItem |\n| \"用关键词搜亚马逊商品目录\" | searchCatalogItems（keywords） |\n| \"查这几个 ASIN/EAN 的目录\" | searchCatalogItems（identifiers） |\n| \"这个 ASIN 属于哪些类目\" | listCatalogCategories |\n| \"查商品图片、摘要、销售排名\" | getCatalogItem + includedData |\n\n不适用场景见上方【能力边界】。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用以下措施来处理：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n### 措施\n- 优先采用skill内的 onboarding.md 引导解决问题。\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\n - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。\n\n---\n\n# 亚马逊店铺商品目录 API 参考\n\n经 **LinkFox** `storeTokens` + `developerProxy` 调用 SP-API **Catalog Items**（与 listings / pricing 系列相同）。\n\n环境变量：`LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）；可选 `LINKFOX_TOOL_GATEWAY`（回退 `STORE_API_BASE_URL` / `SPAPI_BASE_URL`，默认 `https://tool-gateway.linkfox.com`）。\n\n---\n\n## 1. 脚本与路径\n\n| 脚本 | 方法 | 路径 |\n|------|--------|------|\n| `list_catalog_categories.py` | GET | `catalog/v0/categories` |\n| `search_catalog_items.py` | GET | `catalog/2022-04-01/items`（默认） |\n| `get_catalog_item.py` | GET | `catalog/2022-04-01/items/{asin}`（默认） |\n\n`catalogItemsVersion` 可选 **`2020-12-01`**，path 中版本段随之替换。\n\n---\n\n## 2. listCatalogCategories（v0）\n\n### 入参（JSON）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId, region | 是 | 店铺与区域 |\n| marketplaceId / marketplaceIds | 是 | 仅使用**第一个**站点 ID → query **`MarketplaceId`** |\n| asin / ASIN | 条件 | 与 sellerSku **二选一** |\n| sellerSku / SellerSKU | 条件 | 与 asin **二选一** |\n\n### 查询参数（大小写敏感）\n\n- `MarketplaceId`\n- `ASIN` 或 `SellerSKU`\n\n解析字段：**`categories`**\n\n---\n\n## 3. searchCatalogItems\n\n### 入参\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| marketplaceIds | 是 | 文档通常 ≤1 个 |\n| keywords | 条件 | 与 identifiers **互斥**，最多 20 个 |\n| identifiers | 条件 | 最多 20 个；须配 **identifiersType** |\n| identifiersType | 条件 | ASIN, EAN, GTIN, ISBN, JAN, MINSAN, SKU, UPC |\n| includedData | 否 | summaries, images, attributes, salesRanks 等 |\n| brandNames, classificationIds | 否 | 限缩关键词搜索 |\n| locale, keywordsLocale | 否 | |\n| pageSize | 否 | 1～20，默认 10 |\n| pageToken | 否 | 分页 |\n| catalogItemsVersion | 否 | `2022-04-01`（默认）或 `2020-12-01` |\n| sellerIdForCatalog | 否 | 覆盖 query 中的 sellerId（默认用 sellerId） |\n\n当 **identifiersType=SKU** 时，Amazon 要求 query 带 **sellerId**；脚本默认使用 JSON 里的 **sellerId**。\n\n解析字段：**`catalogItems`**\n\n---\n\n## 4. getCatalogItem\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| asin | 是 | path 段 |\n| marketplaceIds | 是 | |\n| includedData | 否 | |\n| locale | 否 | |\n| catalogItemsVersion | 否 | |\n\n解析字段：**`catalogItem`**\n\n---\n\n## 5. includedData 示例（2022-04-01）\n\n`summaries`, `attributes`, `classifications`, `dimensions`, `identifiers`, `images`, `productTypes`, `relationships`, `salesRanks`, `vendorDetails`（以官方为准）。\n\n---\n\n## 6. 错误与白名单\n\n- **401**：HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- **402**：HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- **403**：Catalog Items 权限不足。\n- **1005**（网关）：需放行 `catalog/v0/`、`catalog/2020-12-01/`、`catalog/2022-04-01/`。\n- **429**：按官方 usage plan 降频。\n\nFile v1.2.3:references/linkfox-amazon-store-customer-feedback.md\n\n---\nname: linkfox-amazon-store-customer-feedback\ndescription: 亚马逊店铺买家反馈洞察。支持分析 ASIN 或类目节点的评论主题、评价趋势、退货原因及星级影响。\n---\n\n# 亚马逊店铺买家反馈（Amazon Store Customer Feedback）\n\n本 skill 与 **`linkfox-amazon-store-auth`** 等同属 Amazon Store 系列：先 `POST /spApi/storeTokens`，再 `POST /spApi/developerProxy` 转发 `GET`。接口属于 Customer Feedback（买家评论/退货洞察），不是 Orders 订单 API；订单见 `linkfox-amazon-store-orders`。完整参数、响应与错误码见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 调用 SP-API Customer Feedback **v2024-06-01**，分析 ASIN 或 browse node 的评论主题、评价趋势、退货主题与退货趋势。\n- 支持按 `MENTIONS` / `STAR_RATING_IMPACT` 排序评论主题，对比买家关注点与星级影响。\n- 通过 `get_item_browse_node` 由 ASIN 反查类目节点，再下钻类目级反馈。\n\n### ❌ 边界与限制\n\n- **前置依赖**：依赖 `linkfox-amazon-store-auth` 完成授权；未授权无法调用。\n- **非订单接口**：订单查询见 `linkfox-amazon-store-orders`。\n- **角色要求**：通常需 Brand Analytics 或 Selling Partner Insights 等角色；站点以官方为准（常见 US/UK/DE 等）。\n- **ASIN 口径**：一般为子体 ASIN；topics 类接口需 `sortBy`（`MENTIONS` 或 `STAR_RATING_IMPACT`）。\n- **网关白名单**：需放行 `customerFeedback/2024-06-01/`。\n- **数据时效**：刷新频率以 Amazon 为准（通常按周）。\n- **成本约束**：本工具消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；继续检索前先向用户说明额外消耗。\n\n## 执行流程\n\n复杂 skill：多接口编排，建议按以下顺序逐步调用。\n\n### 步骤 1 — ASIN 评论主题\n\n- 【输入】`sellerId`、`region`、`marketplaceId`、`asin`、`sortBy`\n- 【动作】运行 `get_item_review_topics.py`，`sortBy` 分别取 `MENTIONS` 与 `STAR_RATING_IMPACT` 各调一次以对比\n- 【输出】`itemReviewTopics`（评论主题、提及量与星级影响）\n\n### 步骤 2 — ASIN 评论趋势\n\n- 【输入】`sellerId`、`region`、`marketplaceId`、`asin`\n- 【动作】运行 `get_item_review_trends.py`\n- 【输出】`itemReviewTrends`（评价趋势）\n\n### 步骤 3 — 反查类目节点\n\n- 【输入】`sellerId`、`region`、`marketplaceId`、`asin`\n- 【动作】运行 `get_item_browse_node.py`\n- 【输出】`itemBrowseNode`（取得 `browseNodeId`）\n\n### 步骤 4 — 类目级反馈\n\n- 【输入】`sellerId`、`region`、`marketplaceId`、`browseNodeId`（来自步骤 3）；topics 接口另需 `sortBy`\n- 【动作】按需运行 `get_browse_node_review_topics` / `get_browse_node_review_trends` / `get_browse_node_return_topics` / `get_browse_node_return_trends`\n- 【输出】`browseNodeReviewTopics` / `browseNodeReviewTrends` / `browseNodeReturnTopics` / `browseNodeReturnTrends`\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）。\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`（可用脚本见下方使用示例）。\n- **成本约束**：失败/空结果不得自动换关键词、翻页或连续试探；继续检索前先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n\n- **始终**将完整响应写入 `/linkfox///data/linkfox-amazon-store-customer-feedback-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）。\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout。\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）。\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）。\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"\"\n\npython scripts/get_item_review_topics.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0...\",\"marketplaceId\":\"ATVPDKIKX0DER\",\"sortBy\":\"MENTIONS\"}'\n\npython scripts/get_item_browse_node.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0...\",\"marketplaceId\":\"ATVPDKIKX0DER\"}'\n\npython scripts/get_browse_node_review_topics.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"browseNodeId\":\"123456\",\"marketplaceId\":\"ATVPDKIKX0DER\",\"sortBy\":\"STAR_RATING_IMPACT\"}'\n```\n\n## 展示规则\n\n1. 先看 `developerProxy.errcode` / `httpStatus`，再读各脚本解析字段（如 `itemReviewTopics`）。\n2. 网关白名单需包含 `customerFeedback/2024-06-01/`。\n3. 数据刷新频率以 Amazon 为准（通常按周）。\n4. 以结构化表格呈现评论主题、提及量、星级影响与趋势变化，只呈现数据，不做主观商业建议。\n\n## 用户表达与场景速查\n\n**适用** —— 亚马逊 ASIN / 类目节点买家反馈洞察：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"这个 ASIN 的评论主题是什么\"、\"买家最关心什么\" | ASIN 评论主题（MENTIONS） |\n| \"哪些主题拉低了星级\"、\"星级影响\" | ASIN 评论主题（STAR_RATING_IMPACT） |\n| \"这个 ASIN 评价趋势\"、\"评论走势\" | ASIN 评论趋势 |\n| \"这个 ASIN 属于哪个类目\"、\"反查 browse node\" | ASIN 类目节点 |\n| \"这个类目的评论主题\"、\"类目买家反馈\" | browse node 评论主题 |\n| \"这个类目退货原因\"、\"退货主题\" | browse node 退货主题 |\n| \"类目评价趋势\"、\"类目退货趋势\" | browse node 趋势 |\n\n不适用场景见上方【能力边界】。\n\n## 解决认证和积分问题\n\n发生以下异常情况时，采用以下措施来处理：\n\n### 异常情况\n- **未配置 API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应 401 或 402 状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n### 措施\n- 优先采用 skill 内的 onboarding.md 引导解决问题。\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个 skill 并根据它的引导来处理。如未安装请先安装：\n - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个 skill。\n\n---\n\n# linkfox-amazon-store-customer-feedback — API 参考\n\nCustomer Feedback **v2024-06-01**，经 LinkFox `storeTokens` + `developerProxy` 调用。\n\n官方总览：[Customer Feedback API](https://developer-docs.amazon.com/sp-api/docs/customer-feedback-api-v2024-06-01-use-case-guide)\n\n---\n\n## 1. 脚本与 path\n\n| 脚本 | GET path |\n|------|----------|\n| `get_item_review_topics.py` | `customerFeedback/2024-06-01/items/{asin}/reviews/topics` |\n| `get_item_browse_node.py` | `customerFeedback/2024-06-01/items/{asin}/browseNode` |\n| `get_item_review_trends.py` | `customerFeedback/2024-06-01/items/{asin}/reviews/trends` |\n| `get_browse_node_review_topics.py` | `customerFeedback/2024-06-01/browseNodes/{browseNodeId}/reviews/topics` |\n| `get_browse_node_review_trends.py` | `customerFeedback/2024-06-01/browseNodes/{browseNodeId}/reviews/trends` |\n| `get_browse_node_return_topics.py` | `customerFeedback/2024-06-01/browseNodes/{browseNodeId}/returns/topics` |\n| `get_browse_node_return_trends.py` | `customerFeedback/2024-06-01/browseNodes/{browseNodeId}/returns/trends` |\n\n前缀均为 `customerFeedback/2024-06-01/`；共享模块：`_spapi_customer_feedback_common.py`。\n\n---\n\n## 2. 公共入参\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 卖家 ID |\n| region | 是 | `NA` / `EU` / `FE` 等 |\n| marketplaceId | 是 | 单站点；或 `marketplaceIds` 数组取第一个 |\n| skipDepCheck | 否 | 跳过依赖检查 |\n\n---\n\n## 3. 按接口\n\n### getItemReviewTopics / getBrowseNodeReviewTopics / getBrowseNodeReturnTopics\n\n| 字段 | 必填 |\n|------|------|\n| asin 或 browseNodeId | 是（按接口） |\n| sortBy | 是 | `MENTIONS` \\| `STAR_RATING_IMPACT` |\n\nQuery：`marketplaceId`、`sortBy`\n\n解析字段：`itemReviewTopics` / `browseNodeReviewTopics` / `browseNodeReturnTopics`\n\n### getItemBrowseNode\n\n| 字段 | 必填 |\n|------|------|\n| asin | 是 |\n\nQuery：`marketplaceId`\n解析字段：`itemBrowseNode`\n\n### getItemReviewTrends / getBrowseNodeReviewTrends / getBrowseNodeReturnTrends\n\nQuery：`marketplaceId`\n解析字段：`itemReviewTrends` / `browseNodeReviewTrends` / `browseNodeReturnTrends`\n\n---\n\n## 4. 推荐调用顺序（ASIN）\n\n1. `get_item_review_topics`（`sortBy=MENTIONS` 与 `STAR_RATING_IMPACT` 各一次）\n2. `get_item_review_trends`\n3. `get_item_browse_node` → 取 `browseNodeId`\n4. 对 browse node 调用 review/return 的 topics 与 trends\n\n---\n\n## 5. 限制\n\n- 非订单接口；订单用 `linkfox-amazon-store-orders`。\n- **401**：HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- **402**：HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- **403**：角色或站点不支持。\n- **1005**：网关需放行 `customerFeedback/2024-06-01/`。\n\nFile v1.2.3:references/linkfox-amazon-store-external-fulfillment.md\n\n---\nname: linkfox-amazon-store-external-fulfillment\ndescription: 亚马逊店铺 External Fulfillment（与 linkfox-amazon-store-auth / orders / listings 同系列），经 /spApi/developerProxy 调用 SP-API External Fulfillment v2024-09-11：Inventory 的 batchInventory（按 location 查/写库存）；Shipping 的 getShipments、getShipment、processShipment、createPackages、updatePackage、updatePackageStatus、retrieveShippingOptions、generateInvoice、retrieveInvoice、generateShipLabels；Returns 的 listReturns、getReturn。覆盖 Seller Flex / Easy Ship / Self Ship / MFN Self Delivery 等。当用户提到 External Fulfillment、SmartConnect、Seller Flex、FBA Onsite、Easy Ship、Self Ship、batchInventory、location 库存、履约单 shipment、面单、发票、EF 退货、externalFulfillment 时触发。与普通 Orders/Feeds 库存不同，本技能专指 External Fulfillment API。\n---\n\n# Amazon 店铺 External Fulfillment\n\n本 skill 与 **`linkfox-amazon-store-auth`** 等同属 **Amazon Store** 系列：依赖 **`linkfox-amazon-store-auth`** 选店（`sellerId`+`region`）；直接 **`POST /spApi/developerProxy`** 传入 `sellerId`+`region`，由服务端解析 token（勿传 `amzAccessToken`，除非兼容旧调用）。转发上游 **`GET` / `POST` / `PUT` / `PATCH`**。\n\n适用渠道：Seller Flex / FBA Onsite、Multi Seller Flex、Easy Ship、Self Ship、MFN Self Delivery、Amazon Pharmacy 等（以商家 allowlist 与角色为准）。\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（完整参数/响应见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动翻页或连续试探；需要继续时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-amazon-store-external-fulfillment-.json`\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要\n- 加 `--inline` 强制全量打印（同样落盘）\n\n**读数据建议**：先看摘要；需要具体字段时用 `jq` / `ConvertFrom-Json` 从落盘文件抽取。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## 官方参考索引\n\n| 模块 | 能力 | 文档 |\n|------|------|------|\n| Inventory | batchInventory | [batchInventory](https://developer-docs.amazon.com/sp-api/reference/batchinventory) |\n| Shipping | getShipments | [getShipments](https://developer-docs.amazon.com/sp-api/reference/getshipments-1) |\n| Shipping | getShipment | [getShipment](https://developer-docs.amazon.com/sp-api/reference/getshipment-1) |\n| Shipping | processShipment | [processShipment](https://developer-docs.amazon.com/sp-api/reference/processshipment) |\n| Shipping | createPackages | [createPackages](https://developer-docs.amazon.com/sp-api/reference/createpackages) |\n| Shipping | updatePackage | [updatePackage](https://developer-docs.amazon.com/sp-api/reference/updatepackage) |\n| Shipping | updatePackageStatus | [updatePackageStatus](https://developer-docs.amazon.com/sp-api/reference/updatepackagestatus) |\n| Shipping | retrieveShippingOptions | [retrieveShippingOptions](https://developer-docs.amazon.com/sp-api/reference/retrieveshippingoptions) |\n| Shipping | generateInvoice | [generateInvoice](https://developer-docs.amazon.com/sp-api/reference/generateinvoice) |\n| Shipping | retrieveInvoice | [retrieveInvoice](https://developer-docs.amazon.com/sp-api/reference/retrieveinvoice) |\n| Shipping | generateShipLabels | [generateShipLabels](https://developer-docs.amazon.com/sp-api/reference/generateshiplabels) |\n| Returns | listReturns | [listReturns](https://developer-docs.amazon.com/sp-api/reference/listreturns) |\n| Returns | getReturn | [getReturn](https://developer-docs.amazon.com/sp-api/reference/getreturn) |\n\n---\n\n## Prerequisites（必须先读）\n\n本 skill **依赖** **`linkfox-amazon-store-auth`**。\n\n1. 运行 `python scripts/check_auth_dependency.py`；若 exit code **42** 且 stderr 含 `DEPENDENCY_MISSING:`，请先安装 **`linkfox-amazon-store-auth`**。\n2. **不要**在本 skill 内绕过依赖实现授权或令牌逻辑。\n3. 商家需 **External Fulfillment allowlist**，应用需 **Direct-to-Consumer Shipping (Restricted)** 角色。\n\n---\n\n## Current Capabilities（脚本一览）\n\n| 能力 | developerProxy `path`（要点） | 脚本 |\n|------|------------------------------|------|\n| batchInventory | `externalFulfillment/inventory/2024-09-11/inventories`，POST | `post_batch_inventory.py` |\n| getShipments | `externalFulfillment/2024-09-11/shipments` + Query | `get_shipments.py` |\n| getShipment | `.../shipments/{shipmentId}` | `get_shipment.py` |\n| processShipment | `.../shipments/{shipmentId}?operation=`，POST | `process_shipment.py` |\n| createPackages | `.../shipments/{shipmentId}/packages`，POST | `create_packages.py` |\n| updatePackage | `.../shipments/{shipmentId}/packages/{packageId}`，PUT | `update_package.py` |\n| updatePackageStatus | 同上 path，PATCH | `update_package_status.py` |\n| retrieveShippingOptions | `.../shipments/{shipmentId}/shippingOptions` + packageId | `retrieve_shipping_options.py` |\n| generateInvoice | `.../shipments/{shipmentId}/invoice`，POST | `generate_invoice.py` |\n| retrieveInvoice | 同上 path，GET | `retrieve_invoice.py` |\n| generateShipLabels | `.../shipments/{shipmentId}/shipLabels?operation=`，PUT | `generate_ship_labels.py` |\n| listReturns | `externalFulfillment/2024-09-11/returns` + Query | `list_returns.py` |\n| getReturn | `.../returns/{returnId}` | `get_return.py` |\n\n共享逻辑见 **`scripts/_spapi_ef_common.py`**（仅供同目录脚本 import）。\n\n---\n\n## Quick Parameters（摘要）\n\n- **batchInventory**：`requests` 1～10 条。简化项：`action`=`fetch`|`update`、`locationId`、`skuId`；update 必填 `quantity`。MFN 单仓常用 `locationId=DEFAULT`；Seller Flex 用 4 位仓码。高级：`useAmazonRequestShape:true` 直传官方 `requests`。\n- **getShipments**：必填 `status`（如 `ACCEPTED`/`CREATED`）；可选 `locationId`、`marketplaceId`、`channelName`、`lastUpdatedAfter/Before`、`maxResults`、`paginationToken`。\n- **processShipment**：`operation`=`CONFIRM`|`REJECT`；REJECT 时可传 `referenceId`/`lineItems` 或 `requestBody`。\n- **createPackages / updatePackage**：包裹尺寸重量与 `packageLineItems` 按官方 schema 放在 `packages` 或 `requestBody`。\n- **updatePackageStatus**：主要用于 Self Delivery；传 `status`/`subStatus`/`reason`。\n- **generateShipLabels**：`operation`=`GENERATE`|`REGENERATE`；可选 `shippingOptionId`、`packageIds`。\n- **listReturns**：可选 `status`（新退货常用 `CREATED`）、`returnLocationId`、时间窗、`nextToken`。\n\n典型履约流程：`getShipments` → `processShipment(CONFIRM)` → `createPackages` → `retrieveShippingOptions` → `generateInvoice` → `generateShipLabels` →（Self Delivery）`updatePackageStatus`。\n\n---\n\n## Scripts\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"\"\n\npython scripts/post_batch_inventory.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"requests\":[{\"action\":\"fetch\",\"locationId\":\"DEFAULT\",\"skuId\":\"SKU-1\",\"marketplaceAttributes\":{\"marketplaceId\":\"ATVPDKIKX0DER\",\"channelName\":\"MFN\"}}]}'\n\npython scripts/get_shipments.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"status\":\"ACCEPTED\",\"locationId\":\"ABCD\"}'\n\npython scripts/process_shipment.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"shipmentId\":\"...\",\"operation\":\"CONFIRM\"}'\n```\n\n---\n\n## Display Rules\n\n1. 先看网关 **`developerProxy.errcode` / `httpStatus`**，再解析脚本附加字段（如 **`batchInventory`**、**`shipments`**、**`invoice`**）。\n2. **batchInventory** 成功时常为 **207** Multi-Status；逐条看 `responses[].status`。\n3. 多数写操作成功可能为 **204**（无 body）；stdout 会标 `success: true`。\n4. 发票/面单文档多为 Base64 或预签名 URL，勿把整段大 base64 反复贴进上下文。\n5. **路径白名单**：若返回 **1005**，需后端放行 **`externalFulfillment/`** 前缀。\n\n---\n\n## Important Limitations\n\n- 权限：**Direct-to-Consumer Shipping (Restricted)**；商家需 allowlist。\n- **写库存为绝对值发布**，非增量；只同步有变化的 SKU；SKU 特殊字符需 URL 编码（脚本已处理简化入参）。\n- 与 **`linkfox-amazon-store-orders`**（普通 Orders）、**`linkfox-amazon-store-feeds`**（Feed 改库存）、**`linkfox-amazon-store-report`**（库存报告）边界不同，勿混用。\n- Seller Flex 上 `retrieveShippingOptions` 常返回空；Easy Ship 全球多数站点可能不支持 `generateInvoice`（印度除外）。\n- 返回结构以 Amazon schema 为准；详见 **`references/api.md`**。\n\n## 积分消耗规则\n\n不消耗积分（以网关实际计费为准；若网关计费则按积分规则处理）。\n\n**Feedback：** 见 `references/api.md`，`skillName`：`linkfox-amazon-store-external-fulfillment`。\n\n---\n*更多跨境 skill：[LinkFox Skills](https://skill.linkfox.com/)*\n\n\n---\n\n# linkfox-amazon-store-external-fulfillment — API 与网关调用说明\n\n## 1. 调用链\n\n1. 依赖 **`linkfox-amazon-store-auth`** 完成店铺授权（`sellerId` + `region`）。\n2. **`POST ${LINKFOX_TOOL_GATEWAY}/spApi/developerProxy`** \n Body 字段：\n - **`region`**\n - **`path`**：Amazon SP-API 相对 path，**无**前导 `/`\n - **`method`**：`GET` | `POST` | `PUT` | `PATCH`\n - **`sellerId`**：由网关解析 token（勿优先传 `amzAccessToken`）\n - **`queryString`**（可选）：不含 `?`\n - **`body`**（写操作）：JSON 字符串\n - **`contentType`**：`application/json`\n\n环境变量：\n\n- **`LINKFOX_AGENT_API_KEY`**（或 **`LINKFOXAGENT_API_KEY`**）\n- **`LINKFOX_TOOL_GATEWAY`**（或 `STORE_API_BASE_URL` / `SPAPI_BASE_URL`）：默认 `https://tool-gateway.linkfox.com`\n\n---\n\n## 2. 脚本与 path / method 对照\n\n| 脚本 | method | path 模板 |\n|------|--------|-----------|\n| `post_batch_inventory.py` | POST | `externalFulfillment/inventory/2024-09-11/inventories` |\n| `get_shipments.py` | GET | `externalFulfillment/2024-09-11/shipments` |\n| `get_shipment.py` | GET | `externalFulfillment/2024-09-11/shipments/{shipmentId}` |\n| `process_shipment.py` | POST | `externalFulfillment/2024-09-11/shipments/{shipmentId}` + `operation` |\n| `create_packages.py` | POST | `.../shipments/{shipmentId}/packages` |\n| `update_package.py` | PUT | `.../shipments/{shipmentId}/packages/{packageId}` |\n| `update_package_status.py` | PATCH | `.../shipments/{shipmentId}/packages/{packageId}` |\n| `retrieve_shipping_options.py` | GET | `.../shipments/{shipmentId}/shippingOptions` + `packageId` |\n| `generate_invoice.py` | POST | `.../shipments/{shipmentId}/invoice` |\n| `retrieve_invoice.py` | GET | `.../shipments/{shipmentId}/invoice` |\n| `generate_ship_labels.py` | PUT | `.../shipments/{shipmentId}/shipLabels` + `operation` |\n| `list_returns.py` | GET | `externalFulfillment/2024-09-11/returns` |\n| `get_return.py` | GET | `externalFulfillment/2024-09-11/returns/{returnId}` |\n\n路径段经 percent-encoding。\n\n---\n\n## 3. 公共入参\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家 ID |\n| region | string | 是 | NA / EU / FE |\n| skipDepCheck | boolean | 否 | true 时跳过本地依赖探测 |\n\n---\n\n## 4. Inventory — `post_batch_inventory.py`\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| requests | object[] | 是 | 1～10 条 |\n| useAmazonRequestShape | boolean | 否 | true 时 `requests` 为官方原始数组 |\n\n简化项字段：\n\n| 字段 | 说明 |\n|------|------|\n| action | `fetch` 或 `update` |\n| locationId | MFN 单仓常用 `DEFAULT`；Seller Flex 为 4 位仓码 |\n| skuId | 卖家 SKU |\n| quantity | update 必填；绝对库存 |\n| clientSequenceNumber | 可选 |\n| marketplaceAttributes | 可选；多站点时常需 `{marketplaceId, channelName}` |\n\n脚本会组装为：\n\n```json\n{\n \"requests\": [\n {\n \"method\": \"POST\",\n \"uri\": \"/inventory/fetch?locationId=DEFAULT&skuId=SKU-1\",\n \"body\": { \"marketplaceAttributes\": { \"marketplaceId\": \"...\", \"channelName\": \"MFN\" } }\n }\n ]\n}\n```\n\n解析字段：**`batchInventory`**（上游常为 HTTP **207**）。\n\n官方：\n\n- [Publish location-level inventory](https://developer-docs.amazon.com/sp-api/docs/publish-location-level-inventory)\n- [Retrieve location-level inventory](https://developer-docs.amazon.com/sp-api/docs/retrieve-location-level-inventory)\n\n---\n\n## 5. Shipping\n\n### 5.1 `get_shipments.py`\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| status | 是 | 如 ACCEPTED、CREATED、CONFIRMED、SHIPPED… |\n| locationId | 否 | 渠道 location |\n| marketplaceId / channelName | 否 | |\n| lastUpdatedAfter / lastUpdatedBefore | 否 | ISO 8601 |\n| maxResults | 否 | 1～100 |\n| paginationToken | 否 | 上一页 nextToken |\n\n解析字段：**`shipments`**。\n\n### 5.2 `get_shipment.py`\n\n| 字段 | 必填 |\n|------|------|\n| shipmentId | 是 |\n\n解析字段：**`shipment`**。\n\n### 5.3 `process_shipment.py`\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| shipmentId | 是 | |\n| operation | 是 | CONFIRM / REJECT |\n| requestBody | 否 | 官方 body |\n| referenceId / lineItems | 否 | 简化字段，合成 body |\n\n### 5.4 `create_packages.py`\n\n| 字段 | 必填 |\n|------|------|\n| shipmentId | 是 |\n| packages 或 requestBody | 是 |\n\n### 5.5 `update_package.py`\n\n| 字段 | 必填 |\n|------|------|\n| shipmentId / packageId / requestBody | 是 |\n\n### 5.6 `update_package_status.py`\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| shipmentId / packageId | 是 | |\n| status 或 requestBody | 是 | 可附带 subStatus、reason |\n\n### 5.7 `retrieve_shipping_options.py`\n\n| 字段 | 必填 |\n|------|------|\n| shipmentId / packageId | 是 |\n\n解析字段：**`shippingOptions`**。\n\n### 5.8 `generate_invoice.py` / `retrieve_invoice.py`\n\n| 字段 | 必填 |\n|------|------|\n| shipmentId | 是 |\n\n解析字段：**`invoice`**（含 `document.format` / `document.content` Base64）。\n\n### 5.9 `generate_ship_labels.py`\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| shipmentId | 是 | |\n| operation | 是 | GENERATE / REGENERATE |\n| shippingOptionId | 否 | 需 URL 编码（脚本处理） |\n| packageIds / requestBody | 否 | 三方承运等场景 |\n\n解析字段：**`shipLabels`**。\n\n---\n\n## 6. Returns\n\n### 6.1 `list_returns.py`\n\n可选：`returnLocationId`、`rmaId`、`status`、`reverseTrackingId`、`createdSince`、`createdUntil`、`lastUpdatedSince`、`lastUpdatedUntil`、`maxResults`、`nextToken`。\n\n解析字段：**`returns`**。\n\n### 6.2 `get_return.py`\n\n| 字段 | 必填 |\n|------|------|\n| returnId | 是 |\n\n解析字段：**`returnItem`**。\n\n---\n\n## 7. 错误与白名单\n\n| 现象 | 处理 |\n|------|------|\n| 401/402 / 积分不足 | 见 `references/onboarding.md` |\n| 403 | 角色/allowlist/签名问题，非 onboarding 范围 |\n| 1005 路径拒绝 | 后端放行 `externalFulfillment/` |\n| 409 / 422 | 履约状态机冲突或参数不可处理，检查当前 shipment status |\n| 429 | 降速重试（先征得用户同意） |\n\n---\n\n## 8. Feedback\n\n`skillName`：`linkfox-amazon-store-external-fulfillment`\n\nFile v1.2.3:references/linkfox-amazon-store-fba.md\n\n---\nname: linkfox-amazon-store-fba\ndescription: 亚马逊店铺 Fulfillment by Amazon（FBA）系列（与 linkfox-amazon-store-auth 同系列），经 /spApi/developerProxy 调用 SP-API：FBA Inbound Eligibility（getItemEligibilityPreview）、FBA Inventory（getInventorySummaries/createInventoryItem/deleteInventoryItem/addInventory）、Fulfillment Inbound v2024-03-20（InboundPlan/装箱/放置/运输/货件等）与 v0（prepInstructions/labels/BOL/shipments）、Fulfillment Outbound 2020-07-01（MCF 履约单/预览/退货/tracking/features）。当用户提到 FBA、入仓资格、Inbound Eligibility、FBA 库存摘要、Send to Amazon、Inbound Plan、FBA 货件、MCF、多渠道履约、getItemEligibilityPreview、getInventorySummaries、createInboundPlan、createFulfillmentOrder 时触发。与 External Fulfillment / 普通 Orders 不同。\n---\n\n# Amazon 店铺 Fulfillment by Amazon (FBA)\n\n本 skill 与 **`linkfox-amazon-store-auth`** 同属 **Amazon Store** 系列：依赖授权选店（`sellerId`+`region`）；经 **`POST /spApi/developerProxy`** 转发 SP-API（勿传 `amzAccessToken`，除非兼容旧调用）。\n\n覆盖 **方案 A** 模块：\n\n1. **Inbound Eligibility v1**（入仓/混装资格预览）\n2. **FBA Inventory v1**（仓内库存）\n3. **Fulfillment Inbound v2024-03-20**（现行入仓工作流）+ **v0** 保留查询\n4. **Fulfillment Outbound 2020-07-01**（MCF 多渠道履约）\n\n不包含：FBA Small and Light（已弃用）、External Fulfillment（见 `linkfox-amazon-store-external-fulfillment`）、Merchant Fulfillment（MFN）。\n\n## 调用方式\n\n- **统一入口**：`python scripts/fba_api.py '{\"api\":\"\",\"sellerId\":\"...\",\"region\":\"NA\",...}' [--inline]`\n- **单接口脚本**：`python scripts/<脚本名>.py '' [--inline]`（完整对照见 `references/capabilities.md`）\n- **写操作 body**：优先传 **`requestBody`**；也可把业务字段平铺在 JSON 中（脚本会排除 sellerId/region/path/query 后组装 body）\n- **Query**：声明字段直接传；或用 **`query`** 对象 / **`queryString`** 覆盖\n- **成本约束**：失败/空结果不得自动翻页或连续试探；继续前先说明可能产生额外消耗\n\n**输出策略**：完整响应落盘到 `linkfox///data/linkfox-amazon-store-fba-*.json`；>8KB 默认摘要；`--inline` 全量打印。\n\n## 解决认证和积分问题\n\n发生未配置 API Key、401/402、积分不足时，采用 `references/onboarding.md` 引导。\n\n## Prerequisites\n\n1. 依赖 **`linkfox-amazon-store-auth`**：`python scripts/check_auth_dependency.py`（exit 42 → 先装 auth）\n2. 应用需具备 **Amazon Fulfillment** 等相关角色（以 Amazon 控制台为准）\n3. 网关需放行路径前缀：`fba/`、`inbound/fba/`（遇 **1005** 找后端加白）\n\n## Current Capabilities\n\n共 **70** 个 operation。模块表：\n\n| 模块 | 数量 | 说明 |\n|------|------|------|\n| eligibility | 1 | getItemEligibilityPreview |\n| inventory | 4 | summaries / create / delete / add |\n| inbound_v0 | 6 | prep / labels / BOL / shipments / items |\n| inbound (2024-03-20) | 45 | InboundPlan 全流程 |\n| outbound (2020-07-01) | 14 | MCF 履约 |\n\n**完整 Operation ↔ path ↔ 脚本表**：见 [`references/capabilities.md`](references/capabilities.md) \n**机器可读注册表**：`scripts/_fba_endpoints.py`、`references/operations.json`\n\n## Quick Parameters\n\n### getItemEligibilityPreview\n\n- 必填：`asin`、`program`（`INBOUND`|`COMMINGLING`）\n- `program=INBOUND` 时必填 `marketplaceIds`（或 `marketplaceId`，最多 1 个）\n\n```bash\npython scripts/get_item_eligibility_preview.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0...\",\"program\":\"INBOUND\",\"marketplaceId\":\"ATVPDKIKX0DER\"}'\n```\n\n### getInventorySummaries\n\n- 必填：`granularityType`（通常 `Marketplace`）、`granularityId`（marketplaceId）、`marketplaceIds`\n- 可选：`details`、`sellerSkus`、`startDateTime`、`nextToken`\n\n### Inbound / Outbound 写操作\n\n复杂 schema 请用 **`requestBody`** 按官方模型传完整 JSON；path 参数（如 `inboundPlanId`、`shipmentId`、`sellerFulfillmentOrderId`）与 query 字段并列在入参中。\n\n异步步骤（generate*Options 等）返回后用 **`getInboundOperationStatus`** 轮询（勿擅自高频轮询，先征得用户同意）。\n\n## Scripts\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"\"\n\n# 统一入口\npython scripts/fba_api.py '{\"api\":\"getItemEligibilityPreview\",\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0...\",\"program\":\"INBOUND\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/fba_api.py '{\"api\":\"getInventorySummaries\",\"sellerId\":\"A1...\",\"region\":\"NA\",\"granularityType\":\"Marketplace\",\"granularityId\":\"ATVPDKIKX0DER\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"details\":true}'\n\npython scripts/fba_api.py '{\"api\":\"listInboundPlans\",\"sellerId\":\"A1...\",\"region\":\"NA\",\"pageSize\":10}'\n```\n\n共享模块：`_spapi_fba_common.py`、`_fba_endpoints.py`、`_fba_runner.py`（非独立 CLI）。\n\n## Display Rules\n\n1. 先看 `developerProxy.errcode` / `httpStatus`，再看解析字段 **`payload`**\n2. 202/204 可能无 body；以状态码判断成功\n3. Inbound 2024 与 v0 的 `getShipments`/`getShipment` 勿混淆：v0 脚本为 `get_shipments_v0.py`；2024 货件为 `get_inbound_shipment.py`\n4. 与 **`linkfox-amazon-store-orders`**、**`linkfox-amazon-store-external-fulfillment`** 边界清晰，勿混用\n\n## Important Limitations\n\n- Outbound **2026-07-04** 未纳入本 skill（方案 A）\n- Small and Light 已弃用，不实现\n- Inbound 状态机复杂，需按官方工作流顺序调用；冲突常见 **409/422**\n- 限速因接口而异（Eligibility 约 1 rps），注意 **429**\n\n## 积分消耗规则\n\n不消耗积分（以网关实际计费为准）。\n\n**Feedback：** `skillName`：`linkfox-amazon-store-fba`\n\n---\n*更多跨境 skill：[LinkFox Skills](https://skill.linkfox.com/)*\n\n\n---\n\n# linkfox-amazon-store-fba — API 与网关说明\n\n## 1. 调用链\n\n`POST ${LINKFOX_TOOL_GATEWAY}/spApi/developerProxy`\n\n| 字段 | 说明 |\n|------|------|\n| region | NA / EU / FE |\n| path | SP-API 相对路径，无前导 `/` |\n| method | GET / POST / PUT / DELETE / PATCH |\n| sellerId | 店铺 ID（网关解析 token） |\n| queryString | 可选 |\n| body + contentType | 写操作 |\n\n环境变量：`LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）、可选 `LINKFOX_TOOL_GATEWAY`。\n\n## 2. 通用 JSON 入参\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId / region | 是 | |\n| api / operation | 用 `fba_api.py` 时必填 | Amazon operationId |\n| requestBody | 写操作推荐 | 官方 body |\n| query | 否 | 额外 query 对象 |\n| queryString | 否 | 原始查询串（覆盖） |\n| skipDepCheck | 否 | 跳过 auth skill 探测 |\n| marketplaceId | 否 | 自动提升为 marketplaceIds |\n\n路径模板参数（如 `inboundPlanId`、`shipmentId`、`sellerSku`）直接写在同级 JSON。\n\n## 3. 模块索引\n\n完整表见 [`capabilities.md`](capabilities.md)，机器可读见 [`operations.json`](operations.json)。\n\n### 3.1 Eligibility\n\n- `getItemEligibilityPreview`：`asin` + `program`；INBOUND 需 marketplaceIds\n\n### 3.2 Inventory\n\n- `getInventorySummaries`：granularityType + granularityId + marketplaceIds\n- `createInventoryItem` / `addInventory`：marketplaceId + requestBody\n- `deleteInventoryItem`：sellerSku + marketplaceId\n\n### 3.3 Inbound v0\n\n- prepInstructions / labels / billOfLading / shipments / shipmentItems\n\n### 3.4 Inbound 2024-03-20\n\n- InboundPlan CRUD 与状态机：packing → placement → transportation → shipment\n- 异步：`getInboundOperationStatus`\n- items：compliance / labels / prepDetails\n\n### 3.5 Outbound 2020-07-01\n\n- preview / deliveryOffers / fulfillmentOrders CRUD / return / tracking / features\n\n## 4. 官方入口\n\n- [getItemEligibilityPreview](https://developer-docs.amazon.com/sp-api/reference/getitemeligibilitypreview)\n- [FBA Inventory v1](https://developer-docs.amazon.com/sp-api/reference/fba-inventory-v1)\n- [Fulfillment Inbound v2024-03-20](https://developer-docs.amazon.com/sp-api/reference/fulfillment-inbound-v2024-03-20)\n- [Fulfillment Inbound v0](https://developer-docs.amazon.com/sp-api/reference/fulfillment-inbound-v0)\n- [Fulfillment Outbound 2020-07-01](https://developer-docs.amazon.com/sp-api/reference/fulfillment-outbound-2020-07-01)\n\n## 5. 错误处理\n\n| 现象 | 处理 |\n|------|------|\n| 401/402 / 积分 | onboarding.md |\n| 1005 | 放行 `fba/`、`inbound/fba/` |\n| 403 | 角色/权限 |\n| 409/422 | 状态机或参数问题 |\n| 429 | 降速，先征得用户同意 |\n\n## 6. Feedback\n\n`skillName`：`linkfox-amazon-store-fba`\n\n\n---\n\n### eligibility (1)\n\n| Operation | Method | path | 脚本 |\n|-----------|--------|------|------|\n| getItemEligibilityPreview | GET | `fba/inbound/v1/eligibility/itemPreview` | `get_item_eligibility_preview.py` |\n\n### inventory (4)\n\n| Operation | Method | path | 脚本 |\n|-----------|--------|------|------|\n| getInventorySummaries | GET | `fba/inventory/v1/summaries` | `get_inventory_summaries.py` |\n| createInventoryItem | POST | `fba/inventory/v1/items` | `create_inventory_item.py` |\n| deleteInventoryItem | DELETE | `fba/inventory/v1/items/{sellerSku}` | `delete_inventory_item.py` |\n| addInventory | POST | `fba/inventory/v1/items/inventory` | `add_inventory.py` |\n\n### inbound_v0 (6)\n\n| Operation | Method | path | 脚本 |\n|-----------|--------|------|------|\n| getPrepInstructions | GET | `fba/inbound/v0/prepInstructions` | `get_prep_instructions.py` |\n| getLabels | GET | `fba/inbound/v0/shipments/{shipmentId}/labels` | `get_labels_v0.py` |\n| getBillOfLading | GET | `fba/inbound/v0/shipments/{shipmentId}/billOfLading` | `get_bill_of_lading.py` |\n| getShipments | GET | `fba/inbound/v0/shipments` | `get_shipments_v0.py` |\n| getShipmentItemsByShipmentId | GET | `fba/inbound/v0/shipments/{shipmentId}/items` | `get_shipment_items_by_shipment_id.py` |\n| getShipmentItems | GET | `fba/inbound/v0/shipmentItems` | `get_shipment_items.py` |\n\n### inbound (45)\n\n| Operation | Method | path | 脚本 |\n|-----------|--------|------|------|\n| listInboundPlans | GET | `inbound/fba/2024-03-20/inboundPlans` | `list_inbound_plans.py` |\n| createInboundPlan | POST | `inbound/fba/2024-03-20/inboundPlans` | `create_inbound_plan.py` |\n| getInboundPlan | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}` | `get_inbound_plan.py` |\n| listInboundPlanBoxes | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/boxes` | `list_inbound_plan_boxes.py` |\n| cancelInboundPlan | PUT | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/cancellation` | `cancel_inbound_plan.py` |\n| listInboundPlanItems | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/items` | `list_inbound_plan_items.py` |\n| updateInboundPlanName | PUT | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/name` | `update_inbound_plan_name.py` |\n| listPackingGroupBoxes | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingGroups/{packingGroupId}/boxes` | `list_packing_group_boxes.py` |\n| listPackingGroupItems | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingGroups/{packingGroupId}/items` | `list_packing_group_items.py` |\n| setPackingInformation | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingInformation` | `set_packing_information.py` |\n| listPackingOptions | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions` | `list_packing_options.py` |\n| generatePackingOptions | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions` | `generate_packing_options.py` |\n| confirmPackingOption | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions/{packingOptionId}/confirmation` | `confirm_packing_option.py` |\n| listInboundPlanPallets | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/pallets` | `list_inbound_plan_pallets.py` |\n| listPlacementOptions | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions` | `list_placement_options.py` |\n| generatePlacementOptions | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions` | `generate_placement_options.py` |\n| confirmPlacementOption | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions/{placementOptionId}/confirmation` | `confirm_placement_option.py` |\n| getShipment | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}` | `get_inbound_shipment.py` |\n| listShipmentBoxes | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/boxes` | `list_shipment_boxes.py` |\n| listShipmentContentUpdatePreviews | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/contentUpdatePreviews` | `list_shipment_content_update_previews.py` |\n| generateShipmentContentUpdatePreviews | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/contentUpdatePreviews` | `generate_shipment_content_update_previews.py` |\n| getShipmentContentUpdatePreview | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/contentUpdatePreviews/{contentUpdatePreviewId}` | `get_shipment_content_update_preview.py` |\n| confirmShipmentContentUpdatePreview | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/contentUpdatePreviews/{contentUpdatePreviewId}/confirmation` | `confirm_shipment_content_update_preview.py` |\n| getDeliveryChallanDocument | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryChallanDocument` | `get_delivery_challan_document.py` |\n| listDeliveryWindowOptions | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions` | `list_delivery_window_options.py` |\n| generateDeliveryWindowOptions | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions` | `generate_delivery_window_options.py` |\n| confirmDeliveryWindowOptions | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions/{deliveryWindowOptionId}/confirmation` | `confirm_delivery_window_options.py` |\n| listShipmentItems | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/items` | `list_shipment_items.py` |\n| updateShipmentName | PUT | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/name` | `update_shipment_name.py` |\n| listShipmentPallets | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/pallets` | `list_shipment_pallets.py` |\n| cancelSelfShipAppointment | PUT | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/selfShipAppointmentCancellation` | `cancel_self_ship_appointment.py` |\n| getSelfShipAppointmentSlots | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/selfShipAppointmentSlots` | `get_self_ship_appointment_slots.py` |\n| generateSelfShipAppointmentSlots | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/selfShipAppointmentSlots` | `generate_self_ship_appointment_slots.py` |\n| scheduleSelfShipAppointment | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/selfShipAppointmentSlots/{slotId}/schedule` | `schedule_self_ship_appointment.py` |\n| updateShipmentSourceAddress | PUT | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/sourceAddress` | `update_shipment_source_address.py` |\n| updateShipmentTrackingDetails | PUT | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/trackingDetails` | `update_shipment_tracking_details.py` |\n| listTransportationOptions | GET | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions` | `list_transportation_options.py` |\n| generateTransportationOptions | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions` | `generate_transportation_options.py` |\n| confirmTransportationOptions | POST | `inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions/confirmation` | `confirm_transportation_options.py` |\n| listItemComplianceDetails | GET | `inbound/fba/2024-03-20/items/compliance` | `list_item_compliance_details.py` |\n| updateItemComplianceDetails | PUT | `inbound/fba/2024-03-20/items/compliance` | `update_item_compliance_details.py` |\n| createMarketplaceItemLabels | POST | `inbound/fba/2024-03-20/items/labels` | `create_marketplace_item_labels.py` |\n| listPrepDetails | GET | `inbound/fba/2024-03-20/items/prepDetails` | `list_prep_details.py` |\n| setPrepDetails | POST | `inbound/fba/2024-03-20/items/prepDetails` | `set_prep_details.py` |\n| getInboundOperationStatus | GET | `inbound/fba/2024-03-20/operations/{operationId}` | `get_inbound_operation_status.py` |\n\n### outbound (14)\n\n| Operation | Method | path | 脚本 |\n|-----------|--------|------|------|\n| getFulfillmentPreview | POST | `fba/outbound/2020-07-01/fulfillmentOrders/preview` | `get_fulfillment_preview.py` |\n| deliveryOffers | POST | `fba/outbound/2020-07-01/deliveryOffers` | `delivery_offers.py` |\n| listAllFulfillmentOrders | GET | `fba/outbound/2020-07-01/fulfillmentOrders` | `list_all_fulfillment_orders.py` |\n| createFulfillmentOrder | POST | `fba/outbound/2020-07-01/fulfillmentOrders` | `create_fulfillment_order.py` |\n| getPackageTrackingDetails | GET | `fba/outbound/2020-07-01/tracking` | `get_package_tracking_details.py` |\n| listReturnReasonCodes | GET | `fba/outbound/2020-07-01/returnReasonCodes` | `list_return_reason_codes.py` |\n| createFulfillmentReturn | PUT | `fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}/return` | `create_fulfillment_return.py` |\n| getFulfillmentOrder | GET | `fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}` | `get_fulfillment_order.py` |\n| updateFulfillmentOrder | PUT | `fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}` | `update_fulfillment_order.py` |\n| cancelFulfillmentOrder | PUT | `fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}/cancel` | `cancel_fulfillment_order.py` |\n| submitFulfillmentOrderStatusUpdate | PUT | `fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}/status` | `submit_fulfillment_order_status_update.py` |\n| getFeatures | GET | `fba/outbound/2020-07-01/features` | `get_features.py` |\n| getFeatureInventory | GET | `fba/outbound/2020-07-01/features/inventory/{featureName}` | `get_feature_inventory.py` |\n| getFeatureSKU | GET | `fba/outbound/2020-07-01/features/inventory/{featureName}/{sellerSku}` | `get_feature_sku.py` |\n\nFile v1.2.3:references/linkfox-amazon-store-feeds.md\n\n---\nname: linkfox-amazon-store-feeds\ndescription: 亚马逊店铺 Feeds 数据上传。支持库存或 Listing 批量文件的创建、上传、状态查询与取消。\n---\n\n# 亚马逊店铺 Feeds\n\n本 skill 与 **`linkfox-amazon-store-auth`** 等同属 Amazon Store 系列：先 **`POST /spApi/storeTokens`**，再 **`POST /spApi/developerProxy`** 转发 **GET / POST / DELETE**。完整参数、响应与错误码见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 调用 SP-API Feeds v2021-06-30：`createFeedDocument`、`getFeedDocument`、`createFeed`、`getFeed`、`getFeeds`、`cancelFeed`。\n- 通过 `upload_feed_document` 向预签名 URL 上传 feed 文件内容（不经 developerProxy）。\n- 支持库存与 Listing 批量文件的创建、上传、状态轮询、取消与结果文档下载。\n\n### ❌ 边界与限制\n\n- 本 skill **不**代替 Amazon 侧 feed 文件 schema 校验；`feedType`、TSV/XML 格式以官方为准。\n- 上传/下载文档 URL 内容需另行 HTTP PUT/GET（不经 developerProxy），且有时效，过期需重新 `createFeedDocument`。\n- 依赖 **`linkfox-amazon-store-auth`**；应用需具备 Feeds 相关角色，`feedType` 须与上传文件格式匹配。\n- 失败/空结果不得自动换关键词、翻页或连续试探；继续检索前须向用户说明会产生额外消耗。\n\n## 执行流程\n\n库存或 Listing Feed 从创建到结果回执的标准多步编排：\n\n**步骤 1：创建 Feed 文档**\n- 【输入】`sellerId`、`region`、`contentType`（与待上传文件 MIME 一致，如 `text/tab-separated-values; charset=UTF-8`）。\n- 【动作】运行 `create_feed_document.py`，经 developerProxy 调 `createFeedDocument`。\n- 【输出】`feedDocumentId` 与预签名上传 `url`。\n\n**步骤 2：上传文件内容**\n- 【输入】步骤 1 的 `url`、`contentType`，以及 `filePath` / `content` / `contentBase64` 三选一。\n- 【动作】运行 `upload_feed_document.py`，对 `url` 执行 **PUT**（不经 developerProxy）。\n- 【输出】HTTP 上传成功状态；URL 失效则回到步骤 1 重新创建。\n\n**步骤 3：创建 Feed 任务**\n- 【输入】`inputFeedDocumentId`（步骤 1 的 `feedDocumentId`）、`feedType`、`marketplaceIds`、可选 `feedOptions`。\n- 【动作】运行 `create_feed.py`，经 developerProxy 调 `createFeed`。\n- 【输出】`feedId` 与初始 `processingStatus`。\n\n**步骤 4：轮询处理状态**\n- 【输入】`feedId`。\n- 【动作】运行 `get_feed.py`（或 `get_feeds.py` 批量）轮询 `processingStatus`（IN_QUEUE → IN_PROGRESS → DONE / FATAL / CANCELLED）。\n- 【输出】最终状态；DONE 时返回 `resultFeedDocumentId`。\n\n**步骤 5：下载结果文档**\n- 【输入】`resultFeedDocumentId`。\n- 【动作】运行 `get_feed_document.py` 取得结果文档 URL，再自行 HTTP GET 下载结果文件。\n- 【输出】处理结果文件（含错误报告等）。\n\n> 需取消未完成的 Feed 时，用 `cancel_feed.py` 传入 `feedId` 执行 DELETE。\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分）。\n- **Python 脚本**：`python scripts/<脚本名>.py '' [--inline]`。\n- **成本约束**：本工具消耗积分；失败/空结果不得自动重试或连续试探。\n\n**输出策略（脚本默认行为）**：\n- 始终将完整响应写入 `/linkfox///data/linkfox-amazon-store-feeds-.json`（`` 取自环境变量 `SESSION_ID`；禁止写入 /tmp，当前目录不可写则报错）。\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout。\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段长度 + 前 3 条样本）。\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）。\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取。\n\n### 能力一览\n\n| 能力 | path | method | 脚本 |\n|------|------|--------|------|\n| createFeedDocument | `feeds/2021-06-30/documents` | POST | `create_feed_document.py` |\n| getFeedDocument | `feeds/2021-06-30/documents/{feedDocumentId}` | GET | `get_feed_document.py` |\n| createFeed | `feeds/2021-06-30/feeds` | POST | `create_feed.py` |\n| getFeed | `feeds/2021-06-30/feeds/{feedId}` | GET | `get_feed.py` |\n| getFeeds | `feeds/2021-06-30/feeds` | GET | `get_feeds.py` |\n| cancelFeed | `feeds/2021-06-30/feeds/{feedId}` | DELETE | `cancel_feed.py` |\n| 上传文档内容 | createFeedDocument 返回的 URL | PUT | `upload_feed_document.py` |\n\n共享模块：`_spapi_feeds_common.py`。\n\n### 官方参考索引\n\n| 能力 | 文档 |\n|------|------|\n| createFeedDocument | [createFeedDocument](https://developer-docs.amazon.com/sp-api/reference/createfeeddocument) |\n| getFeedDocument | [getFeedDocument](https://developer-docs.amazon.com/sp-api/reference/getfeeddocument) |\n| createFeed | [createFeed](https://developer-docs.amazon.com/sp-api/reference/createfeed) |\n| getFeed | [getFeed](https://developer-docs.amazon.com/sp-api/reference/getfeed) |\n| getFeeds | [getFeeds](https://developer-docs.amazon.com/sp-api/reference/getfeeds) |\n| cancelFeed | [cancelFeed](https://developer-docs.amazon.com/sp-api/reference/cancelfeed) |\n\n## 使用示例\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"\"\n\npython scripts/create_feed_document.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"contentType\":\"text/tab-separated-values; charset=UTF-8\"}'\n\npython scripts/upload_feed_document.py '{\"uploadUrl\":\"\",\"contentType\":\"text/tab-separated-values; charset=UTF-8\",\"filePath\":\"./inventory.tsv\"}'\n\npython scripts/create_feed.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"feedType\":\"POST_FLAT_FILE_INVLOADER_DATA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"inputFeedDocumentId\":\"\"}'\n```\n\n## 展示规则\n\n1. 先看 `developerProxy.errcode` / `httpStatus`；`createFeedDocument` 常为 **201**，`createFeed` 常为 **202**。\n2. **getFeeds** 分页：仅用上一页 `nextToken` 作为下一请求的分页游标（Amazon 侧参数名为 `nextToken`，脚本字段同名）。\n3. **upload** 失败与 SP-API 网关无关，检查 `uploadUrl` 是否过期、`Content-Type` 是否与 `createFeedDocument` 一致。\n4. 网关 path 白名单需包含 `feeds/2021-06-30/` 前缀。\n5. 只呈现数据，不做主观商业建议；处理结果含错误报告时如实展示错误条目。\n\n## 用户表达与场景速查\n\n**适用** —— 亚马逊店铺 Feed 上传与状态管理：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"上传库存 Feed\"、\"提交 Listing 批量文件\" | 创建并上传 Feed |\n| \"查 Feed 处理状态\"、\"Feed 跑完了吗\" | 轮询 processingStatus |\n| \"取消这个 Feed\"、\"撤销未完成的 Feed\" | cancelFeed |\n| \"看下最近的 Feeds 列表\" | getFeeds 分页查询 |\n| \"下载 Feed 结果报告\" | getFeedDocument 取结果 |\n| \"POST_FLAT_FILE 上传\"、\"feedType 怎么填\" | Feed 类型咨询 |\n\n不适用场景见上方【能力边界】。\n\n## 解决认证和积分问题\n\n发生以下异常情况时，采用以下措施来处理：\n\n### 异常情况\n- **未配置 API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应 401 或 402 状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n### 措施\n- 优先采用 skill 内的 onboarding.md 引导解决问题。\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个 skill 并根据它的引导来处理。如未安装请先安装：\n - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个 skill。\n\n---\n\n# linkfox-amazon-store-feeds — API 参考（Feeds v2021-06-30）\n\n## 1. 调用链\n\n| 步骤 | 端点 | 说明 |\n|------|------|------|\n| 1 | `POST {BASE}/spApi/storeTokens` | `{\"sellerId\",\"region\"}` → `accessToken` |\n| 2 | `POST {BASE}/spApi/developerProxy` | 转发 SP-API（除文档上传/下载 URL 外） |\n\n环境变量：`LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`，必填）（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）；`LINKFOX_TOOL_GATEWAY`（可选，默认 `https://tool-gateway.linkfox.com`，回退 `STORE_API_BASE_URL` / `SPAPI_BASE_URL`）。\n\n### developerProxy Body\n\n| 字段 | 说明 |\n|------|------|\n| region | NA / EU / FE |\n| path | 如 `feeds/2021-06-30/feeds`，无前导 `/` |\n| method | GET / POST / DELETE |\n| amzAccessToken | storeTokens 返回值 |\n| queryString | 无 `?` 前缀 |\n| body | POST 时为 JSON 字符串 |\n| contentType | 一般 `application/json` |\n\n网关响应：`errcode`、`httpStatus`、`body`（字符串）。成功 HTTP 可能为 **200 / 201 / 202 / 204**。\n\n---\n\n## 2. 脚本入参摘要\n\n### 公共\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 卖家 ID |\n| region | 是 | 区域 |\n| skipDepCheck | 否 | 跳过本地 auth 探测 |\n\n### create_feed_document.py\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| contentType | 是 | 与将要上传的文件 MIME 一致，如 `text/tab-separated-values; charset=UTF-8` |\n\n解析字段：**`feedDocument`**（含 `feedDocumentId`、`url` 等，以 Amazon 为准）。\n\n### upload_feed_document.py（不经 developerProxy）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| uploadUrl | 是 | createFeedDocument 返回的 `url` |\n| contentType | 是 | 与 createFeedDocument 相同 |\n| filePath | 三选一 | 本地文件路径 |\n| content | 三选一 | UTF-8 字符串内容 |\n| contentBase64 | 三选一 | Base64 编码内容 |\n\n### create_feed.py\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| feedType | 是 | 如 `POST_FLAT_FILE_INVLOADER_DATA` |\n| marketplaceIds | 是 | 1～25 个站点 ID |\n| inputFeedDocumentId | 是 | 已上传内容的文档 ID |\n| feedOptions | 否 | 因 feedType 而异的对象 |\n\n### get_feed.py / cancel_feed.py\n\n| 字段 | 必填 |\n|------|------|\n| feedId | 是 |\n\n### get_feeds.py\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| feedTypes | 条件 | 与 nextToken 二选一；最多 10 个 |\n| nextToken | 条件 | 分页时**单独**传此参数 |\n| marketplaceIds | 否 | 最多 10 个 |\n| processingStatuses | 否 | CANCELLED, DONE, FATAL, IN_PROGRESS, IN_QUEUE |\n| createdSince / createdUntil | 否 | ISO 8601 |\n| pageSize | 否 | 1～100，默认 10 |\n\n### get_feed_document.py\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| feedDocumentId | 是 | |\n| enableContentEncodingUrlHeader | 否 | boolean；GZIP 时便于客户端自动解压 |\n\n---\n\n## 3. Feed 标准流程\n\n```text\ncreateFeedDocument → PUT uploadUrl (upload_feed_document.py)\n → createFeed → poll getFeed until DONE/FATAL\n → getFeedDocument(resultFeedDocumentId) → GET 结果 url\n```\n\n---\n\n## 4. 常见 feedType（示例）\n\n以 [Feed Type Values](https://developer-docs.amazon.com/sp-api/docs/feed-type-values) 为准，例如：\n\n- `POST_PRODUCT_DATA` / `POST_INVENTORY_AVAILABILITY_DATA`\n- `POST_FLAT_FILE_INVLOADER_DATA`\n- `POST_ORDER_FULFILLMENT_DATA`\n\n---\n\n## 5. 错误与限制\n\n- **401**：HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- **402**：HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- **403**：权限或 feedType 未授权。\n- **1005**（网关）：path 未在白名单，需放行 `feeds/2021-06-30/`。\n- **429**：降频；getFeeds 等有独立 usage plan。\n- 上传 URL 有时效，过期需重新 createFeedDocument。\n\nArchive v1.2.2: 223 files, 477614 bytes\n\nFiles: references/authorization-flow.md (13084b), references/linkfox-amazon-store-aplus-content.md (18222b), references/linkfox-amazon-store-auth.md (14451b), references/linkfox-amazon-store-catalog.md (8899b), references/linkfox-amazon-store-customer-feedback.md (9584b), references/linkfox-amazon-store-feeds.md (11788b), references/linkfox-amazon-store-listings.md (41389b), references/linkfox-amazon-store-orders.md (15523b), references/linkfox-amazon-store-pricing.md (24167b), references/linkfox-amazon-store-report.md (19602b), references/linkfox-amazon-store-uploads.md (9692b), references/onboarding.md (2068b), references/quick-start.md (7115b), references/report-requests/accountHealthReport-2020-11-18.md (2723b), references/report-requests/b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.md (2731b), references/report-requests/b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.md (2670b), references/report-requests/endUserDataReport.md (3018b), references/report-requests/marketplaceAsinPageViewMetrics.md (3094b), references/report-requests/promotionReport.md (2938b), references/report-requests/README.md (7506b), references/report-requests/sellerCouponReport.md (2842b), references/report-requests/sellerSalesAndTrafficReport.md (3027b), references/report-requests/sellingPartnerMarketBasketAnalysisReport.md (3467b), references/report-requests/sellingPartnerRepeatPurchaseReport.md (2837b), references/report-requests/sellingPartnerSearchCatalogPerformanceReport.md (3184b), references/report-requests/sellingPartnerSearchQueryPerformanceReport.md (3194b), references/report-requests/sellingPartnerSearchTermsReport.md (2953b), references/report-requests/types/END_USER_DATA_REPORT.md (1751b), references/report-requests/types/FBA_BULK_INVOICE.md (4129b), references/report-requests/types/FEE_DISCOUNTS_REPORT.md (2793b), references/report-requests/types/GET_AFN_INVENTORY_DATA_BY_COUNTRY.md (2929b), references/report-requests/types/GET_AFN_INVENTORY_DATA.md (2656b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL.md (3340b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING.md (3130b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX.md (3090b), references/report-requests/types/GET_B2B_PRODUCT_OPPORTUNITIES_NOT_YET_ON_AMAZON.md (2044b), references/report-requests/types/GET_B2B_PRODUCT_OPPORTUNITIES_RECOMMENDED_FOR_YOU.md (1923b), references/report-requests/types/GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT.md (2021b), references/report-requests/types/GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT.md (1761b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT.md (2034b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT.md (2017b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT.md (1809b), references/report-requests/types/GET_CONVERGED_FLAT_FILE_PENDING_ORDERS_DATA.md (2645b), references/report-requests/types/GET_COUPON_PERFORMANCE_REPORT.md (1815b), references/report-requests/types/GET_CSV_MFN_PRIME_RETURNS_REPORT.md (3081b), references/report-requests/types/GET_DATE_RANGE_FINANCIAL_HOLDS_DATA.md (2919b), references/report-requests/types/GET_EASYSHIP_DOCUMENTS.md (2653b), references/report-requests/types/GET_EASYSHIP_PICKEDUP.md (2585b), references/report-requests/types/GET_EASYSHIP_WAITING_FOR_PICKUP.md (2657b), references/report-requests/types/GET_EPR_ANNUAL_REPORTS.md (2993b), references/report-requests/types/GET_EPR_MONTHLY_REPORTS.md (3016b), references/report-requests/types/GET_EPR_QUARTERLY_REPORTS.md (3011b), references/report-requests/types/GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA.md (2943b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_RETURNS_DATA.md (2816b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_PROMOTION_DATA.md (2894b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_REPLACEMENT_DATA.md (2768b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_SALES_DATA.md (2991b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_TAXES_DATA.md (2869b), references/report-requests/types/GET_FBA_FULFILLMENT_INBOUND_NONCOMPLIANCE_DATA.md (2769b), references/report-requests/types/GET_FBA_FULFILLMENT_LONGTERM_STORAGE_FEE_CHARGES_DATA.md (2911b), references/report-requests/types/GET_FBA_FULFILLMENT_REMOVAL_ORDER_DETAIL_DATA.md (2962b), references/report-requests/types/GET_FBA_FULFILLMENT_REMOVAL_SHIPMENT_DETAIL_DATA.md (2965b), references/report-requests/types/GET_FBA_INVENTORY_PLANNING_DATA.md (2846b), references/report-requests/types/GET_FBA_MYI_ALL_INVENTORY_DATA.md (2771b), references/report-requests/types/GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA.md (2772b), references/report-requests/types/GET_FBA_OVERAGE_FEE_CHARGES_DATA.md (2712b), references/report-requests/types/GET_FBA_RECOMMENDED_REMOVAL_DATA.md (2885b), references/report-requests/types/GET_FBA_REIMBURSEMENTS_DATA.md (2720b), references/report-requests/types/GET_FBA_STORAGE_FEE_CHARGES_DATA.md (2733b), references/report-requests/types/GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING.md (2948b), references/report-requests/types/GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL.md (3105b), references/report-requests/types/GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL.md (3082b), references/report-requests/types/GET_FLAT_FILE_ARCHIVED_ORDERS_DATA_BY_ORDER_DATE.md (3057b), references/report-requests/types/GET_FLAT_FILE_MFN_SKU_RETURN_ATTRIBUTES_REPORT.md (3133b), references/report-requests/types/GET_FLAT_FILE_OPEN_LISTINGS_DATA.md (3767b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING.md (3347b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING.md (3362b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_TAX.md (3295b), references/report-requests/types/GET_FLAT_FILE_PENDING_ORDERS_DATA.md (2624b), references/report-requests/types/GET_FLAT_FILE_RETURNS_DATA_BY_RETURN_DATE.md (2999b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: linkfox-amazon-store-operations\ndisplay_name: Linkfox 亚马逊店铺运营\ndisplay_name_en: LinkFox Amazon Store Operations\ndescription: 亚马逊店铺 SP-API 运营一站式 AI 工具集，整合授权/订单/Listing/定价/Catalog/报告/Feeds/买家反馈/文件上传/A+ Content 等 10 项子能力，覆盖店铺日常运营全链路。\ndescription_zh: 亚马逊店铺 SP-API 运营工具集，整合 10 项子能力：店铺授权与令牌管理、订单查询与发货确认、Listing 刊登与限制、定价与比价（含批量 FOEP/竞争摘要）、Catalog 目录检索、95+ 种后台报告下载、Feeds 批量上传、买家反馈洞察、文件预签名上传、A+ Content 管理。经 LinkFox 网关调用 SP-API，需先授权取令牌。当用户需要亚马逊店铺运营、订单、Listing、定价、报告、批量上传、A+ 页面或买家反馈分析时触发。参数见 references/，脚本见 scripts/。\ndescription_en: One-stop Amazon store SP-API operations toolkit integrating 10 sub-capabilities: store OAuth authorization & token management, order query & shipment confirmation, Listings management (PATCH/PUT/DELETE/restrictions/Product Type definitions), product pricing & comparison (batch FOEP & competitive summary), Catalog retrieval, automated download of 95+ Seller Central report types (request→poll→download→extract), Feeds bulk data upload, customer feedback insights (review topics/trends/return reasons), presigned file upload, and A+ Content management. All routed through the LinkFox gateway POST /spApi/developerProxy to Amazon SP-API; requires prior store authorization to obtain an access token. Triggered when the user needs Amazon store operations, order management, listing, pricing, report download, bulk upload, A+ pages, or customer feedback analysis. Full params per sub-capability in references/, scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox 亚马逊店铺运营（Amazon Store Operations）\n\n亚马逊店铺 SP-API 运营一站式 AI 工具集，整合 **10 项子能力**，覆盖授权与令牌、订单、Listing 刊登、定价、Catalog 目录、报告、Feeds 批量上传、买家反馈、文件上传与 A+ Content。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n\n以下能力均经 tool_key `amazon_sp_api`（亚马逊 SP-API 网关 `POST /spApi/developerProxy` 转发上游 SP-API，授权类直连 `POST /spApi/*`）实现，整合 10 项子能力：\n\n- **授权与令牌管理（linkfox-amazon-store-auth）**：生成亚马逊店铺 OAuth 授权链接、查询已授权店铺列表、刷新令牌、查询指定店铺访问令牌；是所有下游 SP-API 操作的前置依赖（取 `accessToken`）。\n- **订单管理（linkfox-amazon-store-orders）**：订单列表检索、单笔订单详情、买家信息、收货地址、订单行项目、管制订单核验信息查询，以及发货状态更新、确认发货、管制订单核验状态更新（SP-API Orders）。\n- **Listing 刊登管理（linkfox-amazon-store-listings）**：单条/列表检索刊登、PATCH 部分更新、PUT 创建/全量更新、DELETE 删除刊登，查询 ASIN 刊登限制（是否可售）、Product Type 列表搜索与 JSON Schema 定义查询（SP-API Listings & Definitions）。\n- **商品定价与比价（linkfox-amazon-store-pricing）**：单条/批量获取 ASIN/SKU 定价、竞争性报价、Listing/Item 报价、购物车预期价（FOEP）与竞争摘要（SP-API Product Pricing，含 batch 接口）。\n- **Catalog 目录检索（linkfox-amazon-store-catalog）**：按 ASIN 获取商品目录详情、按关键词/标识符检索商品目录、查询商品所属类目节点，返回摘要/图片/销售排名等（SP-API Catalog Items）。\n- **报告自动化（linkfox-amazon-store-report）**：95+ 种卖家后台报告（库存/订单/销售流量/财务结算/FBA/Brand Analytics 等）的端到端获取——请求→轮询→下载→解压，并生成限时本机 HTTP 下载链接（SP-API Reports）。\n- **Feeds 批量数据上传（linkfox-amazon-store-feeds）**：库存或 Listing 批量文件的 Feed 文档创建、文件上传、Feed 任务创建、状态轮询、列表查询、取消与结果文档下载（SP-API Feeds）。\n- **买家反馈洞察（linkfox-amazon-store-customer-feedback）**：按 ASIN 或类目节点分析评论主题、评价趋势、退货原因与星级影响（MENTIONS / STAR_RATING_IMPACT）（SP-API Customer Feedback）。\n- **文件预签名上传（linkfox-amazon-store-uploads）**：创建上传目的地生成预签名 URL，再向该 URL 上传文件，供 A+ Content、Messaging 等下游 API 使用（SP-API Uploads）。\n- **A+ Content 管理（linkfox-amazon-store-aplus-content）**：A+ 文档检索、创建、获取、更新、ASIN 关联校验/全量替换、发布记录查询、审核提交与暂停展示（SP-API A+ Content Management）。\n- 覆盖美国、英国、德国、日本、法国、意大利、西班牙等站点（`marketplaceIds`/`marketplaceId` 指定，`region` 取 `NA`/`EU`/`FE` 且须与授权区域一致）。\n\n### ❌ 边界与限制\n\n- **API Key 必需**：所有工具均需环境变量 `LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）；各子能力独立计费、独立限频。\n- **授权前置**：除 `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`）。\n- **计费约束**：同一会话同一参数组合默认只调用一次（脚本带本地缓存）；失败或空结果不得自动改参数、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 `skills-version.json` 对应条目与 references 内 api.md 的 `costToken` 字段）。\n- **不在范围内**：选品/关键词/竞品/评论挖掘等选品调研（用 `linkfox-amazon-product-selection` 系列）；广告投放与管理（用 Amazon Ads 系列）；前台实时搜索/商品详情/前台评论（用 amazon_search / amazon_product_detail / amazon_reviews 系列）；物流与供应链规划、1688 找货源、其他平台运营、与平台或卖家的直接沟通、实时库存与订单的自动决策。\n- **数据时效**：SP-API 返回为亚马逊后台当前状态；报告类为按 `dataStartTime`/`dataEndTime` 拉取的历史快照；`accessToken` 约 1 小时过期，过期需 `refresh_token.py` 刷新或重新 `store_tokens.py` 获取。\n\n## 工具选择指南\n\n按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。\n\n| 需求 / 用户说 | 默认推荐（子能力） | 何时换用其他 |\n|---|---|---|\n| 授权/绑定亚马逊店铺、查已授权店铺、令牌过期 | `linkfox-amazon-store-auth` | — |\n| 查订单列表 / 单笔订单详情 / 买家信息 / 收货地址 / 订单行 | `linkfox-amazon-store-orders` | 要批量下载历史订单报告用 `linkfox-amazon-store-report`（reportType 订单类） |\n| 确认发货 / 标记已发货 / 更新发货状态 | `linkfox-amazon-store-orders`（confirm_shipment / update_shipment_status） | — |\n| 单条 Listing 改标题/价格/属性、新建/全量更新/删除刊登 | `linkfox-amazon-store-listings`（PATCH/PUT/DELETE） | 要批量上传/修改多条 Listing 文件用 `linkfox-amazon-store-feeds`（feedType=Listing 类） |\n| 查 ASIN 能不能卖 / 刊登限制 | `linkfox-amazon-store-listings`（get_listings_restrictions） | — |\n| Product Type 有哪些 / 某类型的字段 Schema | `linkfox-amazon-store-listings`（search/get_definitions_product_type） | — |\n| 查商品定价 / 这个 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` |\n| 批量查报价（多个 ASIN/SKU） | `linkfox-amazon-store-pricing`（post_item_offers_batch / post_listing_offers_batch） | 仅 1 个用单条 `get_item_offers` / `get_listing_offers` |\n| 查商品目录 / 按 ASIN 查商品信息 / 关键词搜目录 / 类目节点 | `linkfox-amazon-store-catalog` | 要前台实时搜索结果（非店铺目录）用 amazon_search 系列（选品 skill） |\n| 下载卖家后台报告（库存/订单/销售流量/财务/FBA/Brand Analytics） | `linkfox-amazon-store-report`（get_report ⭐端到端） | 要逐条查订单用 `linkfox-amazon-store-orders` |\n| 批量上传库存 / 批量改 Listing（Feed 文件） | `linkfox-amazon-store-feeds`（create_feed_document→upload→create_feed→get_feed） | 单条 Listing 改用 `linkfox-amazon-store-listings` |\n| 查 Feed 处理状态 / 取消 Feed / 下载 Feed 结果 | `linkfox-amazon-store-feeds`（get_feed / cancel_feed / get_feed_document） | — |\n| 这个 ASIN 评论主题/差评痛点/星级影响 | `linkfox-amazon-store-customer-feedback`（get_item_review_topics，sortBy=STAR_RATING_IMPACT 看星级影响） | 要前台逐条评论文本用 amazon_reviews 系列（选品 skill）；要类目级反馈用 `get_browse_node_review_topics` |\n| 这个 ASIN 评价趋势 / 类目评论趋势 | `linkfox-amazon-store-customer-feedback`（get_item_review_trends / get_browse_node_review_trends） | — |\n| 退货原因 / 类目退货主题趋势 | `linkfox-amazon-store-customer-feedback`（get_browse_node_return_topics / trends） | — |\n| 上传 A+ 图片 / Messaging 附件 / 生成预签名上传 URL | `linkfox-amazon-store-uploads`（create_upload_destination_for_resource→upload_to_destination） | — |\n| A+ 页面检索/创建/获取/更新 | `linkfox-amazon-store-aplus-content` | 需先上传图片用 `linkfox-amazon-store-uploads` 取得 URL |\n| A+ 关联 ASIN / 校验 ASIN / 审核提交 / 暂停展示 / 发布记录 | `linkfox-amazon-store-aplus-content` | — |\n\n### 工具选择思路\n\n- **重要**：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参，从中调研出最合适的子能力，并推荐用户，让用户自己决定。\n- 满足程度同等的前提下，向用户推荐\"默认推荐子能力\"。\n- **单条 vs 批量**：单条写操作优先 `linkfox-amazon-store-listings`；批量文件操作优先 `linkfox-amazon-store-feeds`。\n- **店铺目录 vs 前台搜索**：查自己店铺后台可售商品/类目用 `linkfox-amazon-store-catalog`；查前台实时 SERP/竞品用选品 skill 的 amazon_search 系列。\n\n## 业务需求路由速查\n\n按【工具选择指南】定到子能力后，下表查端点、脚本与 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/*`。\n\n### 子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（10 项）\n\n**amazon_sp_api**\n\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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（辅助） |\n| 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 |\n| 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 |\n| 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 |\n| 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_conte\n\nArchive v1.2.1: 223 files, 477747 bytes\n\nFiles: references/authorization-flow.md (13084b), references/linkfox-amazon-store-aplus-content.md (18222b), references/linkfox-amazon-store-auth.md (14451b), references/linkfox-amazon-store-catalog.md (8899b), references/linkfox-amazon-store-customer-feedback.md (9584b), references/linkfox-amazon-store-feeds.md (11788b), references/linkfox-amazon-store-listings.md (41389b), references/linkfox-amazon-store-orders.md (15523b), references/linkfox-amazon-store-pricing.md (24167b), references/linkfox-amazon-store-report.md (19602b), references/linkfox-amazon-store-uploads.md (9692b), references/onboarding.md (2068b), references/quick-start.md (7115b), references/report-requests/accountHealthReport-2020-11-18.md (2723b), references/report-requests/b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.md (2731b), references/report-requests/b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.md (2670b), references/report-requests/endUserDataReport.md (3018b), references/report-requests/marketplaceAsinPageViewMetrics.md (3094b), references/report-requests/promotionReport.md (2938b), references/report-requests/README.md (7506b), references/report-requests/sellerCouponReport.md (2842b), references/report-requests/sellerSalesAndTrafficReport.md (3027b), references/report-requests/sellingPartnerMarketBasketAnalysisReport.md (3467b), references/report-requests/sellingPartnerRepeatPurchaseReport.md (2837b), references/report-requests/sellingPartnerSearchCatalogPerformanceReport.md (3184b), references/report-requests/sellingPartnerSearchQueryPerformanceReport.md (3194b), references/report-requests/sellingPartnerSearchTermsReport.md (2953b), references/report-requests/types/END_USER_DATA_REPORT.md (1751b), references/report-requests/types/FBA_BULK_INVOICE.md (4129b), references/report-requests/types/FEE_DISCOUNTS_REPORT.md (2793b), references/report-requests/types/GET_AFN_INVENTORY_DATA_BY_COUNTRY.md (2929b), references/report-requests/types/GET_AFN_INVENTORY_DATA.md (2656b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL.md (3340b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING.md (3130b), references/report-requests/types/GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX.md (3090b), references/report-requests/types/GET_B2B_PRODUCT_OPPORTUNITIES_NOT_YET_ON_AMAZON.md (2044b), references/report-requests/types/GET_B2B_PRODUCT_OPPORTUNITIES_RECOMMENDED_FOR_YOU.md (1923b), references/report-requests/types/GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT.md (2021b), references/report-requests/types/GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT.md (1761b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT.md (2034b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT.md (2017b), references/report-requests/types/GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT.md (1809b), references/report-requests/types/GET_CONVERGED_FLAT_FILE_PENDING_ORDERS_DATA.md (2645b), references/report-requests/types/GET_COUPON_PERFORMANCE_REPORT.md (1815b), references/report-requests/types/GET_CSV_MFN_PRIME_RETURNS_REPORT.md (3081b), references/report-requests/types/GET_DATE_RANGE_FINANCIAL_HOLDS_DATA.md (2919b), references/report-requests/types/GET_EASYSHIP_DOCUMENTS.md (2653b), references/report-requests/types/GET_EASYSHIP_PICKEDUP.md (2585b), references/report-requests/types/GET_EASYSHIP_WAITING_FOR_PICKUP.md (2657b), references/report-requests/types/GET_EPR_ANNUAL_REPORTS.md (2993b), references/report-requests/types/GET_EPR_MONTHLY_REPORTS.md (3016b), references/report-requests/types/GET_EPR_QUARTERLY_REPORTS.md (3011b), references/report-requests/types/GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA.md (2943b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_RETURNS_DATA.md (2816b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_PROMOTION_DATA.md (2894b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_REPLACEMENT_DATA.md (2768b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_SHIPMENT_SALES_DATA.md (2991b), references/report-requests/types/GET_FBA_FULFILLMENT_CUSTOMER_TAXES_DATA.md (2869b), references/report-requests/types/GET_FBA_FULFILLMENT_INBOUND_NONCOMPLIANCE_DATA.md (2769b), references/report-requests/types/GET_FBA_FULFILLMENT_LONGTERM_STORAGE_FEE_CHARGES_DATA.md (2911b), references/report-requests/types/GET_FBA_FULFILLMENT_REMOVAL_ORDER_DETAIL_DATA.md (2962b), references/report-requests/types/GET_FBA_FULFILLMENT_REMOVAL_SHIPMENT_DETAIL_DATA.md (2965b), references/report-requests/types/GET_FBA_INVENTORY_PLANNING_DATA.md (2846b), references/report-requests/types/GET_FBA_MYI_ALL_INVENTORY_DATA.md (2771b), references/report-requests/types/GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA.md (2772b), references/report-requests/types/GET_FBA_OVERAGE_FEE_CHARGES_DATA.md (2712b), references/report-requests/types/GET_FBA_RECOMMENDED_REMOVAL_DATA.md (2885b), references/report-requests/types/GET_FBA_REIMBURSEMENTS_DATA.md (2720b), references/report-requests/types/GET_FBA_STORAGE_FEE_CHARGES_DATA.md (2733b), references/report-requests/types/GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING.md (2948b), references/report-requests/types/GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL.md (3105b), references/report-requests/types/GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL.md (3082b), references/report-requests/types/GET_FLAT_FILE_ARCHIVED_ORDERS_DATA_BY_ORDER_DATE.md (3057b), references/report-requests/types/GET_FLAT_FILE_MFN_SKU_RETURN_ATTRIBUTES_REPORT.md (3133b), references/report-requests/types/GET_FLAT_FILE_OPEN_LISTINGS_DATA.md (3767b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING.md (3347b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING.md (3362b), references/report-requests/types/GET_FLAT_FILE_ORDER_REPORT_DATA_TAX.md (3295b), references/report-requests/types/GET_FLAT_FILE_PENDING_ORDERS_DATA.md (2624b), references/report-requests/types/GET_FLAT_FILE_RETURNS_DATA_BY_RETURN_DATE.md (2999b)\n\nArchive v1.2.0: 220 files, 466867 bytes\n\nFiles: references/authorization-flow.md (13084b), references/linkfox-amazon-store-aplus-content.md (18222b), references/linkfox-amazon-store-auth.md (14451b), references/linkfox-amazon-store-catalog.md (8899b), references/linkfox-amazon-store-customer-feedback.md (9584b), references/linkfox-amazon-store-feeds.md (11788b), references/linkfox-amazon-store-listings.md (4138...","readmeExcerpt":"Skill: Linkfox 亚马逊店铺运营 Owner: linkfox-ai Summary: 整合亚马逊店铺 SP-API，实现授权管理、订单处理、Listing 发布、定价查询、目录检索、报告下载、批量上传、买家反馈分析及A+内容管理。 Tags: latest:1.2.3 Version history: v1.2.3 | 2026-08-14T14:47:28.603Z | user Update from 1.2.2 to 1.2.3 v1.2.2 | 2026-08-07T10:44:29.819Z | user Update from 1.2.1 to 1.2.2 v1.2.1 | 2026-08-05T08:59:42.602Z | user Update from 1.2.0 to 1.2.1 v1.2.0 | 2026-07-16T04:00:08.845Z | user Update from 1.0.","codeSnippets":[],"executableExamples":[{"language":"json","snippet":"{\"region\": \"NA\", \"sellerName\": \"My Store\"}"},{"language":"json","snippet":"{\"sellerId\": \"A1EC6SZ7XAMURH\", \"region\": \"NA\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"], \"lastUpdatedAfter\": \"2026-05-01T00:00:00Z\"}"},{"language":"json","snippet":"{\"sellerId\": \"A1BCDEFGHIJK2\", \"region\": \"NA\", \"sku\": \"My-Seller-SKU-001\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"], \"productType\": \"LUGGAGE\", \"requirements\": \"LISTING\", \"attributes\": {\"item_name\": [{\"value\": \"Example Title\", \"marketplace_id\": \"ATVPDKIKX0DER\"}]}}"},{"language":"json","snippet":"{\"sellerId\": \"A1...\", \"region\": \"NA\", \"asin\": \"B08N5WRWNW\", \"marketplaceId\": \"ATVPDKIKX0DER\", \"itemType\": \"Asin\", \"asins\": [\"B08N5WRWNW\"], \"itemCondition\": \"New\"}"},{"language":"json","snippet":"{\"sellerId\": \"A1...\", \"region\": \"NA\", \"asin\": \"B08N5WRWNW\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"], \"includedData\": [\"summaries\", \"images\"]}"},{"language":"json","snippet":"{\"sellerId\": \"A1EC6SZ7XAMURH\", \"region\": \"NA\", \"reportType\": \"GET_MERCHANT_LISTINGS_ALL_DATA\", \"marketplaceIds\": [\"ATVPDKIKX0DER\"]}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: linkfox-amazon-store-operations\ndisplay_name: Linkfox 亚马逊店铺运营\ndisplay_name_en: LinkFox Amazon Store Operations\ndescription: 亚马逊店铺 SP-API 运营一站式 AI 工具集，整合授权/订单/Listing/定价/Catalog/报告/Feeds/买家反馈/文件上传/A+ Content/External Fulfillment/FBA 等 12 项子能力，覆盖店铺日常运营全链路。\ndescription_zh: 亚马逊店铺 SP-API 运营工具集，整合 12 项子能力：店铺授权与令牌管理、订单查询与发货确认、Listing 刊登与限制、定价与比价（含批量 FOEP/竞争摘要）、Catalog 目录检索、95+ 种后台报告下载、Feeds 批量上传、买家反馈洞察、文件预签名上传、A+ Content 管理、External Fulfillment（location 库存/履约单/面单发票/退货）、FBA（入仓资格/库存/Inbound/MCF）。经 LinkFox 网关调用 SP-API，需先授权取令牌。当用户需要亚马逊店铺运营、订单、Listing、定价、报告、批量上传、A+ 页面、买家反馈分析、External Fulfillment 或 FBA 入仓/库存/MCF 时触发。参数见 references/，脚本见 scripts/。\ndescription_en: One-stop Amazon store SP-API operations toolkit integrating 10 sub-capabilities: store OAuth authorization & token management, order query & shipment confirmation, Listings management (PATCH/PUT/DELETE/restrictions/Product Type definitions), product pricing & comparison (batch FOEP & competitive summary), Catalog retrieval, automated download of 95+ Seller Central report types (request→poll→download→extract), Feeds bulk data upload, customer feedback insights (review topics/trends/return reasons), presigned file upload, and A+ Content management. All routed through the LinkFox gateway POST /spApi/developerProxy to Amazon SP-API; requires prior store authorization to obtain an access token. Triggered when the user needs Amazon store operations, order management, listing, pricing, report download, bulk upload, A+ pages, or customer feedback analysis. Full params per sub-capability in references/, scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox 亚马逊店铺运营（Amazon Store Operations）\n\n亚马逊店铺 SP-API 运营一站式 AI 工具集，整合 **12 项子能力**，覆盖授权与令牌、订单、Listing 刊登、定价、Catalog 目录、报告、Feeds 批量上传、买家反馈、文件上传、A+ Content、External Fulfillment 与 FBA。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n\n以下能力均经 tool_key `amazon_sp_api`（亚马逊 SP-API 网关 `POST /spApi/developerProxy` 转发上游 SP-API，授权类直连 `POST /spApi/*`）实现，整合 12 项子能力：\n\n- **授权与令牌管理（linkfox-amazon-store-auth）**：生成亚马逊店铺 OAuth 授权链接、查询已授权店铺列表、刷新令牌、查询指定店铺访问令牌；是所有下游 SP-API 操作的前置依赖（取 `accessToken`）。\n- **订单管理（linkfox-amazon-store-orders）**：订单列表检索、单笔订单详情、买家信息、收货地址、订单行项目、管制订单核验信息查询，以及发货状态更新、确认发货、管制订单核验状态更新（SP-API Orders）。\n- **Listing 刊登管理（linkfox-amazon-store-listings）**：单条/列表检索刊登、PATCH 部分更新、PUT 创建/全量更新、DELETE 删除刊登，查询 ASIN 刊登限制（是否可售）、Product Type 列表搜索与 JSON Schema 定义查询（SP-API Listings & Definitions）。\n- **商品定价与比价（linkfox-amazon-store-pricing）**：单条/批量获取 ASIN/SKU 定价、竞争性报价、Listing/Item 报价、购物车预期价（FOEP）与竞争摘要（SP-API Product Pricing，含 batch 接口）。\n- **Catalog 目录检索（linkfox-amazon-store-catalog）**：按 ASIN 获取商品目录详情、按关键词/标识符检索商品目录、查询商品所属类目节点，返回摘要/图片/销售排名等（SP-API Catalog Items）。\n- **报告自动化（linkfox-amazon-store-report）**：95+ 种卖家后台报告（库存/订单/销售流量/财务结算/FBA/Brand Analytics 等）的端到端获取——请求→轮询→下载→解压，并生成限时本机 HTTP 下载链接（SP-API Reports）。\n- **Feeds 批量数据上传（linkfox-amazon-store-feeds）**：库存或 Listing 批量文件的 Feed 文档创建、文件上传、Feed 任务创建、状态轮询、列表查询、取消与结果文档下载（SP-API"},{"path":"references/report-requests/README.md","content":"# 报告请求与文档格式（按 GitHub schema 分文件）\n\n> 与 [amzn/selling-partner-api-models/schemas/reports](https://github.com/amzn/selling-partner-api-models/tree/main/schemas/reports) 中的 JSON Schema **一一对应**。\n\n## `reportType` 全覆盖（含无 JSON 的 Flat File）\n\n`references/report-types.md` 表格中的 **每一个** `reportType` 均有专页 → **[types/README.md](./types/README.md)**（109 个：`types/.md`）。 \n有 GitHub JSON 的条目会链回下表中的 `*.md`；其余条目给出最小 CreateReport 模板并指向 [Report type values](https://developer-docs.amazon.com/sp-api/docs/report-type-values)。\n\n## 索引（仅含官方 `schemas/reports/*.json`）\n\n| 文档 | 上游 Schema | 涉及 `reportType` |\n|------|-------------|-------------------|\n| [accountHealthReport-2020-11-18.md](./accountHealthReport-2020-11-18.md) | [`accountHealthReport-2020-11-18.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/accountHealthReport-2020-11-18.json) | 见专页（账户状况结果 JSON；`reportType` 以官方 Report Type Values 为准） |\n| [b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.md](./b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.md) | [`b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/b2bProductOpportunitiesNotYetOnAmazonReport-2020-11-19.json) | `GET_B2B_PRODUCT_OPPORTUNITIES_NOT_YET_ON_AMAZON` |\n| [b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.md](./b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.md) | [`b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/b2bProductOpportunitiesRecommendedForYouReport-2020-11-19.json) | `GET_B2B_PRODUCT_OPPORTUNITIES_RECOMMENDED_FOR_YOU` |\n| [endUserDataReport.md](./endUserDataReport.md) | [`endUserDataReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/endUserDataReport.json) | `END_USER_DATA_REPORT` |\n| [marketplaceAsinPageViewMetrics.md](./marketplaceAsinPageViewMetrics.md) | [`marketplaceAsinPageViewMetrics.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/marketplaceAsinPageViewMetrics.json) | `MARKETPLACE_ASIN_PAGE_VIEW_METRICS` |\n| [promotionReport.md](./promotionReport.md) | [`promotionReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/promotionReport.json) | `GET_PROMOTION_PERFORMANCE_REPORT` |\n| [sellerCouponReport.md](./sellerCouponReport.md) | [`sellerCouponReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellerCouponReport.json) | `GET_COUPON_PERFORMANCE_REPORT` |\n| [sellerSalesAndTrafficReport.md](./sellerSalesAndTrafficReport.md) | [`sellerSalesAndTrafficReport.json`](https://raw.githubusercontent.com/amzn/selling-partner-api-models/main/schemas/reports/sellerSalesAndTrafficReport.json) | `GET_SALES_AND_TRAFFIC_REPORT` |\n| [sellingPartnerMarketBasketAnalysisReport.md](./sel"},{"path":"references/report-requests/types/README.md","content":"# 按 `reportType` 全覆盖 — 请求说明专页\n\n本目录为 `references/report-types.md` 中**每一个**报告枚举提供一页说明：\n\n- 标注是否在 Amazon [`schemas/reports`](https://github.com/amzn/selling-partner-api-models/tree/main/schemas/reports) 有 JSON 结果 Schema，并链到 `references/report-requests/` 下对应专页。\n- 无独立 JSON 的类型：给出 **CreateReport 最小请求体** 与官方 [Report type values](https://developer-docs.amazon.com/sp-api/docs/report-type-values) 入口。\n- 每页顶部另有 **「官方说明」或「官方索引（Report type values）」**：从亚马逊各子类文档自动摘录；其中在 `report-requests/` 下**已有 GitHub Schema 专页**（`*.md` 与 `schemas/reports/*.json` 对应）的类型，仅保留 **Schema 链、Amazon 锚点、权限/站点类字段**，避免与专页中的 Schema 摘要、`reportOptions` 表重复。其余 Flat File 类型仍为完整「官方说明」。 \n 更新摘录：将 15 个子页 HTML 放入 `references/_spapi_docs_cache/`，运行 `scripts/merge_report_type_values_from_cache.py`（依赖见该脚本注释）。\n\n**共计**：109 个 `reportType`。\n\n## 索引\n\n| reportType | 分类（report-types.md） | 类型 | 专页 |\n|------------|-------------------------|------|------|\n| `FEE_DISCOUNTS_REPORT` | 1. Amazon Business Reports | Flat/XML（文档） | [FEE_DISCOUNTS_REPORT.md](./FEE_DISCOUNTS_REPORT.md) |\n| `GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT.md](./GET_BRAND_ANALYTICS_SEARCH_CATALOG_PERFORMANCE_REPORT.md) |\n| `GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT.md](./GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT.md) |\n| `GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT.md](./GET_BRAND_ANALYTICS_MARKET_BASKET_REPORT.md) |\n| `GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT.md](./GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT.md) |\n| `GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT.md](./GET_BRAND_ANALYTICS_REPEAT_PURCHASE_REPORT.md) |\n| `GET_VENDOR_REAL_TIME_INVENTORY_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_REAL_TIME_INVENTORY_REPORT.md](./GET_VENDOR_REAL_TIME_INVENTORY_REPORT.md) |\n| `GET_VENDOR_REAL_TIME_TRAFFIC_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_REAL_TIME_TRAFFIC_REPORT.md](./GET_VENDOR_REAL_TIME_TRAFFIC_REPORT.md) |\n| `GET_VENDOR_REAL_TIME_SALES_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_REAL_TIME_SALES_REPORT.md](./GET_VENDOR_REAL_TIME_SALES_REPORT.md) |\n| `GET_VENDOR_SALES_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_SALES_REPORT.md](./GET_VENDOR_SALES_REPORT.md) |\n| `GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT.md](./GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT.md) |\n| `GET_VENDOR_TRAFFIC_REPORT` | 2. Analytics Reports | JSON Schema 专页 | [GET_VENDOR_TRAFFIC_REPORT.md](./GET_VENDOR_TRAFFIC_REPORT.md) |\n| `GET_VENDOR_FORECASTING_REPORT"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-amazon-store-operations\",\n \"version\": \"1.2.3\",\n \"publishedAt\": 1786718848603\n}"},{"path":"references/authorization-flow.md","content":"# 亚马逊店铺授权流程详细说明\n\n本文档提供所有授权相关接口的详细说明，包括请求参数、返回值、错误处理等。\n\n---\n\n## 1. 获取授权URL\n\n### 接口信息\n\n- **路径**: `/spApi/authorizeUrl`\n- **方法**: POST (RouteMapping)\n- **鉴权**: 需要（从 Token 中获取 userId）\n- **实现**: `SpApiController.java:52`\n\n### 请求参数 (SpApiAuthorizeUrlReq)\n\n| 参数 | 类型 | 必填 | 说明 | 示例 |\n|------|------|------|------|------|\n| region | String | ✅ 是 | 区域代码：NA/EU/FE | \"NA\" |\n| sellerName | String | ✅ **是（必填）** | 店铺名 / 卖家展示名称，用于在已授权店铺列表中区分账号；**调用前必须向用户确认并传入非空字符串**，不可省略 | \"My Amazon Store\" |\n| central | String | ❌ 否 | 中心站点 | - |\n| marketplace | String | ❌ 否 | 市场代码 | - |\n\n### 返回结果 (SpApiAuthorizeUrlVo)\n\n```json\n{\n \"authorizeUrl\": \"https://sellercentral.amazon.com/...\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| authorizeUrl | String | 亚马逊授权链接，用户需在浏览器中打开 |\n\n### 业务逻辑\n\n1. 校验 region 参数（必须为 NA/EU/FE）；**本 Skill 约定**：`sellerName` 须为非空字符串（与用户在 LinkFox 侧展示、区分店铺一致），AI/脚本在调用前应向用户确认店铺名。\n2. 构建 state 参数：\n - 包含 gateway.url + /spApi/oauth/callback\n - 附加 userId, region, sellerName\n3. 调用紫鸟代理接口 `/developer-proxy/v1/authorize/url`\n4. 返回授权链接给用户\n\n### 错误码\n\n| 错误码 | 说明 | 处理建议 |\n|--------|------|----------|\n| 1002 | 缺少 region 参数 | 必须提供 region (NA/EU/FE) |\n| 1003 | 获取授权地址失败 | 检查网络连接和白名单配置，稍后重试 |\n\n### 使用示例\n\n**请求**:\n```json\n{\n \"region\": \"NA\",\n \"sellerName\": \"MyStore\"\n}\n```\n\n**响应**:\n```json\n{\n \"authorizeUrl\": \"https://sellercentral.amazon.com/apps/authorize/consent?application_id=xxx&state=xxx\"\n}\n```\n\n**后续操作**:\n用户在浏览器中打开 `authorizeUrl`，在亚马逊页面完成授权后，会自动重定向到回调地址。\n\n---\n\n## 2. 授权回调处理（服务端内部）\n\n### 接口信息\n\n- **路径**: 服务端内部回调接口（不对客户端/Agent暴露）\n- **方法**: POST (RouteMapping)\n- **鉴权**: 不需要（auth=false）\n- **实现**: `SpApiController.java:111`\n\n### 请求参数 (SpApiAuthorizeCallbackReq)\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| userId | String | ✅ 是 | 用户ID（从 state 中解析） |\n| sellingPartnerId | String | ✅ 是 | 亚马逊卖家ID |\n| accessToken | String | ✅ 是 | 访问令牌 |\n| refreshToken | String | ✅ 是 | 刷新令牌 |\n| tokenType | String | ❌ 否 | 令牌类型（默认 bearer） |\n| expiresIn | String | ❌ 否 | 过期时间（秒） |\n| region | String | ✅ 是 | 区域代码 |\n| sellerName | String | ❌ 否 | 卖家名称 |\n| mwsAuthToken | String | ❌ 否 | MWS 授权令牌 |\n\n### 返回结果 (SpApiAuthorizeCallbackVo)\n\n```json\n{\n \"saved\": true,\n \"authRecordId\": 123,\n \"bindUserId\": 456,\n \"message\": \"已新增授权\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| saved | Boolean | 是否保存成功 |\n| authRecordId | Long | 授权记录ID（sp_api_amazon_auth 表） |\n| bindUserId | Long | 绑定记录ID（sp_api_bind_user 表） |\n| message | String | 处理结果消息 |\n\n### 业务逻辑\n\n1. 检查是否已存在同一店铺的授权（sellingPartnerId + region）\n2. 如果存在，更新原有授权记录；否则新增\n3. 创建或更新用户与授权的绑定关系\n4. 返回保存结果\n\n### 注意事项\n\n- 此接口无需鉴权，因为是亚马逊重定向回调\n- userId 从 state 参数中解析，必须在获取授权URL时正确设置\n- 同一店铺的授权会更新而非重复创建\n\n---\n\n## 3. 查看已授权店铺列表\n\n### 接口信息\n\n- **路径**: `/spApi/authorizedStores`\n- **方法**: POST (RouteMapping)\n- **鉴权**: 需要（从 Token 中获取 userId）\n- **实现**: `SpApiController.java:126`\n\n### 请求参数\n\n无（从 Token 中自动获取当前用户 userId）\n\n### 返回结果 (SpApiAuthorizedStoresVo)\n\n```json\n{\n \"stores\": [\n {\n \"sellerName\": \"My Store\",\n \"sellerId\": \"A1234567890\",\n \"region\": \"NA\"\n },\n {\n \"selle"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1199,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T21:54:15.511Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T21:54:15.511Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-13T03:10:44.105Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}