1688开放平台WEB端授权教程

一、WEB授权方式：

对于WEB授权开发方式而言，您的app不会在阿里巴巴应用市场售卖，那么您需要完成完整的授权过程，请参考如下授权流程

二、WEB端授权流程详解：
授权及使用授权时序图

如果已经授权并且得到refreshToken，那么可以参考refreshToken换取accessToken流程详解一节；如果是首次授权，那么授权流程如下：

1) 用户使用app，访问在 1688 的隐私数据

2) app发起授权请求

https://auth.1688.com/oauth/authorize?client_id=xxx&site=1688&redirect_uri=YOUR_REDIRECT_URL&state=YOUR_PARM

a) client_id：app注册时，分配给app的唯一标示，又称appKey

b) site:site参数标识当前授权的站点，直接填写1688

c) redirect_uri: app的入口地址，授权临时令牌会以queryString的形式跟在该url后返回。注意参数中回调地址的域名必须与app注册时填写的回调地址的域名匹配。

d) state：可选，app自定义参数，回跳到redirect_uri时，会原样返回

3) 用户输入用户名密码，并确认授权

4) 返回临时授权码code给app
具体返回方式，参照redirect_uri说明

5) 使用code获取令牌

https://gw.open.1688.com/openapi/http/1/system.oauth2/getToken/YOUR_APPKEY?grant_type=authorization_code&need_refresh_token=true&client_id= YOUR_APPKEY&client_secret= YOUR_APPSECRET&redirect_uri=YOUR_REDIRECT_URI&code=CODE

注：此接口必须使用POST方法提交；必须使用https

getToken接口参数说明：

a) grant_type为授权类型，使用authorization_code即可

b) need_refresh_token为是否需要返回refresh_token，如果返回了refresh_token，原来获取的refresh_token也不会失效，除非超过半年有效期

c) client_id为app唯一标识，即appKey

d) client_secret为app密钥

e) redirect_uri为app入口地址

f) code为授权完成后返回的一次性令牌

g) 调用getToken接口不需要签名注：如果超过code有效期（2分钟）或者已经使用code获取了一次令牌，code都将失效，需要返回第二步重新获取code

6) 返回令牌
getToken返回结果：{"aliId":"8888888888","resource_owner":"xxx","memberId":"xxxxxxx","expires_in":"36000","refresh_token":"479f9564-1049-456e-ab62-29d3e82277d9","refresh_token_timeout":"20121222222222+0800","access_token":"f14da3b8-b0b1-4f73-a5de-9bed637e0188"}
说明：resource_owner为登录id，memberId为会员接口id，aliId为阿里巴巴集团统一的id，refresh_token_timeout表示refreshToken的过期时间

7) 使用令牌访问用户隐私数据
例如访问以下api ： http://gw.open.1688.com/openapi/param2/1/cn.alibaba.open/member.get/1?memberId=xxx&access_token=ACCESS_TOKEN&_aop_signature=SIGENATURE
签名示例见API签名规则

三、refreshToken换取accessToken流程详解

换取accessToken流程

如果refreshToken有效并且accessToken已经过期（超过10小时），那么可以使用refresh_token换取access_token，不用重新进行授权，然后访问用户隐私数据。

注意：如果refreshToken已经超过了半年的有效期，用户修改密码，用户订购到期或者用户通过取消授权工具取消了对app的授权，那么都需要用户重新授权获取refreshToken

换取accessToken的url示例如下：

https://gw.open.1688.com/openapi/param2/1/system.oauth2/getToken/YOUR_APPKEY请求参数如下：

grant_type=refresh_token&client_id=YOUR_APPKEY&client_secret=YOUR_APPSECRET&refresh_token=REFRESH_TOKEN
注：此接口必须使用POST方法提交；必须使用https

a) 此处grant_type参数必须为refresh_token，表示通过refreshToken换取accessToken，而不是通过临时code换取

b) 调用getToken接口时不需要签名

四、换取新的refreshToken流程详解

换取refreshToken流程

如果当前时间离refreshToken过期时间在30天以内，那么可以调用postponeToken接口换取新的refreshToken；否则会报错。

注意：有自动功能的应用（用户不进入应用主页也能使用第三方应用，因为在应用后台可以自动调用api处理用户数据，如自动重发类的应用）才需要调用此接口。如果没有自动功能，那么不需要调用，因为用户必须在应用主页操作才能获取以及修改用户数据，所以即使refreshToken过期了，用户再次通过应用市场进入应用主页时授权一次即可

换取refreshToken的url示例如下：

https://gw.open.1688.com/openapi/param2/1/system.oauth2/postponeToken/YOUR_APPKEY请求参数如下：

client_id=YOUR_APPKEY&client_secret=YOUR_APPSECRET&refresh_token=REFRESH_TOKEN&access_token=ACCESS_TOKEN返回结果类似getToken的返回结果：

{"aliId":"8888888888","resource_owner":"xxx","memberId":"xxxxxxx","expires_in":"36000","refresh_token":"479f9564-1049-456e-ab62-29d3e82277d9","access_token":"f14da3b8-b0b1-4f73-a5de-9bed637e0188","refresh_token_timeout":"20121222222222+0800"}
注：此接口必须使用https，get和post都行

a) 调用postponeToken接口需要授权，所以必须带上access_token参数

b) 调用postponeToken接口时不需要签名

c) refresh_token参数表示当前使用的refreshToken，如果refreshToken的有效期和当前时间的差值小于30天，那么调用此接口后当前使用的refreshToken失效，返回一个新的refreshToken

五、签名规则

一、API签名算法及工具

API签名算法及工具

二、API签名串组装规则

在1688开放平台，url请求的多个参数都要参与签名（与文件上传有关的api中，文件字节流那个参数不参与签名），下面以两个参数为例，假设请求的url格式如下所示：
http://gw.open.1688.com/openapi/param2/1/system/currentTime/1000000?b=2&a=1（appKey=1000000，假设 secretKey=test123）

参照签名算法说明，签名串s组装规则为：
1、构造签名因子：urlPath。url 中的一部分，我们称之为urlPath，从协议（param2）开始截取，到“?”为止，urlPath=param2/1/system/currentTime/1000000
2、构造签名因子：拼装的参数。参数 b=2&a=1，首先将参数的key和value拼在一起，得到b2和a1，然后按照首字母排序，得到a1和b2，最后按顺序拼在一起得到a1b2
3、合并两个签名因子。把前两步的字符串拼起来，得到s = param2/1/system/currentTime/1000000a1b2
4、对合并后的签名因子执行hmac_sha1算法。 Signature=uppercase (hex (hmac_sha1 (s, secretKey)) 得到签名33E54F4F7B989E3E0E912D3FBD2F1A03CA7CCE88
——secretKey为签名密钥，与urlPath中的appKey（1000000）对应
——hmac_sha1为通用的hmac_sha1算法，各编程语言一般都对应类库
——hex为转为十六进制
——uppercase为转为大写字符

说明：API签名算法主要是使用urlPath和请求参数作为签名因子进行签名，主要针对api 调用

三、参数签名算法及工具

参数签名算法及工具

四、参数签名串组装规则

在1688开放平台，用户在客户端访问app时app发起的授权请求url如下所示：（注意：只有客户端或WEB端授权流程中的"app发起授权请求"这一步的签名才使用此规则，参见客户端流程详情）
http://gw.open.1688.com/auth/authorize.htm?client_id=YOUR_CLIENT_ID&site=china&redirect_uri=YOUR_REDIRECT_URL&state=YOUR_PARAM&_aop_signature=SIGNATURE
注意：此处访问的是授权页面authorize.htm，并不是api调用，所以没有urlPath，不能用API签名算法，只是用请求参数作为签名因子进行签名。请求参数的拼装算法跟API签名一致

假设用户授权请求的参数为 client_id=10000&site=china&redirect_uri=http://localhost:8888&state=test（ client_id为appKey，对应的签名密钥假设为 client_secret=abcd），那么签名串的组装规则为：
1、构造签名因子：拼装的参数。参数 client_id=10000&site=china&redirect_uri=http://localhost:8888&state=test， key和value拼在一起得到 client_id10000&sitechina&redirect_urihttp://localhost:8888&statetest，然后按照首字母排序，排序后为 client_id10000&redirect_urihttp://localhost:8888&sitechina&statetest，然后将排序后的数组拼在一起，得到最终的签名因子 data=client_id10000redirect_urihttp://localhost:8888sitechinastatetest
2、对最终的签名因子执行hmac_sha1算法。 Signature=uppercase (hex (hmac_sha1 (data, client_secret)) 得到签名CA538FE6B2180496B77EB46D0EBB5A2EA7A2418B
——client_secret为签名密钥，与值为10000（client_id参数的值）的appKey对应
——hmac_sha1为通用的hmac_sha1算法，各编程语言一般都对应类库
——hex为转为十六进制
——uppercase为转为大写字符

说明：参数签名算法只使用请求参数作为签名因子进行签名，仅针对客户端或WEB端授权时请求临时令牌code