您的位置 : 文档中心 -> API授权说明

授权说明

应用程序可通过调用开放平台提供的API获取到阿里巴巴的会员、交易等数据,因为涉及数据隐私,所以在使用前必须获得阿里巴巴会员的授权,才可以调用API(公开数据除外)。

授权方式展开

目前开放平台提供了三种授权方式:单用户授权,简单多用户授权,OAuth授权,具体内容如下:

1、单用户授权展开

单用户授权意味着您的应用程序只能被一个阿里巴巴用户授权,适用于企业对接场景,企业只需要在1688上使用一个账号进行商品采购或者商品售卖,授权流程可以简单归纳为:
(1)对接应用审核通过后开发者可以在控制台添加授权用户,默认为开发者自己,如果授权用户有登录邮箱,系统会自动发送邀请邮件,开发者账号除外;
(2)授权用户拿到邮件中或者开发者提供的授权确认链接,然后访问此链接确认授权;
(3)开发者可以参考 API调用说明了解如何调用API,注意不需要传access_token,因为这样调用api操作的就是唯一授权用户的数据。

2、多用户授权展开

多用户授权适用于企业对接场景,并且企业在1688有多个店铺或者买家账号,授权流程可以简单归纳为:
(1)开发者在控制台添加授权用户,默认为开发者自己,如果授权用户有登录邮箱,系统会自动发送邀请邮件,开发者账号除外;
(2)授权用户拿到邮件中或者开发者提供的授权确认链接,然后访问此链接确认授权;
(3)开发者在控制台拿到持久的访问令牌(accessToken);
(4)开发者可以参考 API调用说明了解如何调用API,注意调用API时传入此accessToken,这样操作的是此token对应授权用户的数据。

3、OAuth授权展开

阿里巴巴开放平台采用OAuth 2.0作为授权协议,授权流程可以简单归纳为:
(1)获取临时令牌;
(2)用临时令牌换取长时令牌以及访问令牌;
(3)访问令牌过期后用长时令牌刷新访问令牌。
关于临时令牌访问令牌以及长时令牌的介绍请参考下一节概念介绍

概念介绍展开

1、appKey和appSecret

appKey是app的唯一标识,appSecret是app的密钥,它们相当于用户名和密码。注册app之后就会生成一个appKey和appSecret,请妥善保存。另外appSecret和密码一样也可以重置,在编辑或者查看app的页面都可以重置密钥。

2、code

即临时令牌。当用户在开放平台访问app前,需对app进行授权,用户授权后,app方可访问用户的隐私数据。用户在完成授权之后,会跳转到redirect_uri,并带上临时令牌code,app再用code从开放平台后台接口换取access_token。code为一次性令牌,有效期为2分钟。

3、access_token

即用户授权令牌,为用户一次会话的授权标识,有效期10小时。在获得code后,通过调用开放平台后台接口getToken来获取access_token。 App在访问用户隐私数据时,需要带上access_token,也只有accessToken才能作为访问的凭证,其他token如code和refreshToken都不能直接作为访问凭证,需要转换为accessToken之后才能访问用户隐私数据。

4、refresh_token

即长时令牌,有效期半年。当access_token过期后,可以使用refresh_token换取新的access_token访问用户数据。

5、redirect_uri

即回调地址,指的是App发起请求时,所传的回调地址参数,必填。请参考授权流程中的说明。

授权分类

请选择授权方式:

注意:请根据自己APP的情况选择对应的授权方式,如果使用了错误的授权方式可能给您APP的使用带来不便

1、托管式授权

第三方开发者提供的app会托管在应用市场进行售卖,用户要通过应用市场访问app,那么这样的app就要采用托管式授权方式。

2、WEB端授权

第三方开发者提供的app属于网页应用,但是不在应用市场售卖,可以自用或者自行售卖,用户直接在浏览器中输入app入口地址即可访问,那么这样的app就要采用WEB授权方式。

3、客户端授权

第三方开发者提供的app属于客户端应用,用户需要下载应用到本地客户端才能使用,那么这样的app就要采用客户端授权方式。

托管式授权流程详解 隐藏

授权及使用授权时序图

授权流程

托管式授权是指将授权托管给应用市场,由应用市场发出授权请求的方式。

1) 用户通过应用市场使用app

2) 应用市场向1688开放平台发起授权请求

3) 如果用户没有授权或者授权过期,需要输入用户名密码,并确认授权;否则跳到下一步

4) 应用市场获得临时令牌code,并302跳转到app入口地址,同时带入参数code

5) app使用code换取access_token

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","access_token":"f14da3b8-b0b1-4f73-a5de-9bed637e0188","refresh_token_timeout":"20121222222222+0800"}
说明: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
子账号授权