亚马逊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 information 和 Pricing、App details都如实填写就行
两点我之前遇到的问题:
1.在第点击提交时,报错说spc3000,我这边时由于在 App information中的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: 开发者总引导文档,从这篇文档开始深入理解整个SPAPImigration-guide:迁移的引导文档,给老的MWS需要平滑过渡到SPAPI对接的开发者使用的。对于第三方服务商,这个迁移的API就很有用,因为可以做到不用卖家参与就可以过渡到SPAPI授权上来。里面有个核心的API就是Authorization API,可以实现用MWS授权的MwsAuthToken去换取SPAPI的授权refresh_tokenRoles: 在申请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.javasellingpartner-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
亚马逊SP-API对接实践解析(amazon selling partner api)相关推荐
- 对接亚马逊 SP-API(Amazon Selling Partner API) 第四章:签名
目录 1. 前提概要 2. Authorization 介绍 Python 版本完整案例 3. 拼接 Authorization Task 1: Create a canonical request ...
- 对接亚马逊 SP-API(Amazon Selling Partner API) 第一章:注册帐号
目录 1. SP-API 基本介绍 1.1. 从 MWS 迁移到 SP-API 1.2. SP-API 开发者指南 1.3. MWS 与 SP-API 接口映射 1.4. SP-API 的站点 2. ...
- 对接亚马逊 SP-API(Amazon Selling Partner API) 第二章:授权
目录 1. 授权销售伙伴 API 应用程序 1.1. Marketplace Appstore workflow 1.2. Website workflow(推荐使用) 1.3. 自行授权(仅限店铺本 ...
- 对接亚马逊 SP-API(Amazon Selling Partner API) 第三章:对接 SDK
目录 必要条件 1. Generating a Java SDK with LWA token exchange and authentication 1.8. SwaggerToCL 结构. 1.9 ...
- QCon速递:亚马逊AWS技术应用实践
2015年4月23日,为期3天的QCon全球软件开发大会(北京站)正式拉开帷幕.在『亚马逊AWS技术应用实践』专题中,讨论了亚马逊AWS热门服务与工具及典型架构,涉及自动化运维.混合云.移动应用开发和 ...
- 星淘惠跨境:亚马逊SP广告是什么?SP广告有什么作用
亚马逊卖家通过会采用广告投放进行推广,因为卖家需要通过广告获得更高的流量以及销量.亚马逊SP广告就是按点击付费的广告. 亚马逊广告的作用有哪些? 提升关键词排名 卖家可通过广告累积出单量,出单量积累到 ...
- 亚马逊 新版卖家中心 销售伙伴API(amazon selling partner API)开发人员指南
文章目录 关于本指南 术语 什么是销售合作伙伴 API? 主要特点 全球应用 销售合作伙伴 API 端点 市场 ID 值 注册为开发者 检查您注册为开发人员的请求的状态 创建和配置 IAM 策略和实体 ...
- 亚马逊SP广告报告解析
序言:对接亚马逊广告,很重要一个工作是要对广告报告进行分析,比如分析各个产品广告花费分布.投入产出比.曝光量之类.在分析之前,我们需要知道广告报告总共有哪些类型报告.我根据亚马逊官方后台并结合实际开发 ...
- 对接亚马逊 SP-API(Amazon Selling Partner API) 第六章:Fulfillment Inbound 模块
1. API 对比 MWS操作 SP-API操作 简短说明 CreateInboundShipmentPlan createInboundShipmentPlan 返回创建 入库货件所需的信息. Cr ...
最新文章
- 为什么ajax请求进不来后端路由_为什么要前后端分离?前后端分离的优点是什么?...
- mysql 拼接sql批量执行_MySql 学习之 一条更新sql的执行过程
- Datawhale MySQL 训练营 Task2 查询语句
- python split函数 空格_python上手--10行代码读懂红楼梦
- python取余_大牛带你打牢Python基础,看看这10语法
- Taotao Picks Apples
- 没事爱在线上制造故障?这位程序媛有话说
- 使用代码辅助生成工具CodeSmith -- 生成NHibernate的映射文件
- 二阶滤波器matlab代码,双二阶滤波器之MATLAB设计及C语言实现
- CocosCreator之KUOKUO带你做刚体移动与物品拾取到背包
- 警告: PREMNMX is an obsolete function.解决办法
- 嵌入式技术与应用专业毕业以后可以做什么?
- 【Kafka】ZK、Kafka以及EFAK的安装、配置
- OC中类别(Catagory)基本使用
- VirtualLab基础实验教程-7.偏振(2)
- ERROR 1366 (HY000): Incorrect string value: '\xCA\xD6\xBB\xFA\xCA\xFD...' for column 'cname' at row
- python语言的实验心得体会范文_实验心得体会-精选范文
- php抽奖的数字滚动器,jQuery数字滚动插件
- 怎么看计算机硬件配置情况,怎么样查看电脑配置?5种方法查看电脑硬件配置好坏图文详解...
- GLES2.0中文API-glGetActiveAttrib