|
API授权说明应用程序可通过调用开放平台提供的API获取到阿里巴巴的会员、交易等数据，因为涉及数据隐私，所以在使用前必须获得阿里巴巴会员的授权，才可以调用API(公开数据除外)。 一、授权方式目前开放平台提供了三种授权方式：单用户授权，简单多用户授权，OAuth授权，具体内容如下： 1、单用户授权单用户授权意味着您的应用程序只能被一个阿里巴巴用户授权，适用于企业对接场景，企业只需要在1688上使用一个账号进行商品采购或者商品售卖。由于对账号数量限制太严，目前不再使用，企业对接场景请参考“多用户授权”。 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就要采用托管式授权方式。 托管式授权流程详解授权及使用授权时序图 授权流程 托管式授权是指将授权托管给应用市场，由应用市场发出授权请求的方式。 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签名规则 2、WEB端授权第三方开发者提供的app属于网页应用，但是不在应用市场售卖，可以自用或者自行售卖，用户直接在浏览器中输入app入口地址即可访问，那么这样的app就要采用WEB授权方式。 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签名规则 3、客户端授权第三方开发者提供的app属于客户端应用，用户需要下载应用到本地客户端才能使用，那么这样的app就要采用客户端授权方式。 客户端授权流程详解授权及使用授权时序图 授权流程 如果已经授权并且得到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_PARMa) client_id：app注册时，分配给app的唯一标示，又称appKey
b) site:site参数标识当前授权的站点，直接填写字符串"1688"
c) redirect_uri: 用户完成授权之后，回跳到第三方的地址
redirect_uri有三种方式，每种方式对应的code返回形式不同，isv可根据自己的情况选择
i. urn:ietf:wg:oauth:2.0:oob
Code以body的方式返回到默认的alibaba页面
ii. http://localhost:port
Code以queryString的方式返回到url，app需监听本地端口，接收code(windows系统会受到防火墙的干扰)
iii. https://auth.1688.com/auth/authCode.htm
Code以queryString的方式返回到该url
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签名规则 4、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接口时不需要签名 5、子账号授权流程详解子账号授权时仅仅依赖于主账号的授权，主账号授权成功才可以管理子账号的授权。下面针对三类应用分别说明子账号如何授权。 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?subUserIdentityList=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?subUserIdentityList=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?subUserIdentityList=a,b&access_token=ACCESS_TOKEN 正常返回结果类似{"returnValue":true,"success":true} 返回的主体内容是一个布尔值，标识取消授权是否成功，如果为false则需要重试。 异常返回结果类似{"errorCode":"xx","errorMessage":"xx","success":false} 3、应用工具APP暂不支持子账号授权管理，子账号授权逻辑跟以前一样，主账号授权后先到1688的子账号控制台给子账号分配使用权限，然后子账号就可以直接在服务市场或者work工作台使用有权限的应用，子账号会以主账号的名义使用第三方工具，所以ISV拿到的授权用户还是主账号，无法感知是子账号在使用。 |
