linkfox-amazon-store-fulfillment-outbound

Amazon 店铺 Fulfillment Outbound

将此 Skill 用于 Fulfillment Outbound v2026-07-04 上的 Amazon Multi-Channel Fulfillment 工作流。它提供 Amazon 当前 Outbound 模型中的全部 9 个操作，以及 Invoices v2026-06-25 概览页关联的 getInvoiceHeaders 操作，同时保持现有的生产环境 linkfox-amazon-store-fba 和 linkfox-amazon-store-external-fulfillment 实现不变。

前置条件

1. 必须依赖 linkfox-amazon-store-auth。运行 python scripts/check_auth_dependency.py；退出码 42 表示必须先安装或加载该依赖。
2. 选择一个已授权的店铺，并获取其 sellerId 和 region。仅接受 NA、EU 或 FE。
3. 切勿接受或转发 amzAccessToken、accessToken 或 refreshToken；服务端会根据 sellerId + region 解析授权。
4. 在执行创建、更新或取消操作之前，请阅读 references/api.md 了解操作约定，并阅读 references/workflows.md。
5. 在获得用户明确确认后，向 createOrder、updateOrder、cancelOrder、updateOrderStatus 或 updatePackage 传入布尔值 confirmWrite: true；否则包装器会拒绝写入操作。
6. 如果 Amazon 分配了多租户服务标识，则仅将其作为顶层参数 fulfillmentServiceId 传入（1–40 个字符）。代理会将其映射到 x-amzn-fulfillment-service-id；切勿将原始请求头名称放入查询或请求体中。

调用方式

• API 端点：POST /spApi/developerProxy（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/<operation_script>.py '<JSON 参数>' [--inline] [--no-cache]
• 调用约束：本工具沿用 Amazon Store Skill 的统一免费配置；同一会话、同一参数组合默认只调用一次，脚本带有 24h 本地缓存。失败或结果为空时，不得自动更换参数、翻页或连续试探；需要继续调用时，须先征得用户同意。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-fulfillment-outbound-<timestamp>.json（<session> 取自 SESSION_ID；禁止写入 /tmp，当前目录不可写时则报错）
• 响应体 ≤ 8 KB：写入文件后，将完整 JSON 打印到 stdout
• 响应体 > 8 KB：写入文件后，stdout 仅输出摘要（顶层字段、常见计数、最大列表字段长度及前 3 条样本）
• 添加 --inline 可强制将全部内容打印到 stdout（同样写入文件）
• 添加 --no-cache 可强制本次读取/预览操作访问网关；仅在用户要求刷新或已确认外部状态发生变化时使用

读取数据建议：先查看摘要；需要具体字段时，使用 jq 或 ConvertFrom-Json 从保存的文件中按需提取。

操作指南

阶段	操作	脚本	可用性
报价	getOffers	get_offers.py	生产环境
预览	getOrderPreview	get_order_preview.py	生产环境
创建	createOrder	create_order.py	生产环境
读取	getOrder	get_order.py	生产环境
列表	listOrders	list_orders.py	生产环境
解除保留 / 更新	updateOrder	update_order.py	生产环境
取消	cancelOrder	cancel_order.py	生产环境
模拟订单状态	updateOrderStatus	update_order_status.py	仅限 Amazon 动态沙盒
模拟包裹状态	updatePackage	update_package.py	仅限 Amazon 动态沙盒
列出发票抬头	getInvoiceHeaders	get_invoice_headers.py	生产环境，Invoices v2026-06-25

工作流规则

1. 对于多 SKU 的配送选项和过期时间，使用 getOffers；对于计划配送、费用、限制和可履行性，使用 getOrderPreview。
2. 在调用 createOrder 前，展示所选商店、目的地、订单项、服务等级、费用、暂存/发货操作和 orderId。
3. 将 orderId 和每个 lineItemId 视为由卖家控制的幂等标识符。发生超时且结果不确定时，绝不要编造替代 ID。
4. createOrder 的响应可以是 HTTP 200 或 202。响应为 202 时，使用返回或请求中的 orderId 调用 getOrder；不要自动轮询。
5. 仅使用 updateOrder 更新受支持的履行配置，目前仅支持 HOLD/SHIP 操作。释放暂存订单前须确认。
6. 调用 cancelOrder 前须确认。只有在仍可取消时，Amazon 才会停止履行；不要将 202 描述为已完成取消。
7. 需要包裹和跟踪详情时，在 getOrder 或 listOrders 中添加 shipments: "INCLUDE"。
8. 遇到 429、500、503 或超时时，绝不要自动重放 POST/PUT 请求。尽可能使用 getOrder 恢复状态。
9. 仅使用 getInvoiceHeaders 查询发票标头。必须提供 marketplaceId；必须同时提供或同时省略两个开具日期边界；日期范围不得超过 90 天；仅在用户批准后使用 nextToken 翻页。

重要限制

• Amazon 将 updateOrderStatus 和 updatePackage 标记为 x-amzn-api-sandbox-only: true。与现有 FBA 技能一致，这些封装器对所有操作都使用相同的 /spApi/developerProxy 请求格式，且不接受或发送单独的 sandbox 控制字段。仅将它们用于沙盒测试数据；是否可用取决于统一网关/上游路由。
• 可选的 x-amzn-fulfillment-service-id 多租户标头仅通过类型化的顶层 fulfillmentServiceId 参数提供。原始标头名称、嵌套别名、空白值、超过 40 个字符的值以及换行符，都会在调用网关前被拒绝。
• Amazon 的 Outbound 概览角色列表中提到了 getInvoiceHeaders，但其 Reference 路径为 /finances/invoices/2026-06-25/invoices。此 Skill 将其作为明确标注的相关 Invoices 操作提供；它不计入九个 Outbound OpenAPI 操作，也不接受 fulfillmentServiceId。
• 旧版 v2020-07-01 的退货、功能和包裹跟踪操作仍保留在生产环境的 FBA Skill 中，不会复制到此当前版本的 Skill。迁移时请阅读 references/migration.md。

展示规则

• 展示 Amazon 数据和标识符时，不要暴露内部工具名称或访问令牌。
• 区分操作成功与业务完成：展示网关 errcode、Amazon httpStatus、订单 status、限制和后续操作。
• 对于报价和预览，将过期时间、服务等级、配送时间范围、币种、价格和商品限制一并展示。
• 对于订单，仅在存在时展示 orderId、状态、订单项、货件、包裹、跟踪信息、送达证明、投递点/储物柜详情、单件标识符和分页令牌。

用户表达

询问：“查询这些 Amazon SKU 配送到此邮政编码的 MCF 配送选项。”

操作：使用 getOffers；不要创建订单。

询问：“预览并创建此 MCF 订单。”

操作：运行 getOrderPreview，展示限制和费用，获得确认后再运行一次 createOrder。

询问：“跟踪我的 MCF 订单。”

操作：使用 shipments: "INCLUDE" 运行 getOrder；不要调用旧版跟踪操作。

反馈

报告问题时，请提供 skillName: linkfox-amazon-store-fulfillment-outbound、操作、已屏蔽的 ID、解析后的路径、网关状态和 Amazon 响应摘要。绝不要包含凭据。

Amazon SP-API 接口保护与重试指引

同一店铺连续收到 Amazon SP-API 的 400、403、404 或 429 时，网关会返回 450、453、454 或 459 并短暂冷却。这些自定义状态码不是 Amazon 原生状态，也不表示封号；目的是避免持续异常或高频调用扩大店铺风险。

状态与 message	范围	触发与冷却	处理
450：400，请求异常，请优化您的参数	店铺+接口	60 秒内超过 3 次：5 分钟；10 分钟内超过 4 次：20 分钟	停止原参数重试，检查必填字段、marketplace、ID、日期和请求体
453：403，店铺未授权，请先授权	店铺全部接口	60 秒内超过 2 次：5 分钟；10 分钟内超过 4 次：30 分钟	停止该店铺调用，检查授权、权限、店铺归属和区域
454：404，资源不存在，请优化您的参数	店铺+接口	60 秒内超过 3 次：5 分钟；10 分钟内超过 4 次：30 分钟	确认资源 ID、所属店铺/站点、资源状态和接口路径
459：429限流中，请降低频率	店铺+接口	首次：15 秒；2 分钟内超过 2 次：30 秒；3 分钟内超过 4 次：2 分钟	降低并发、分页和轮询频率并逐级退避

• 立即停止自动或并发重试，不得通过换脚本或重复创建任务绕过保护；优先遵循 retryAfter、blockedUntil，没有时按表中时长说明。
• 450/453/454 必须先修正参数、授权或资源标识，冷却后最多谨慎重试一次；再次触发则停止调用。453 期间停止该店铺全部 SP-API。
• 保留已有 reportId、feedId 等任务 ID；写操作结果不确定时先查询状态，不直接重放。
• 向用户先说明店铺保护，再给原因、处理和等待时间。可回复：“为保护您的亚马逊店铺安全，检测到 Amazon SP-API 连续返回{原因}，当前已进入短暂保护。请先{处理动作}，预计{等待时间}后再试；这不代表封号，也不是套餐或算力限制。”不要只说“LinkFox 限流”或“服务器繁忙”。

算力消耗规则

不消耗算力（以网关实际计费为准）。

---

更多跨境 Skill：LinkFox Skills