开放服务-文档中心

热词搜索： SDK下载应用创建 API调用

oauth2.0授权说明

一、前言
二、名词解释
三、Server-side flow
四、Native Application
五、Refreshing an Access Token
六、错误码说明
七、注意事项

更新时间: 2020-11-19

一、前言

如果您的应用和苏宁开放服务平台对接后，需要获取一些与用户紧密相关的信息（如订单、商品、促销等），为保证数据的安全性和隐私性，需要取得用户的同意，引导用户授权。苏宁开放服务平台采用国际通用的OAuth2.0标准协议，支持网站、桌面客户端、手机客户端。如果要了解更多关于OAuth2.0的技术说明，请参考官方网站 http://oauth.net/2/ 。苏宁开放服务平台的OAuth2.0中约定Access Token有效期受应用订购时长影响，当订购时长小于1年时，token有效期即为订购有效期；当订购时长大于1年时，token有效期为1年，达到1年期后重新授权即可。目前，支持以下方式获取Access Token ：

（1）Server-side flow 此流程要求ISV和商家应用有Web Server，能够保持应用本身的密钥以及状态，可以直接访问苏宁的授权服务器。

（2）Native Application 此流程适合ISV没有自己的web服务器，且应用为原生程序，即客户端应用（同时应用无法与浏览器交互，但是可以外调用浏览器）。

（3）Refreshing an Access Token 通过前两种流程，获取了Access token以及Rrfresh token(刷新令牌，对于具有“获取Refresh token权限”的应用），Access token都有一定的期限，当Access token过期时，用户可以用Refresh token获得一个Access token。

二、名词解释

1. redirect_uri和callback定义规则

redirect_uri指的是应用发起请求时，所传的回调地址参数。

callback指的是应用注册时填写的回调地址链接或者网站接入时所验证的域名地址。

2. scope定义规则

scope指的是应用发起请求时，所请求的API调用权限范围。

scope参数为以下可选值：

item,category, order

应用发起请求时，多个scope值要求用逗号分隔。

3. accessToken

Access Token即用户授权后颁发的凭证。它代表了用户授予应用访问用户在苏宁上特定资源的权限。

4. AppKey和appSecret

AppKey是创建应用时，开放平台分配给应用的的标识，用以鉴别应用的身份。

App Secret是苏宁给应用分配的密钥，开发者需要妥善保存这个密钥，这个密钥用来保证应用来源的可靠性，防止被伪造。

5. itemcode

itemcode是在服务市场后台创建的收费项目(https://fws.suning.com/fws/serviceRelease/releaseList.action)中的收费代码。

三、Server-side flow

此流程要求应用有Web Server，能够保持应用本身的密钥以及状态，可以通过https直接访问苏宁的授权服务器。如下图所示:

图2 授权时序图

授权过程分为两个步骤：

(1) 通过用户授权获取授权码Code；（获取授权码:https://open.suning.com/api/oauth/authorize）。

注：通过服务市场“立即使用”进行授权的场景，由服务市场自行完成授权码的获取，服务所在的应用不需要调用该链接。

(2) 用上一步获取的Code和应用密钥（AppSecret）通过Http Post方式换取Token。

（获取访问令牌：https://open.suning.com/api/oauth/token）。

注：即图2授权时序图中第7步“访问获取tocken(访问令牌)接口”请调用本链接。

1. 参数说明

1.1 获取授权码参数

参数名字	参数选项	默认值	参数释义	用途描述	备注
client_id	必选		应用客户端标识	用来唯一标识应用
response_type	必选	code	授权请求响应类型	标识响应数据是授权码	请求授权码时参数值必须设为“code”
redirect_uri	必选		授权响应重定向URI	授权认证成功后重定向的uri	需在创建应用时填写重定向地址,redirect_uri必须和填写的URI域名一致
scope	可选		授权范围	标识用户授予应用访问资源服务器上的资源范围	访问请求的作用域，以逗号隔开，暂不使用
state	可选		状态码	维护请求和响应的状态，传入值与返回值保持一致	暂不使用
itemcode	必选		版本ID	线上订购应用服务的版本id	必填

1.2 返回值说明

参数名字	参数选项	参数释义	用途描述
code	正常结果	授权码	授权码
error	异常时返回	错误码	错误码
error_description	异常时返回	错误码描述	错误码描述
state	可选	状态	维护请求和响应的状态
userid	可选	用户编码	授权用户在苏宁的唯一编码(只返回主账号会员编码)
itemcode	可选	版本编码	授权应用的版本
orderId	可选	订单号	质检应用授权专用
scope	可选	授权范围	授权访问的资源范围

1.3 获取访问令牌参数

参数名字	参数选项	默认值	参数释义	用途描述	备注
client_id	必选		应用客户端标识	用来唯一标识应用	对应于应用注册时返回的appKey
client_secret	必选		应用客户端密钥	用来进行应用鉴权	对应于应用注册时返回的appSecret
code	必选		授权码	用户授权凭证
grant_type	必选		授权许可类型	用于标识获取令牌的授权许可类型	Web-server子态获取令牌流程，该字段为authorization_code
redirect_uri	必选		授权响应重定向URI	终端用户的授权步骤完成时授权服务器将要把user-agent重定向到的一个绝对URI	应用注册时，需要预先注册它们的重定向URI，再授权操作中，redirect_uri必须和注册时的URI域名一致
scope	可选		授权范围	标识用户授予应用访问资源服务器上的资源范围	访问请求的作用域，以空格隔开的字符串列表来表示暂不使用
state	可选		状态码	维护请求和响应的状态，传入值与返回值保持一致	暂不使用

1.4 返回值说明

参数名字	参数选项	默认值	参数释义	用途描述	备注
access_token	必选		访问令牌	用于访问资源服务上用户的资源凭证
token_type	必选		令牌类型	类型目前只支持bearer
refresh_token	可选		刷新令牌	用户访问令牌的刷新或者生成新的访问令牌	只有第一次授权有
expires_in	必选		访问令牌过期时间	用于访问令牌的时效性控制	单位:秒
re_expires_in	可选		刷新令牌过期时间	用于刷新令牌的时效性控制
suning_user_name	必选		苏宁用户名	考虑到应用可能需要苏宁用户名和访问令牌进行绑定操作	返回主账号用户名
custnum	必选		用户会员编码	返回授权登录用户的会员编码	主账号授权登录返回主账号会员编码，子账号授权登录返回子账号会员编码
module	必选		用户类型	返回授权登录用户的用户类型
vendorCode	必选		商家编码	返回授权登录用户的商家编码

2. 应用示例

2.1 引导用户授权登录

https://open.suning.com/api/oauth/authorize?response_type=code&client_id=1&redirect_uri=1&scope=item,price&state=1&itemcode=1

如下图:

图3 授权登录

2.2 用户确认授权（用户登录后）

如下图：

图4 授权确认页

2.3 获取授权码code

出现授权页面后，用户可以选择“授权“ 或 ”取消“。

若用户同意授权，页面跳转至应用的回调地址，同时返回授权码code,版本ID itemcode以及state等参数。如下图：

图5 授权回调链接

2.4 获取访问令牌

方式换取Token（访问令牌，即Sessionkey），苏宁开放服务平台会以json文本的形式返回响应的值。

代码示例（JAVA）：

图6 授权码获取访问令牌JAVA示例代码

代码示例（C#）

图7授权码获取访问令牌C#示例代码

返回JSON格式示例：

{"access_token":"1","token_type":"1","refresh_token":"1","expires_in":"1","re_expires_in":"1","suning_user_name":"1","custnum":"1","module":"1","vendorCode":"1"}

四、Native Application

此流程适合ISV没有自己的web服务器，且应用为原生程序，即客户端应用（同时应用无法与浏览器交互，但是可以外调用浏览器）。

请求的流程有：

获取授权码：https://open.suning.com/api/oauth/authorize

获取访问令牌：https://open.suning.com/api/oauth/token

1. 参数说明

1.1 获取授权码输入参数

参数名字	参数选项	默认值	参数释义	用途描述	备注
client_id	必选		应用客户端标识	用来唯一标识应用
response_type	必选	code	授权请求响应类型	标识响应数据是授权码	请求授权码时参数值必须设为“code”
redirect_uri	必选	urn:ietf:wg:oauth:2.0:oob			参数值为默认值
scope	可选		授权范围	标识用户授予应用访问资源服务器上的资源范围	访问请求的作用域，以逗号隔开，暂不使用
state	可选		状态码	维护请求和响应的状态，传入值与返回值保持一致	暂不使用
itemcode	必选		版本ID	线上订购应用服务的版本id	必填

1.2 获取访问令牌参数

参数名字	参数选项	默认值	参数释义	用途描述	备注
client_id	必选		应用客户端标识	用来唯一标识应用	对应于应用注册时返回的appKey
client_secret	必选		应用客户端密钥	用来进行应用鉴权	对应于应用注册时返回的appSecret
code	必选		授权码	用户授权凭证
grant_type	必选		授权许可类型	用于标识获取令牌的授权许可类型	Web-server子态获取令牌流程，该字段为authorization_code
redirect_uri	必选	urn:ietf:wg:oauth:2.0:oob			参数值为默认值
scope	可选		授权范围	标识用户授予应用访问资源服务器上的资源范围	访问请求的作用域，以空格隔开的字符串列表来表示暂不使用
state	可选		状态码	维护请求和响应的状态，传入值与返回值保持一致	暂不使用

2. 应用示例

2.1 应用引导用户登录

https://open.suning.com/api/oauth/authorize?response_type=code&client_id=1&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=item,price&state=1&itemcode=1

如下图:

图8 授权登录页

2.2 用户确认授权

如下图：

图9 授权确认页

2.3 获取授权码

回调到授权默认页面，同时将授权码显示在页面上。如下图：

图10 授权码显示页

2.4 获取访问令牌

用上一步获取的code和注册应用时分配的AppSecret，通过Http Post方式换取Token（访问令牌，即Sessionkey），苏宁开放服务平台会以json文本的形式返回响应的值。

示例代码（JAVA），如图6。

示例代码（C#）,如图7。

返回JSON格式示例：

{"access_token":"1","token_type":"1","refresh_token":"1","expires_in":"1","re_expires_in":"1","suning_user_name":"1","custnum":"1","module":"1","vendorCode":"1"}

五、Refreshing an Access Token

1. 参数说明

通过前两种流程，获取了Access token以及Refresh token（对于具有“获取Refresh token权限”的应用）,但是一般来讲，access token都有一定的有效期，在刷新有效时长内必须通过Refresh token 来延迟Access token的时长。根据刷新令牌获取访问令牌参数如下：

参数名字	参数选项	默认值	参数释义	用途描述	备注
client_id	必选		应用客户点标识	用来唯一标识应用	对应于应用注册时返回的appKey
client_secret	必选		应用客户端密钥	用来进行应用鉴权	对应于应用注册时返回的appSecret
refresh_token	必选		刷新令牌	用于获取访问令牌
redirect_uri	必选				回调地址
grant_type	必选		授权许可类型	用于标识获取令牌的授权许可类型	刷新令牌流程，该字段为refresh_token
scope	可选		授权范围	标识用户授予应用访问资源服务器上的资源范围	访问请求的作用域，以空格隔开的字符串列表来表示，暂未使用
state	可选		状态码	维护请求和响应的状态，传入值与返回值保持一致	暂未使用

2. 调用示例

示例代码（JAVA），如下图：

图11 刷新令牌获取访问令牌JAVA示例代码

示例代码（C#），如下图：

图12刷新令牌获取访问令牌C#示例代码

返回JSON格式示例：

{"access_token":"1","token_type":"1","refresh_token":"1","expires_in":"1","suning_user_name":"1"}

六、错误码说明

1、获取授权码操作

（1） app status is invalid : 应用状态无效

（2）app appkey is overdue : 应用appKey过期

（3）redirect_url is not match the register uri : 提供的重定向URL与预先注册的值不匹配

（4）client_Id is inValid : 无效的appKey

（5）规格ID不存在：请检查拼的链接中规格ID是否缺失

（6）授权请求预处理失败，请重试：请对照正确拼连接中参数检查是否缺少拼的参数

2、获取token操作

（1） app status is invalid : 应用状态无效

（2）app appkey is overdue : 应用appKey过期

（3）redirect_url is not match the register uri : 提供的重定向URL与预先注册的值不匹配

（4）authorize_code is overdue : 授权码过期

（5）authorize_code is invalid : 授权码无效

（6）client_Id is inValid : 无效的appKey

（7）refresh token interval 5 minute：刷新token间隔5分钟

（8）refresh_token is invalid:刷新令牌失效

七、注意事项

1、商户初次使用订购的应用时，需在服务市场的”我的服务“菜单中找到订购的应用，点立即使用进行授权，走URL地址拼链接授权方式易导致报错且此方式逐渐被禁用。

2、商户走服务市场每点击一次立即使用按钮，则access_token会相应的刷新变化一次，服务商可登陆http://open.suning.com中控制台“授权管理"菜单下查看授权日志记录。

3、使用拼链接的服务商因拼的链接中参数不全，可能会导致出现“规格ID不存在” “授权预处理失败，请重试”的报错，这时候请对照正确的拼连接格式检查参数,正确的格式demo:https://open.suning.com/api/oauth/authorize?response_type=code&client_id=1&redirect_uri=1&scope=item,price&state=1&itemcode=1

4、关于子账号授权，多个子账号共享主账号的订购关系，因此其中一个子账号授权刷新token会导致其他子账号的授权token被刷新失效。