亚马逊SP-API对接实践解析（amazon selling partner api）

1.前言

亚马逊(amazon)在2020年10月推出了新的替代MWS的api方案，称为Selling Partner API(SP-API). SP-API在授权方式、权限管理、覆盖站点、支持的卖家模式、接口交互数据格式上都做了升级优化，当然目前这个SP-API还不够稳定，亚马逊也一直在改进和优化中。在不久之后，它将替代MWS发挥AGS的API的管理店铺等作用。在其github中的discussion中就有很多announcement发布MWS的api在某某截止日后不能使用，需要迁移到SP-API。比如第三方开发者使用到MWS Orders, Reports, and Merchant Fulfillment API的一定要在2022年7月31前将这些API切换到使用SP-API相关的API，具体看这里。

2.目录

接下来我主要从四个方面，讲下对接SP-API的流程及过程中需要注意的问题

1. MWS 与 SP-API

2. Developer及APP的申请

3. 接口的集成与使用

4. 注意事项

3.MWS 与 SP-API

大家在对接SP-API前，对MWS一定不陌生，MWS是Marketplace Web Service(商城网络服务)的简称。是亚马逊为给seller提供的API自动管理店铺的服务，利用此API可更加高效的运营店铺，减少手工运营时间，提高响应速度。当然第三方服务商（收款商和ERP等）也可以利用这个API为卖家提供更好更精准的服务。MWS从2003年推出到现在已经服务了18年，随着互联网技术的发展，根据数据的安全性及API的易用性等方面考虑，亚马逊在2020年10月推出了新的API方案叫Selling Partner API，简称SP-API。SP-API在很多方面都做了些改进：
1. SP-API 在授权方式上使用标准的OAuth2.0

SP-API现在使用典型的OAuth2.0方式做授权管理，比MWS的授权方案更安全易于管理。MWS的授权方式是简化版的OAuth2.0，只根据MwsAuthToken或者AccessKeyId和SecretKey的方式

MWS的方案是：如果是第三方服务商，那需要卖家授权获取到MwsAuthToken去请求API，如果是卖家自己请求API只需要提供下发的AccessKeyId和SecretKey请求即可。那么SP-API的方案是：不管是第三方服务商还是卖家，都需要用标准的OAuth2.0的方式去请求API，通过授权获得的refresh_token去换取1小时生命周期的access_token去请求API

2. SP-API 在接口数据格式上使用了JSON

SP-API使用RESTful的方式请求API，用JSON格式的做数据结构交互，MWS是采用xml等数据结构做交互.

3. SP-API 在权限管理上更明确更安全

SP-API在权限管理上，在申请develoepr及app的过程中都有权限的选择及管控，比MWS的权限管控更细化，分级

4. SP-API 支持一个app全球站点可授权对接

SP-API支持一个app可接受全球站点的授权，这相对于MWS来讲，是个很大的升级。MWS不支持所有全球站点的打通。假设一个卖家在全球站点开店，全球站点分为三个region分别为EU(欧洲)、FE(远东)、NA(北美)，MWS需要在三个region都分别申请一个developer才能做到全球站点API管理。那么现在SP-API只需要在任意一个region申请一个developer，然后在developer下申请一个app就可以做到三个区域的店铺都可授权管理。当然一个developer还可以申请多个app

5. SP-API 支持seller和vendor两种模式的卖家

我们知道亚马逊开店有三个模式分别是SC(Seller Central),VC(Vendor Central ).以前MWS只支持对SC做API管理，现在SP-API即支持SC也支持VC

6. SP-API 引入了AWS的IAM管理体系

SP-API引入了AWS的IAM管理体系做API鉴权（后面介绍怎么设置IAM）

请求API的Credentials等公用参数比较：

	MWS	SP-API
卖家自用	AccessKeyId (MWS developer) SecretKey (MWS developer) SellerID endpoint	AccessKeyId (AWS IAM user) SecretKey (AWS IAM user) region (AWS Region) roleArn (AWS IAM role) roleSessionName ClientId (LWA App) ClientSecret (LWA App) refreshToken lwaEndpoint (https://api.amazon.com/auth/o2/token) endpoint
第三方服务商	AccessKeyId (MWS developer) SecretKey (MWS developer) SellerID mwsAuthToken endpoint	AccessKeyId (AWS IAM user) SecretKey (AWS IAM user) region (AWS Region) roleArn (AWS IAM role) roleSessionName ClientId (LWA App) ClientSecret (LWA App) refreshToken lwaEndpoint (https://api.amazon.com/auth/o2/token) endpoint

从参数比较中可以看出:

MWS 的凭证信息只要申请MWS developer的时候的AccessKeyId和SecretKey。如果是第三方服务商，增加一个卖家给服务商授权时生成的MwsAuthToken.

而 SP-API完全不一样，包含两部分参数信息，一部分是AWS的 IAM体系里面的user和role的参数信息，还有一部分是LWA的申请的app的ClientId及ClientSecret信息。
不管是卖家还是第三方服务商都需要提供refresh_token(其实是access_token,因为SDK里把换access_token
的步骤包含进去了)。
卖家自用的是直接app列表里面点击按钮生成的refresh_token. 而第三方服务商的refresh_token是通过卖家授权给第三方服务商的OAuth2.0流程生成或者请求Authorization API做MWS平滑迁移到SP-API生成的。

4.Developer及APP的申请

第一步：申请注册卖家账户及AWS账户
亚马逊的开发者的申请，先要注册成为专业卖家，然后才能申请注册开发者，
在申请APP时需要AWS 的IAM ARN信息，所以需要注册一个AWS账户

第二步：Your Developer Profile填写开发者资料

1.DataAccess选项

My organization builds and offers publicly available applications

提供公共服务（他人授权给我）第三方服务商

My organization participates in Amazon services, and I want to integrate to manage my own business only

卖家自己使用（他人不授权给我）

注意：如果卖家自己使用请选择第二个，这样的情况下，在申请app的环节就不需要发布出去
如果是第三方服务商，那么需要选择第一个，这样的情况下，在申请app的环节需要发布出去，在app store中展示

2.Roles选项

SP-API公众号权限说明

里面有三项标记为Restricted的PII权限,需要使用tokens API获取专用restrictedDataToken访问相应的业务API接口.

由于各国的数据保护法律法规，PII权限涉及的都是隐私数据，包括卖家和买家的，所以亚马逊对这个权限审核要求不一样。需要提交额外的审查资料.如果刚才DataAccess选择的是第三方服务商，那么在roles里选择这三个PII权限将会受到比较严格的审查
如果刚才DataAccess选择的是卖家自用，那么roles里选择这三个PII权限也会需要提交额外的资料审查，不过本人猜测应该没有第三方服务商那么严格

所以作为卖家朋友来讲，PII权限中包含一些发货详细地址信息和发票信息，对卖家的运营是非常重要的，所以大部分需要这个权限。所以卖家在选择DataAccess时，最好选择卖家自用，这样审核通过的概率大些
关于PII的详细介绍可以看我另外一篇文章，这里

第三步：Add new app client 申请APP

1.edit app

1) API Type
两个选项SP API 和 SP API and MWS
当选择SP API and MWS时，这个app就是混合开发者，之前有申请过MWS的developer才有此选项，混合开发者是SP-API提供的平滑过渡的解决方案，也就是之前使用MwsAuthToken的MWS授权的方式基础上，不需要卖家重新授权，只需要请求Authorization API接口用MwsAuthToken换取SP-API的授权authorization code，然后获得的refresh_token.请求完这个接口后，卖家seller center的Manage your apps页面就会发现多了一个列


这里可以关联全球的developerId号，将之前MWS的开发者关联到此app上，都可以做平滑迁移和聚合
打个比方，一个第三方服务商的一个卖家账号在全球站点开店，然后在欧洲、远东、北美分别申请了三个MWS developer。这时候你就可以在这里将三个developerId都填入，使其与当前app建立好关系。然后当前app就可以平滑迁移获得授权给这些MWS开发者的店铺的SP-API授权。这样就免去了分别要在三个地区申请三个app对应之前三个MWS developer。所以这里的给混合开发者添加developerId对那些ERP或收款商等第三方服务商很有作用

2) IAM ARN
在AWS账号中申请的IAM role 或者IAM user，具体操作方法
（建议：一个AWS账号+一套IAM+一个店铺账号+一个app 保持唯一独立的环境）
3) Business entities supported
此app支持Sellers还是Vendors
4) Roles
在developer profile中选择的权限的基础上选择,权限解析
5) OAuth Login URI
授权发起链接，授权有两种流程方式：
1.从开发者这边组连接跳转到亚马逊发起
2.从亚马逊app stores选择开发者app或者enable的发起，此链接就是亚马逊方发起的链接
6) OAuth Redirect URI
授权同意后的回调链接。可以多个，如果在授权发起时不指定，那么默认取第一个，如果授权发起时参数中的redirectUrl不在这个列表中，用户授权的过程中会出现MD5100错误提示

三点注意：
1.如果是卖家自授权使用的话，到这步就ok了，下面edit listing这步不需要发布到app store。自授权只需要在app列表的Authorize选项就可以授权，且分别授权到你不同的开店站点获得refresh_token.获得的refresh_token拷贝出来，再进入这个页面就会没有了。这个refresh_token没有失效时间，下次重新生成后，历史值就会失效。

2. 如果是授权给第三方服务商，那这个refresh_token就是有一年有效期，需要在过期前renewed（目前没有API可以查询授权失效时间，MWS也没有，所以我们要记录到授权时间，在1年即将失效前，做到提前通知卖家去延期一年，防止业务中断）
3.这些信息最好一次提交正确，在提交前思考清楚。因为每次信息的变更都要等待审核发布完成，时间比较久。
我之前在申请app的时候由于项目刚确定，还没有定义好OAuth Login URI和OAuth Redirect URI链接，所以就随意提交了个然后做申请。等我确定好这两个链接再来修改时，又要重新审核发布，这中间耗费了一个月的时间，影响了些项目的进度。

2.edit listing

edit listing提交的内容都是发布到app stores的信息
总共分为三部分 App infor­mation 和 Pricing、App details都如实填写就行
两点我之前遇到的问题：
1.在第点击提交时，报错说spc3000，我这边时由于在 App infor­mation中的Support phone提交的不符合格式+86400068796、400-876-9066、045186013245、+86045186013245。正确的格式是+86 045186013245

2.避免App details用中文填写提交，因为中文填写会导致翻译速度缓慢，然后审核发布时间较长（这个目前大家应该知道，由于目前大量的app申请审核发布，SP-API的审核进度比较慢

5.接口集成与使用

1.selling-partner-api-docs
根据github的docs文档说明，所有的API接口都是RESTful的方式，可以使用swagger生成客户端请求的代码，再结合use-case里的一些代码就可以轻松调用API接口

references：
    所有API的说明文档

guides：
    developer-guide:  
         开发者总引导文档，从这篇文档开始深入理解整个SPAPI
    migration-guide：
         迁移的引导文档，给老的MWS需要平滑过渡到SPAPI对接的开发者使用的。
         对于第三方服务商，这个迁移的API就很有用，因为可以做到不用卖家参与就可以过渡到SPAPI授权上来。里面有个核心的API就是Authorization API，可以实现用MWS授权的MwsAuthToken去换取SPAPI的授权refresh_token
    Roles： 在申请developer和app中的权限对应的业务API的关系解释
    usage-plans-rate-limits：
       1.对请求接口的访问频率的限制，亚马逊采用令牌桶的算法。亚马逊的API接口对访问评率有很严格的要求，开发时一定要考虑使用响应头里的x-amzn-RateLimit-Limit参数查看剩余的次数，不要不理会429异常，总是重试去请求。这样会导致接口访问评率过大触发防火墙的校验，导致整体接口不能使用（我们在对接过程中就遇到过，给你返回的异常是直接forbidden的，而且没有任何文档解释原因）
       2.有些比如查询订单的接口，不要做太频繁的轮询接口查询，可以对接Notification API订阅通知来获取新订单的消息后做查询，这样就可以大大降低被限流的风险
    use-case-guides：
    使用案例引导，这里面是调用某些接口的具体的方法讲解及代码示例
    重点讲下Authorization API： 这个API是用于做MWS迁移到SPAPI的，一般对第三方服务商作用比较大，因为卖家基本上使用自授权的模式，SPAPI的app不需要发布，不存在让其他店铺授权到app的情况，所以不太需要。这个接口能调用的条件是app必须审核通过发布完成后才可调用

2.selling-partner-api-models

 models: 
     各个接口的model，swagger生成client端代码的输入参数
clients: 
     postman-collections postman方式的请求接口案例，目前只包含restrictedDataToken 使用请求PII数据的案例 tokens-api-sandbox-postman-collection.json，估计以后会添加更多
     sample-code  案例代码   目前只包含PII的restrictedDataToken的java案例代码restricted-data-token-workflow.java
     sellingpartner-api-aa-csharp  c#版的签名代码库
     sellingpartner-api-aa-java  java版本的签名代码库，这是swagger生成的client端代码都需要用到的公共模块，也就是组装鉴权信息的模块
     里面分两部分，一是AWS的签名（这就是我们申请app前AWS的注册和IAM的credentials信息签名部分），二是LWA（Login with Amazon）的签名（这就是我们app的ClientId和ClientSecret以及access_token的签名部分）
    sellingpartner-api-documents-helper-java
    这是文档下载及上传的加解密代码库，大家知道在feeds和reports等接口里面，经常用到文件的上传和下载，且需要对文件做加解密操作，那么这个helper就是提供加解密的java库的，可以拿来即用

3.amazon-sp-api
整个SP-API的docs及models了解下来，内容比较多，在用swagger生成的时候，也是每个model生成一个独立的java 模块。每个业务模块里面都有很多公共的代码。所以我抽出公共代码组合整理成一个SDK分享在github上, 可拿来即用，当然好用的话，请给个star，谢谢

docs：所有业务API的接口方法的markdown文档
src：
    SellingPartnerAPIAA：公用的签名模块
    api：  包含所有的业务API的java类
    auth和client：请求所有业务API用到的http请求共用模块
    documents：整合的上传和下载文件的加解密公用模块
    model：是所有业务接口请求和返回的数据模型

只需要依赖这个SDK就可以很方便的做业务对接开发，当然我们也可以在这个SDK的基础上将自己的请求参数配置好做一个spring boot starter，给到所有的业务系统做依赖使用，做到参数的统一管理等

除了java 的SDK,还有js和php版本的（这两个不是我整理的）
js版本: https://github.com/amz-tools/amazon-sp-api
php版本：https://github.com/clousale/amazon-sp-api-php

6.注意事项

1.申请app的资料填写要慎重准确，权限选择要想清楚，不要多次修改（审核发布时间比较长，会影响进度）

2.请求业务接口的频率要控制好，不要随意轮询，会导致整体接口不可用的风险，等出现了去提case解决的过程会比较长

3.建议保持独立的环境，做到一个AWS账号+一套IAM+一个店铺账号+一个app +一个或多个独立纯净出口IP（出口IP可以用代理+账号路由来实现）

4.为了业务接口稳定，最好做VPN代理服务器访问，代理到香港或美国等

5.第三方服务商开发者需要记录卖家授权的时间，在一年有效期到达前提前通知客户延期，防止业务中断风险

7.可参考的资料

SP-API公众号: https://mp.weixin.qq.com/s/Gu4UwM2r7dPY-jf6_h9fUw

SP-API动手训练营:https://www.spapi.org.cn/cn/intro.html

AMAZON-SP-API SDK: https://github.com/penghaiping/amazon-sp-api

亚马逊SP-API对接JAVA版: https://blog.csdn.net/penghaiping1001/article/details/113524366

PII权限使用解析：https://blog.csdn.net/penghaiping1001/article/details/120002089

8.SPAPI错误码解释

SPAPI错误码解释（MD5100 MD9000 MD1000 403 Unauthorized SPDC）
SP-API Errors Frequently Asked Questions
Troubleshooting Selling Partner API authorization errors