Amazon Seller Central — SP-API

每个 Amazon SP-API 操作均需运行打包的脚本 scripts/amazon_api.py。该脚本在内部完整处理 LWA 刷新令牌获取 + AWS SigV4 签名流程，因此 Agent 始终仅需处理结构化 JSON 数据。

python3 "{baseDir}/scripts/amazon_api.py"  [options]

背景说明：Amazon 的 Selling Partner API（SP-API）是 MWS 的替代方案。身份验证需两层凭证：用于生成 x-amz-access-token 的 LWA 刷新令牌，以及用于 SigV4 请求签名的 IAM 凭据。每次调用均需同时提供二者。访问令牌支持自动刷新，但 Agent 不负责此操作。

首次运行 — 安装唯一的 Python 依赖项

该脚本依赖 httpx。若命令执行失败并提示 ModuleNotFoundError: No module named 'httpx'，请执行一次安装：

python3 -c "import httpx" || python3 -m pip install httpx

配置

设置五个必需的环境变量。推荐将其置于 shell 的 rc 文件中，或使用密钥管理工具（如 1Password CLI、direnv、systemd EnvFile 等）。切勿将密钥直接粘贴至聊天窗口。

export AMAZON_SP_API_REFRESH_TOKEN="Atzr|…"          # LWA 刷新令牌
export AMAZON_SP_API_CLIENT_ID="amzn1.application-oa2-client.…"
export AMAZON_SP_API_CLIENT_SECRET="…"
export AMAZON_SP_API_AWS_ACCESS_KEY_ID="AKIA…"       # 具备 SP-API 角色权限的 IAM 用户
export AMAZON_SP_API_AWS_SECRET_ACCESS_KEY="…"

两个可选配置项（已设合理默认值 —— 英国站点、欧洲区域）：

export AMAZON_SP_API_MARKETPLACE_ID="A1F83G8C2ARO7P"  # 默认：英国站点
export AWS_REGION="eu-west-1"                          # 默认：欧洲区域终端节点

脚本所用的区域 → 终端节点映射关系如下：

站点 ID 列表详见：https://developer-docs.amazon.com/sp-api/docs/marketplace-ids。

工作流规范

1. 所有列表类命令均须以 --summary 开始。 SP-API 响应数据量大且全文阅读效率低 —— 仅当已通过筛选明确目标 ID 后，才可省略 --summary 参数。
2. 尽可能在 API 层完成过滤。 所有列表命令均支持与 Seller Central 相同的过滤参数（--status、--since、--type、--skus）。应将过滤条件下推至 API 层，避免拉取全部结果后分页处理。
3. 报表请求为异步操作。 reports/create-report/get-report/get-report-document 构成四步标准流程。针对补货场景，请使用 restock-report 快捷命令 —— 它在一个调用中完成创建 → 每 10 秒轮询 → 下载全流程。
4. 令牌缓存仅限进程内有效。 每次脚本执行会刷新一次 LWA 令牌，并在内存中缓存约 1 小时；但不会持久化到磁盘 —— 进程退出后，文件系统中不保留任何密钥信息。

命令列表

订单

python3 "{baseDir}/scripts/amazon_api.py" orders --summary
python3 "{baseDir}/scripts/amazon_api.py" orders --status Unshipped --summary
python3 "{baseDir}/scripts/amazon_api.py" orders --since 2026-01-01 --summary
python3 "{baseDir}/scripts/amazon_api.py" orders --status Shipped --since 2026-01-01 --limit 50

python3 "{baseDir}/scripts/amazon_api.py" order 
python3 "{baseDir}/scripts/amazon_api.py" order-items  --summary

订单状态取值包括：Unshipped、PartiallyShipped、Shipped、Canceled、Pending 等。

商品目录

python3 "{baseDir}/scripts/amazon_api.py" catalog-item 

FBA 库存

python3 "{baseDir}/scripts/amazon_api.py" inventory --summary
python3 "{baseDir}/scripts/amazon_api.py" inventory --skus "SKU1,SKU2" --summary

报表

# 列出已有报表任务
python3 "{baseDir}/scripts/amazon_api.py" reports --summary
python3 "{baseDir}/scripts/amazon_api.py" reports --type GET_FLAT_FILE_OPEN_LISTINGS_DATA --summary

# 启动新报表任务
python3 "{baseDir}/scripts/amazon_api.py" create-report --type GET_FLAT_FILE_OPEN_LISTINGS_DATA
python3 "{baseDir}/scripts/amazon_api.py" create-report 
    --type GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL --start 2026-01-01 --end 2026-01-31

# 轮询直至状态变为 DONE
python3 "{baseDir}/scripts/amazon_api.py" get-report 

# 下载并解析报表文档（TSV → JSON）
python3 "{baseDir}/scripts/amazon_api.py" get-report-document 
python3 "{baseDir}/scripts/amazon_api.py" get-report-document  --output report.tsv

补货库存报表（单次执行）

# 创建报表、轮询等待完成、下载 —— 全部一步完成
python3 "{baseDir}/scripts/amazon_api.py" restock-report
python3 "{baseDir}/scripts/amazon_api.py" restock-report --output restock.tsv

输出字段包括：商品名称、SKU、ASIN、FNSKU、最近 30 天销量、已售数量、当前可售数量、在途数量、总库存数量、可售天数、建议补货数量、建议发货日期、告警状态。请直接使用该命令，无需自行实现 create/poll/download 循环逻辑。

财务

python3 "{baseDir}/scripts/amazon_api.py" finances --since 2026-01-01
python3 "{baseDir}/scripts/amazon_api.py" finances --order-id 
python3 "{baseDir}/scripts/amazon_api.py" finances --since 2026-01-01 --limit 50

常用报表类型

完整报表类型列表见：https://developer-docs.amazon.com/sp-api/docs/report-type-values。

输出结构

每个列表类命令均输出如下格式：

{ "count": N, "": [ … ] }

其中 与命令名一致（如 orders、items、inventory、reports）。单条记录查询命令则直接输出资源对象本身。错误响应统一返回 { "error": "...", "detail": "..." } 格式，并以非零退出码表示失败。

实用模式

• 日常运营健康检查。 使用 orders --status Unshipped --summary 查看待处理订单队列，再执行 inventory --summary 评估库存水位，最后运行 finances --since 检查结算变动。
• 补货计划制定。 执行 restock-report --output restock.tsv —— 单一命令即可返回解析后的行数据，Agent 可直接用于电子表格聚合或图表渲染。
• 单笔订单资金流对账。 依次执行 order 、order-items 和 finances --order-id ，即可获知该订单的商品明细、发货情况及 Amazon 实际结算金额。

注意事项

• 速率限制 按终端节点独立设定且较为严格。脚本在收到 HTTP 429 响应时，会依据服务器返回的 Retry-After 头进行重试。
• 区域漂移问题。 若设置的 AWS_REGION 值未在上表中列出，脚本将自动回退至 EU 终端节点。如需显式指定，请从三个已知区域（us-east-1、eu-west-1、us-west-2）中选择其一。
• 报表最终一致性。 对于大时间范围的报表，即使状态显示为 DONE，实际数据就绪仍可能延迟数分钟。restock-report 最多轮询 10 分钟（共 60 次 × 10 秒）；超时后请改用 create-report + get-report/get-report-document 组合，并按自身节奏轮询。
• 终端节点文档： https://developer-docs.amazon.com/sp-api/。

在本技能中执行 SP-API 相关操作时，必须始终调用 scripts/amazon_api.py —— 不得手动构造 SigV4 或 LWA 请求；所有列表命令均须以 --summary 启动；错误信息须原样透出，不可猜测性处理 —— 此即本技能的正确使用方式。