您的位置 : 文档中心 -> 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

子账号授权流程详解隐藏

子账号授权时仅仅依赖于主账号的授权,主账号授权成功才可以管理子账号的授权。下面针对三类应用分别说明子账号如何授权。

1、企业对接APP
企业IT人员可以直接在开放平台控制台授权管理页面进行子账号的授权管理,包括查询、批量授权和批量取消授权,另外主账号也可以在我的授权页面进行子账号授权管理。对于多用户app,子账号授权后在页面可以拿到一个持久accessToken;对于单用户app,授权后也是直接用appKey调用api,不过对于子账号需要额外传入一个子账号登录名参数binding_login_id。

2、软件对接APP
软件开发人员可以通过调用api来管理子账号授权,需要传入主账号的accessToken以及子账号id列表,包括批量查询、批量授权和批量取消授权,另外主账号也可以在我的授权页面进行子账号授权管理。api有如下三个。

a)批量查询
请求url类似https://gw.open.1688.com/openapi/param2/1/system.oauth2/subaccount.auth.list/YOUR_APPKEY?subLoginIdList=a,b&access_token=ACCESS_TOKEN
正常返回结果类似{"returnValue":[{"adminOwnerId":"xx","adminUserId":xx,"status":"authorized","subOwnerId":"xx","subUserId":xx,"accessToken":"xx"}],"success":true}
其中status表示授权状态,主要有authorized,canceled,auth_expired,分别表示已授权,已取消和已过期。还会返回主子账号的loginId和userId,以及授权凭证accessToken,依然是10小时有效期
异常返回结果类似{"errorCode":"xx","errorMessage":"xx","success":false}

b)批量授权
请求url类似https://gw.open.1688.com/openapi/param2/1/system.oauth2/subaccount.auth.add/YOUR_APPKEY?subLoginIdList=a,b&access_token=ACCESS_TOKEN
正常返回结果类似{"returnValue":{"xx":{"accessToken":"xx","accessTokenTimeout":36000,"resourceOwnerId":"xx","memberId":"xx","aliId":xx}},"success":true}
返回的主体内容是一个map,key为子账号loginId,value为对应的授权信息,字段跟主账号授权返回的字段类似,只是没有refreshToken。
异常返回结果类似{"errorCode":"xx","errorMessage":"xx","success":false}

c)批量取消
请求url类似https://gw.open.1688.com/openapi/param2/1/system.oauth2/subaccount.auth.cancel/YOUR_APPKEY?subLoginIdList=a,b&access_token=ACCESS_TOKEN
正常返回结果类似{"returnValue":true,"success":true}
返回的主体内容是一个布尔值,标识取消授权是否成功,如果为false则需要重试。
异常返回结果类似{"errorCode":"xx","errorMessage":"xx","success":false}

3、应用工具APP
暂不支持子账号授权管理,子账号授权逻辑跟以前一样,主账号授权后先到1688的子账号控制台给子账号分配使用权限,然后子账号就可以直接在服务市场或者work工作台使用有权限的应用,子账号会以主账号的名义使用第三方工具,所以ISV拿到的授权用户还是主账号,无法感知是子账号在使用。