从MWS到SP-API：亚马逊卖家接口迁移实战指南

如果你负责的电商系统里还挂着 Amazon MWS 的订单、库存、报表接口，那最近两年官方关于强制迁移到 Selling Partner API 的提醒，应该已经收到过不少轮了。最初大家普遍觉得这只是换换域名、换换SDK的小工程，直到真正动手才发现，认证机制从底层变了，业务代码的对接方式、数据权限、限流策略全部绕不开一波重构。

这篇不是官方文档的复读，而是我把一个从 MWS 迁移到 SP-API 的完整项目走完后，沉淀下来的关键路径、踩坑点和灰度方案。适合正在准备迁移的卖家技术团队，也适合接外包项目的伙伴。无论你只用了订单、报表、库存里的一两个接口，还是整条FBA链路都挂在上面，这篇文章都应该能帮你少走不少弯路。

1. MWS到SP-API，先搞清楚"换的到底是什么"

1.1 认证链路从"一劳永逸"变成了"三层联动"

MWS时代，开发者的接入方式很简单：你有一组 AWS AccessKey 和 SecretKey，再配上卖家的 MWS Auth Token，基本就能直接调接口。整个认证模型偏静态，只要密钥不泄露，写好的代码可以一直跑下去。

SP-API 改变了这个模式。现在调用一个业务接口，至少需要三条凭证链路协同工作：

• LWA（Login With Amazon）应用提供 Client ID 和 Client Secret，用它换取 access_token，这个 token 是SP-API请求中的 x-amz-access-token，有效期比较短，一般在1小时左右，过期后要刷新。
• 你的 AWS IAM Role 负责扮演一个跨账户角色，通过 STS AssumeRole 获取临时安全凭证，这些临时凭证用来做请求签名。
• 卖家在 Seller Central 后台对你的应用完成授权，会生成一个 refresh_token。第三方开发者的代码里必须拿着这个 refresh_token 才能帮卖家换到合法的 access_token。

这还不是最坑的。签名也变了，SP-API 必须对每个请求做 AWS Signature V4 签名，签名的 Service 名是 execute-api，而不是普通 AWS 服务常用的那几个。也就是说，访问任何一个 SP-API 接口，你都得同时维护 LWA 令牌、IAM 临时凭证、卖家 refresh_token 三条线的生命周期。

很多团队迁移时第一轮代码跑不通，问题都出在这儿：以为把 MWS 的请求地址改一下、密钥换一下就行，结果拿到的一直是 401 或 403。

1.2 先盘点你的接口账单再动手

迁移最容易犯的错是"一上来就改代码"。我建议先把整个业务链路中所有 MWS 调用点列成一张清单，搞清楚几个问题：

• 调了哪些 API？订单、报表、库存、物流、支付，全部列出来。
• 这些 API 是周期任务、实时查询，还是 Webhook/通知触发？
• 每个接口的调用频率大概多少？有没有深夜批量任务？
• 有没有用 MWS 的 _GET_... 报表类型，这些报表在 SP-API 中是否还存在？
• 是否存在多个站点账号共用一个 MWS 凭据，迁移后这些账号的授权方式是否会有变化？

做完这张清单，你才会发现真实成本。比如我们这个项目里，核心是订单同步、FBA库存更新、报表拉取和发货API，看似不过五六个接口，但散落在支付、ERP、仓储、客服等六个子系统中，而且每个子系统都有自己的密钥管理方式。整合清单之后才能确定统一接入层怎么做，而不是每个模块各拉一套 SP-API 配置。

2. SP-API认证四步走：注册、角色、令牌、签名

2.1 开发者账号与LWA应用的注册流程

第一步是注册开发者账号。自研系统直接在 Amazon Developer Portal 创建一个开发者资料，第三方服务商则可以走合作伙伴网络，两种模式在页面上有差异，但技术链路是一致的。

接下来要创建一个 LWA 应用。这个应用相当于你在亚马逊身份体系里的"门禁卡"。创建之后会得到三个关键信息：

• Client ID
• Client Secret
• 应用 ID（App ID）

其中 App ID 是给卖家在后台做授权时填写的。卖家进入 Seller Central 后，把 App ID 粘贴到"开发应用"区域，授权成功后，系统会生成一个 refresh_token。这个 token 本质上代表"某个卖家允许你这个应用访问他的店铺数据"，所以它是跟着卖家走的，不是跟着你的 AWS 账号走的。

我们团队早期在这块比较头疼，因为之前用 MWS 时根本没有"每个卖家单独授权"的概念。现在如果你服务几十个卖家，就得想办法管理对应卖家下的 refresh_token。我的建议是放到专用的令牌管理服务里，字段至少包含：卖家ID、市场站点、refresh_token、到期时间、授权状态、最近刷新时间。白名单、加密、审计一个都不能少。

2.2 IAM角色和STS临时凭证：比MWS复杂在哪

SP-API 要求用 AWS IAM Role 而不是 IAM User 的长期密钥来跑业务。官方文档里的推荐做法是：你创建一个 IAM Role，然后通过 STS 的 AssumeRole 获取临时凭证。

这个角色有一个关键配置：信任策略。很多人在创建角色时会忽略 Trust Relationships 设置，导致调用 STS 时始终报 AccessDenied。信任策略里至少要让 sts.amazonaws.com 服务主体可以 AssumeRole，同时如果你有多个账号，还要把账号关系理清楚。不然本地生成临时凭证没问题，放到生产环境跑一阵子又开始报错，排查起来非常浪费时间。

得到临时凭证后，所有的 SP-API 请求都必须用这组临时凭证做 SigV4 签名。临时凭证默认有效期最短为900秒，最长可以到12小时，我们在生产环境设置了1小时，和 LWA access_token 的生命周期保持一致，方便统一刷新。

2.3 签名细节决定成败：region、service、payload哈希

SP-API 的签名要求是 AWS Signature V4，但有两个非常容易忽略的地方：

第一，Service 名称必须是 execute-api。如果你按常态写成 amazon 或 apigateway，签名校验一定失败。这个细节让我排查了不少时间，说多了都是泪。

第二，region 的选取要根据 endpoint 来。北美 endpoint 用 us-east-1，欧洲用 eu-west-1，远东用 us-west-2 之类。但实际上，很多时候官方的例子都统一用 us-east-1，因为它主要影响签名拼接，最终请求还是打到对应的 host 上。建议每个环境都写死在配置里，不要随意切换。

下面是一个用 Python 获取 LWA token 的典型例子：

python复制import requests

token_url = "https://api.amazon.com/auth/o2/token"
payload = {
    "grant_type": "refresh_token",
    "refresh_token": "Atzr|xxx",
    "client_id": "amzn1.application-oa2-client.xxx",
    "client_secret": "xxx"
}
resp = requests.post(token_url, data=payload)
data = resp.json()
access_token = data["access_token"]

获取 STS 临时凭证可以用 boto3：

python复制import boto3

sts = boto3.client("sts", region_name="us-east-1")
response = sts.assume_role(
    RoleArn="arn:aws:iam::123456789012:role/SP-API-Role",
    RoleSessionName="spapi-session"
)
creds = response["Credentials"]

拿到 access_token 之后，请求 SP-API 接口时把 token 放进 x-amz-access-token header，再用 STS 临时凭证对请求做 SigV4 签名，最终带上完整签名头发出请求。签名这块建议直接用官方提供或社区验证过的 SDK，而不是手写。手写 AWS4 签名不是不行，但很容易在 header 大小写、时间戳格式、URI 编码顺序这些细节点上出错。

3. 业务接口迁移对照：订单、报表、FBA库存的真实差异

3.1 Orders API：结构和限制都有微调

订单接口是绝大多数系统的核心依赖。MWS 里的 ListOrders、ListOrderItems 在 SP-API 中仍然存在，路径基本延续了类似 /orders/v0/orders 的风格，第一眼看上去很亲切，但实际使用中要小心几个点。

首先，SP-API 的 Orders API 对日期范围的限制更严格。MWS 时代很多开发者习惯了用大跨度日期去拉全量数据，在 SP-API 中，过大的时间跨度会直接被参数校验拦下来，返回 400。这逼着你把订单同步拆成更细的小任务，而不是一次性全量拉取。

其次，分页行为也需要重新适配。我们在迁移初期遇到过一个诡异的场景：同步任务跑了一半突然停止，没有任何异常日志。后来排查发现是 NextToken 的解析和拼接方式在 SP-API 中发生了变化，某些 SDK 会忽略查询参数中的 NextToken，导致循环只执行了第一页。这类问题一旦出现，数据就会悄悄丢，不会立刻报错，最危险。

然后，订单项、发货信息、退款等接口名称虽然类似，但字段的可选性有变动。有些在 MWS 中默认返回的字段，SP-API 中需要显式声明参与信息，或者在授权范围里配置好。建议迁移时不要只测 200 返回，一定要把所有字段和 MWS 的返回逐项比对，特别是金额、税率、地址这些容易影响业务计算的字段。

3.2 Reports API：从requestReport到createReport

报表接口是重灾区。MWS 时代，拉一张报表的逻辑是 RequestReport 之后轮询 GetReportRequestList，等状态变为 Done 再拿报表 ID 调 GetReport。SP-API 把这条链路改成了 createReport、getReport、getReportDocument 三步，语义上更接近"创建报告-获取报告元数据-下载报告文档"。

迁移时最大的坑是报表类型名。很多 MWS 报表类型在 SP-API 中仍然保留，比如 _GET_FLAT_FILE_ORDERS_DATA_ 这类常见的订单报表，基本沿用。但少数报表类型被拆分或者改名了，尤其是部分 FBA 报表和税务报表。如果不核对官方最新文档，很容易照着旧文档写 createReport 时拿到 InvalidReportType 错误。

另外，SP-API 报表下载的方式也变了。不能用报表 ID 直接作为下载地址，而是要先用 getReportDocument 拿到一个带临时签名的下载地址，再对这个地址发起下载请求。这个地址是限时的，过期后需要重新获取。批量下载任务里，必须考虑"获取报表文档地址"和"实际下载"之间的延迟，不能拿着地址缓存太久。

我建议迁移报表模块时先做一个映射表，把线上所有用到的 MWS 报表类型和 SP-API 的最新报表类型做一一对应。这张表不光是给开发看，还要给运营确认：他们日常依赖的报表在迁移后字段是不是还和以前一样。否则系统虽然跑通了，但运营拿到的报表少了几列，日子一样没法过。

3.3 FBA库存和Inbound：版本兼容问题要提前确认

FBA 库存相关的 API 在 SP-API 中变动比较大，而且存在不同的版本。比如有些接口还在 v1，有些已经升级到了 v2，还有部分接口在 MWS 和 SP-API 之间的映射关系并不是一一对应。

我们团队在接 FBA 库存查询时踩的最大的坑，是以为库存接口名称在 SP-API 中能找到同名函数，结果不仅路径不同，连返回结构都打散了。以前一个接口返回的库存汇总信息，现在要拆成多个接口来组装，而且不同站点下可能有不同的字段状态，比如不可售数量、预留数量这些，在不同市场的口径存在差异。

做 Inbound 货件管理的团队要格外注意版本兼容。部分旧的 FBA 入库接口目前还有兼容层，但官方已经在推动 v2 模型。如果要接新功能，就不要在旧接口上继续投入了，直接按新版本设计数据模型和业务逻辑。否则刚迁完半年又得再迁一次，那种滋味不好受。

4. 迁移中的高频故障：429、401、403逐个定位

4.1 429限流：配额规则变化与重试策略

MWS 时代大家在回调里对 429 相对宽容，毕竟很多 MWS 接口的限流是按小时窗口计数的，只要不是突然上量，一般不容易触发。SP-API 的限流模型更细、更实时，不同接口有独立的配额，还提供了速率限制的响应头，比如剩余的配额数量、建议的重试时间等。

如果处理不好 429，最典型的表现就是生产环境定时任务偶尔失败，但手动重跑又能成功。这种间歇性问题最容易被忽略，积累久了就会造成数据延迟。

我们的处理方式是重新设计重试组件，不能拿旧的通用重试逻辑直接套。要做到三点：

• 读取限流响应头中的剩余配额，自行估算下一批请求是否要放慢速度。
• 针对 429 使用 Retry-After 或官方建议的退避时间，不要盲目重试。
• 对长跑型任务做"更小的批次"策略。比如以前一次性拉 500 条订单，现在改成每批 100 条，批与批之间加一点间隔。

限流参数最终必须做成可配置项，因为不同卖家账号、不同市场站点、不同 API 版本的配额会有差异。写死在代码里迟早要出事。

4.2 401和403：签名错乱与角色授权互相甩锅

401 和 403 是迁移过程中最常见的两类认证错误，但它们的根源完全不同，排查方式也完全不同。

401 通常是令牌或者签名有问题。常见的场景包括：x-amz-access-token 没有正确传进去、token 过期、签名头缺失、签名时间与服务器时间偏差过大。这个顺序基本就是排查顺序。我们最早遇到的是服务器时间不准，导致 SigV4 签名里的时间戳总是和亚马逊服务器的时间差太多，所有请求都返回 401。因为问题太隐蔽了，单独看代码每个环节都对，最后才发现是 NTP 同步没做好。

403 则大多和权限有关。SP-API 对每个卖家的授权粒度更细，一个刷新令牌能访问哪些 API、能读哪些 PII 字段，在授权时就固定了。如果代码没问题但调用始终 403，优先去 Seller Central 里检查应用权限。在自研系统中，还要注意 IAM Role 的权限策略是否允许调用对应的 API 动作。很多开发者在 AWS 控制台上创建角色时只给了普通权限，没有加到 SP-API 相关的策略，导致调用时报 403。

建议在全局异常处理里把 401 和 403 区分开，分别打日志，并挂上对应的告警。不然每次报错都要从调用链路的入口开始翻，效率太低。

4.3 PII字段：权限白名单不是申请完就完事

SP-API 对买家个人信息（PII）管控非常严格。订单接口里的买家姓名、地址、电话、邮箱等信息，在 MWS 时代只要你有授权基本能直接拿到，切到 SP-API 后则需要满足额外的资质审核要求，比如完成税务验证、公司信息核验、明确业务使用场景等，审核通过后才会开放相应字段。

这里有一个容易被低估的点：PII 权限不是"店铺级别"的，而是和具体应用、具体 API、具体用途绑定的。如果团队业务中有多个系统都需要买家手机号，但只有一个系统通过了审核，那其他系统依然拿不到数据。

另外一个坑是日志系统。以前开发的系统普遍喜欢把接口请求和响应原样打进日志，方便排查问题。SP-API 上线后，如果再这样记录 PII 数据，一旦出了安全事件就是大麻烦。我们在迁移时专门加了脱敏层，把买家信息在入参和出参日志里全部打码，数据库里存储时采用加密字段，读取时有独立的密钥管理。整个过程需要跟安全、法务同事一起评审，不要开发自己拍板。

5. 灰度切换方案：双跑对账、分阶段切换、回滚预案

5.1 按接口风险分级，先报表后订单再库存

我见过不少团队用"大爆炸"方式切 SP-API：某一天把线上所有 MWS 调用切换到新接口，切换当晚全组通宵。这种做法风险极高，因为 SP-API 表面上看和 MWS 很像，实际细节差异太多，两套体系对同一订单、同一报表的处理方式不可能完全一致。

我们的做法是把接口按风险分级，分阶段切换：

• 先切换只读类、影响面小的接口，比如报表下载、订单批量查询。
• 再切换订单实时查询和更新类接口。
• 最后迁移库存、物流等强流程性接口，这一块出了问题直接影响发货。

每个阶段之间至少要观察一个完整的业务周期，比如订单数据至少跑满三天的日报流程，确保跨日数据没有问题，再进入下一个批次。

5.2 双跑对账：数据一致性靠订单号和时间戳核对

双跑阶段不是简单地把 MWS 和 SP-API 的调用同时执行一遍就完事。你要设计一个对账机制，否则两边数据是否一致，你根本不知道。

我们在双跑阶段做了一个对账任务：每隔15分钟分别从 MWS 和 SP-API 拉最近订单列表，按订单号、订单状态、下单时间、金额四个维度做对比，不一致的订单进对账明细表，由人工确认原因。这样一旦 SP-API 返回的字段含义和 MWS 有出入，能在业务产生实际影响之前就发现问题。

对报表数据也一样。每天跑完日报后，把两份报表的关键汇总数字做对比，比如订单总数、销售额、退款数。如果差值超过千分之一，就自动告警。这种数字层面的校验，往往比字段逐个比更高效，能快速暴露"漏数据"或"多数据"的情况。

5.3 上线后的监控与回滚触发器

代码上线不等于迁移结束。SP-API 切换后的前几周，监控和告警需要比平时敏感得多。

我们设了三类告警：

• 接口层故障：5xx 比例超过 1% 或者连续失败超过 10 次。
• 数据一致性异常：对账任务发现超过 20 个订单不一致，或单笔关键金额对不上。
• 业务流程异常：同步任务超时时间明显增加，报表文件生成速度低于预期。

每类告警都要有一个明确的回滚触发器。比如数据一致性异常时，要能快速把业务流量切回 MWS。这里的前提是，代码里必须保留旧接口的实现，不要因为切换到新接口就把 MWS 代码删掉。我们保留了完整的 MWS 消费者和生产配置，只不过默认关闭，切换开关放在配置中心里，一个按钮就能全局切回。

我还建议准备一个"只读回滚"模式：切换后如果发现问题但不确定根因，可以先让系统对 SP-API 只读，不写不更新，业务照常用 MWS 写操作。这样既不会完全中断，又能对问题进行定位。这个模式在迁移早期非常实用。

6. 迁完SP-API之后，反而能拿到一些新能力

6.1 从轮询到推送：Notifications和SQS的玩法

如果只是把 MWS 接口原样平移，那么 SP-API 的优势只发挥了一小半。SP-API 提供了 Notifications API，可以把你关注的业务事件推送到你自己的 SQS 队列里，比如订单状态变化、货件状态变更、报表生成完成等。

这个能力的价值非常大。MWS 时代我们为了拿到最新订单，只能高频轮询 ListOrders，既占用配额又有时延。切到 SP-API 后，订单履约有变更时，亚马逊直接推送一个通知到 SQS，应用再根据通知内容去拉详情，配额消耗大幅下降，数据时效性反而更好。

当然，SQS 通知方式也是一套新的维护工作。要处理队列积压、消费失败重试、消息幂等。我们最初消费端就因为没有做消息幂等，收到一次推送结果把订单状态重复更新了好几次，后来在消费者里加了消息ID去重才解决。

6.2 更细的数据权限：批下来才能碰买家隐私

SP-API 的权限模型虽然麻烦，但也让整个系统的数据边界更清晰。以前 MWS 凭据一旦泄露，所有数据都可能被拖走。现在每个应用能访问哪些接口、哪些字段，都有单独的授权范围，安全审计时也说得清楚。

这一点在企业内部尤其重要。财务、客服、仓储各自接入 SP-API，应该用不同的 IAM Role 和应用，不要共用一个超级凭据。虽然初期配置成本高了点，但后续每次权限变更都能最小化影响面。我们后来把所有应用都划到了独立 AWS 账号里，通过企业 SSO 做统一登录，这步对合规和审计帮助很大。

6.3 给还没动工团队的三点建议

如果你们团队还处在"评估阶段"，我根据这次完整的迁移经历，给出三点非常实际的建议：

第一，不要等最后一刻。SP-API 的迁移周期不是按天算，而是按周甚至按月算的，因为涉及应用注册、授权审核、PII 权限申请、开发联调、灰度切换。越早启动，后面越从容。

第二，把迁移当作一次接口治理的机会。趁着迁移，把散落在各系统的 API 调用统一收敛到一个接入层，统一处理令牌、签名、限流、重试、日志，后续维护会省很多事。我们这次迁移顺带干掉了一堆重复代码，效果比预期的还好。

第三，新人加入时，直接按 SP-API 的标准培训，不要让他们再接触 MWS 的旧模式。否则团队的思维会长期停留在"迁移前的世界"里，后面维护和扩展都会吃力。

整个迁移过程确实没有想象中那么轻松，但它也不是一道过不去的坎。只要把认证链路理清、把业务接口差异摸透、把灰度对账做扎实，SP-API 反而能让系统在稳定性、安全性和扩展性上都往前走一大步。如果让我重来一次，我会更早启动盘点，把接口治理放到和功能开发同等重要的位置上。