External Fulfilment Shipping API 返回空货件,如何排查?
即使接口返回 HTTP 200、角色也已获批,仍不能确认货件数据已对应用开放。空货件集合也不能直接说明 allowlisting 尚未完成。应先检查是否已查完所有分页,再请 Amazon 确认商家、应用和履约地点的接入状态。现有信息不足以判定根因,也无法确认未加入白名单是否一定会返回空集合。
为什么有 Easy Ship 订单,接口仍可能返回空结果?
需要分别确认请求权限、查询范围和数据可见性。当前官方教程列出的前提包括卖家授权、开发者资料中的 Direct-to-Consumer Shipping (Restricted) 角色获批,以及在应用注册页面选择该角色。仅确认角色审批通过,不能覆盖全部接入条件。官方货件查询教程
问题中引用的文档还提到了商家 allowlisting。应请支持团队核实这一要求是否适用于当前账户和站点,以及是否已经完成。账户中有 Easy Ship 订单,也不能证明这些订单已形成当前授权及查询范围内可见的 External Fulfilment 货件。
官方 getShipments 参考还说明,该操作可能返回空页。如果响应中仍有 nextToken,就需要继续翻页,不能因为当前页为空就结束查询。getShipments API 参考
已经测试过状态和筛选条件,还应该检查什么?
既然已经测试过所有状态和可选筛选条件,下一步可以保留一组可复现请求,核对以下内容:
- 检查分页是否完整:如果响应的
pagination.nextToken非空,将其作为下一次请求的paginationToken,保持其他查询参数一致,直到没有下一页。 - 确认授权账户:检查请求使用的卖家授权是否对应存在 Easy Ship 订单的账户,并核对实际调用的是否为目标区域的生产 endpoint。
- 确认履约地点:如果使用
locationId,请接入团队确认它与目标站点和履约地点的对应关系。SmartConnect 指南说明,该标识由 External Fulfillment 团队在 onboarding 时提供,不宜自行猜测。SmartConnect 货件指南 - 检查时间条件:
lastUpdatedAfter和lastUpdatedBefore筛选的是货件最后更新时间,不是订单创建时间。应确认所选时间范围覆盖货件更新时间。getShipments API 参考
在现有已认证的 Postman 配置中,可以保留以下最小查询作为对照。这里只展示路径和参数:
GET /externalFulfillment/2024-09-11/shipments?status=ACCEPTED
当前官方教程要求使用 ACCEPTED 查询新货件,并说明自 2026 年 6 月 30 日起,MFN 货件的初始状态由 CREATED 改为 ACCEPTED。这一变化值得核对,但你们已经测试过所有状态,因此不能仅凭它解释故障。官方状态说明
是否需要额外的后台开通?
后台开通状态需要支持团队核实,目前还不能认定它是根因。建议在现有工单中要求明确回答:
- 当前商家是否需要 allowlisting,实际状态是什么?
- 当前应用是否已关联到该商家的 External Fulfilment 接入配置?
- 目标 marketplace 和履约地点是否已经启用相应的 Easy Ship 数据访问?
- 提供的一笔样例订单是否已进入 External Fulfilment 系统?若已进入,对应的
shipmentId、locationId和状态是什么?
如果支持团队能提供一个确认存在且应当可见的 shipmentId,可以调用单件查询作对照:
GET /externalFulfillment/2024-09-11/shipments/{shipmentId}
这里必须使用 External Fulfilment 的 shipmentId,不能直接用 Amazon 订单号替代。单件查询是官方提供的排查入口,结果仍需结合账户配置判断。官方查询教程
等待超过两周后,如何推动处理?
核对到的官方资料没有给出可据此承诺的 SmartConnect onboarding 或 allowlisting 完成时限,因此无法判断两周是否属于正常处理周期,也不宜给出固定等待天数。
可以在原 Amazon Developer Support 工单中补充 SmartConnect 的联系记录,请求协调负责 External Fulfilment 接入的团队,并要求确认接入是否完成、还缺哪一步、由谁处理。如已有 Amazon 业务或接入联系人,也可请其协助核实。
建议一次性提供应用 ID、卖家 ID、marketplace、区域 endpoint、实际查询参数、UTC 请求时间、完整响应以及可获取的请求标识,并附上一笔确实存在的 Easy Ship 样例订单。不要附带 access token、refresh token 或其他凭据。
空货件集合是否就是未开通白名单的预期表现?
目前不能这样下结论。官方参考确认查询可能出现空页,但没有将空货件集合定义为 allowlisting 状态信号。应先确认所有分页均为空,再请 Amazon 针对一笔样例订单核实数据是否进入系统、是否对当前应用可见。有了这些后台信息,才能区分接入配置问题与查询范围问题。
备注:内容仅供参考。
