亚马逊-店铺报表

核心用法

本 Skill 提供亚马逊 SP-API 报告的全流程自动化获取能力，覆盖库存、订单、销售流量、FBA、财务结算、Brand Analytics 等 95+ 种报告类型。执行路径为：请求报告 → 自动轮询状态 → 下载 → 解压 → 生成本地可访问链接，全程无需人工干预。

显著优点

• 端到端自动化：单次调用即可完成从请求到本地文件就绪的全过程，内置智能轮询（默认30秒间隔、20次重试，可配置）
• 报告类型全覆盖：支持 GET_MERCHANT_LISTINGS_ALL_DATA、GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL、GET_SALES_AND_TRAFFIC_REPORT、GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE 等几乎所有亚马逊官方报告
• 本地化友好：完成后默认启动本机短时 HTTP 服务（300秒），生成 extractedFileHttpUrl 供浏览器直接下载已解压文件，同时提供绝对路径和 file:// URI
• 灵活配置：支持自定义时间范围、轮询参数、多站点批量获取

潜在缺点与局限性

• 强依赖前置组件：必须预先安装 linkfox-amazon-store-auth 完成店铺授权与令牌管理，否则完全无法使用
• 单站速率限制：Reports API 限制约 0.0222 req/s（约45秒/次），高频请求需自行控制节奏
• 报告生成时效不定：部分财务报告需10-30分钟，需合理设置 maxAttempts
• 本机 HTTP 服务局限：extractedFileHttpUrl 仅限同一台机器访问，且限时有效，非持久化存储方案
• Token 时效：accessToken 1小时过期，虽脚本自动刷新，但极端长任务存在中断风险

适合人群

• 亚马逊运营人员：需定期获取库存、订单、销售数据做分析
• 电商数据分析师：需要结构化原始报告进行 BI 加工
• 财务对账人员：自动化获取结算报告、退款数据
• 品牌卖家：需拉取 Brand Analytics 搜索词报告进行关键词研究

常规风险

• 权限风险：403 错误通常因缺少 API 权限或未加入 Brand Registry
• 报告失败处理：FATAL 状态可能因店铺类型不支持或数据不足，需人工判断重试或换类型
• 成本消耗：每次调用消耗积分，失败/空结果不会自动重试或换关键词，需用户确认后再继续
• 数据安全：脚本会本地落盘完整响应，含敏感商业数据，需注意工作目录权限管理

核心用法

linkfox-amazon-store-report 是一款专为亚马逊卖家设计的报告自动化获取工具，实现从请求到解压的全流程无人值守。用户只需指定店铺ID、区域和报告类型，技能即可自动完成：令牌获取 → 报告请求 → 状态轮询 → 文件下载 → 自动解压 → 本地服务启动。支持95+种官方报告类型，包括库存报告（GET_MERCHANT_LISTINGS_ALL_DATA）、订单报告（GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL）、销售流量报告（GET_SALES_AND_TRAFFIC_REPORT）、财务结算报告（GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE）及Brand Analytics品牌分析等高级数据。

使用方式灵活多样：推荐通过 scripts/get_report.py 一键脚本完成端到端操作；高级用户也可通过 /spApi/developerProxy 端点手动控制报告生命周期。脚本执行后会生成 extractedFileHttpUrl 本地临时下载链接（默认保持300秒），方便浏览器直接获取已解压文件。

显著优点

全流程自动化：彻底告别亚马逊卖家后台手动请求、等待生成、逐一下载的繁琐流程，将原本耗时30分钟以上的操作压缩至数秒触发、自动完成。

报告类型全覆盖：支持95+种官方报告，从基础库存到高级Brand Analytics搜索词分析，满足运营、财务、选品等多场景数据需求。

智能依赖管理：内置 check_auth_dependency.py 主动检测依赖技能 linkfox-amazon-store-auth，未安装时引导用户优先处理，避免运行时崩溃。

安全设计周全：API令牌通过环境变量隔离，本地HTTP服务严格绑定127.0.0.1，敏感日志自动掩码处理，符合GDPR数据最小化原则。

跨平台兼容：支持Claude、Cursor、OpenClaw、Hermes Agent等多种Agent运行环境，自动探测技能加载路径。

潜在缺点与局限性

强依赖前置技能：必须预先安装并配置 linkfox-amazon-store-auth 完成店铺授权，否则无法执行任何报告操作。对于未授权的新用户，流程中断感明显。

本地服务暴露面：默认启动的本地HTTP服务虽仅绑定127.0.0.1，但仍属额外网络暴露点，多用户共享机器或容器环境存在潜在风险。

Rate Limit约束：Amazon Reports API限流约0.022 req/s，高频轮询可能触发限制；部分财务报告生成耗时10-30分钟，需调大maxAttempts参数耐心等待。

Region/站点限制：需准确指定region（NA/EU/FE）和marketplaceIds，新手易因站点配置错误导致报告为空或权限拒绝。

Subprocess调用风险：依赖检查通过subprocess.run执行外部脚本，虽路径受控，但仍属潜在攻击面。

适合的目标群体

• 跨境电商运营人员：需要定期获取库存、订单、销售数据做日常运营分析
• 财务对账专员：自动化拉取结算报告、FBA费用明细，提升对账效率
• 亚马逊品牌卖家：需要Brand Analytics、搜索词报告等高级数据进行选品和广告优化
• 电商数据分析师：将亚马逊原始数据接入BI系统或数据仓库，构建自动化数据管道
• 多店铺管理者：统一管理多个Seller ID的报告获取，减少重复登录操作

使用风险

性能与稳定性：报告生成依赖Amazon SP-API服务端状态，节假日或大促期间可能出现队列积压；建议业务高峰期预留充足轮询时间。

Token时效性：accessToken有效期1小时，超长耗时报告（如大范围历史订单）存在令牌过期风险，脚本内部已做自动刷新，但极端场景仍需关注。

成本消耗：每次报告请求消耗LinkFox积分，失败或空结果不会自动重试/换关键词，需用户确认后再发起新请求以避免意外扣费。

数据安全：下载的报告文件包含敏感经营数据，临时目录和本地HTTP服务文件需及时清理，避免长期驻留本地磁盘。

权限依赖：Brand Analytics、Vendor类报告需要额外的品牌备案或Vendor账号权限，普通Seller账号请求将返回403错误。