文档中心
一、前言

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


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


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


3Refreshing 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是在服务商后台创建的收费项目中的收费代码。



三、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)。

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

如下图:

授权登录


2.2 用户确认授权(用户登录后)

如下图:


授权确认页​


2.3 获取授权码code

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

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


授权回调链接​


2.4 获取访问令牌

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

如下图:

授权登录


2.2 用户确认授权(用户登录后)

如下图:


授权确认页​


2.3 获取授权码code

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

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


授权回调链接​


2.4 获取访问令牌

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

代码示例(JAVA):


授权码获取访问令牌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


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