智能应用开放平台

APP

APP-所见即可说

意图&参数NLU透传

应用APK接入二维码支付收银台

轻服务

轻服务开发文档

1. 概述

普通用户在使用技能时，平台发送的请求数据中，仅包含此用户的天猫精灵账号和设备信息。如果技能的业务场景中需要知道此天猫精灵用户，在技能服务商的账号体系下是哪个用户时，就需要用到账号关联的授权配置了。

授权配置采用通用的 OAuth2.0 开放授权协议，可以让 AliGenie 在不获取合作方用户名和密码的前提下，访问用户授权的资源，协议规范可以访问 OAuth2.0 官方网站：https://oauth.net/2/

2. 鉴权流程

（1）开发者为 AliGenie 在自己的平台上开发一个授权服务，并分配相应的 Client id 和 Client secret；

（2）用户点击“账户绑定”，AliGenie 平台向开发者 OAuth2.0 授权服务发起一个授权请求，请求中包含用户授权成功的回调地址（redirect_uri）、client_id、state 等参数；

（3）开发者 OAuth2.0 授权服务响应回用户一个授权页面，用户可进行登陆授权；

（4）用户授权账号登录成功后，开发者授权服务回调 redirect_uri地址（需要先URL Decode，并且里面含的skillId、token 参数要原样返回，用来标识是哪个技能的哪个用户在进行账号授权，否则会报参数不完整错误）并带上 state（用于校验）、code（开发者授权服务生成的数据，后续平台会使用 code 去 Access Token URL 换取用户的 access_token）参数；

（5）AilGenie 平台收到开发者的授权成功回调后，携带 code 去访问 Access Token URL 服务换取该用户的access_token；

（6）如果用户在该技能下有 access_token，则用户在使用此技能时，平台发送的 webhook 请求数据中会额外携带token 字段，开发者根据 token 字段查询到此天猫精灵用户的关联账号是什么。

3. 运行流程

OAuth 2.0 的运行流程如下图

（A）用户打开客户端以后，客户端要求用户给予授权。

（B）用户同意给予客户端授权。

（C）客户端使用上一步获得的授权，向认证服务器申请令牌。

（D）认证服务器对客户端进行认证以后，确认无误，同意发放令牌。

（E）客户端使用令牌，向资源服务器申请获取资源。

（F）资源服务器确认令牌无误，同意向客户端开放资源。

4. AliGenie 智能应用平台 oauth 基础配置

账户授权链接：开发者提供的用户关联账号登录页面地址。需要是 https 协议的地址并且已经授信。

Client id 和 Client secret：开发者在授权服务中为 AliGenie 分配的客户端id和秘钥，AliGenie 平台在请求账户授权链接和 Access Token URL 时会携带这两个数据，开发者可以根据这两个数据做安全校验。这两个配置不允许内容相同。

跳转URL：用户授权账号登录成功后，开发者授权服务回调 AliGenie 平台的URL。请不要直接使用此URL，而是从账户授权链接的请求中获取 redirect_uri 进行 URL Decode。

Access Token URL：平台使用 code 换取 access_token 的地址。需要是 https 协议的地址并且已经授信，域名和账户授权链接必须一致。

5. 请求 API

(A) 用户打开授权链接进行授权

例：https://xxx.com/auth/authorize?redirect_uri=https%3A%2F%2Fopen.bot.tmall.com%2Foauth%2Fcallback%3FskillId%3D11111111%26token%3DXXXXXXXXXX&client_id=XXXXXXXXX&response_type=code&state=111

参数说明：

redirect_uri: AliGenie 平台的回调地址，该地址会加上 AliGenie 的参数进行 urlEncode,所以合作方务必做好参数返回的兼容性

client_id: 在合作方上注册的应用 Id

response_type: 响应方式为 code

state: 表示客户端的当前状态，开发者认证服务器需要原封不动地返回这个值。

注：示例中的链接 API (https://xxx.com/auth/authorize) 为开放平台中的账户授权链接字段。

(B) 通过 code 换取合作方访问令牌

例：

https://XXXXX/token?grant_type=authorization_code&client_id=XXXXX&client_secret=XXXXXX&code=XXXXXXXX&redirect_uri=https%3A%2F%2Fopen.bot.tmall.com%2Foauth%2Fcallback

请求方法： POST

参数说明：

client_id: 在合厂商平台上注册的应用 Id

grant_type: 授权类型 authorization_code

client_secret: 在厂商平台上注册应用的 secret

code: 授权登陆后回调 AliGenie 的地址返回的 code

redirect_uri: AliGenie 回调地址

注：示例中的链接 API ( https://XXXXX/token) 为开放平台中的 Access Token Url 字段。2018年1月4日之后，创建的技能通过 body 来传参。

通过 code 换取 access_token 响应结构如下(响应格式 application/json)：

字段	类型	解释说明
access_token	String	访问token（响应正确时必传递）
refresh_token	String	进行刷新access_token的刷新token （响应正确时必传递）
expires_in	long	过期时间时长（响应正确时必传递）
error	String	错误响应码（响应错误时必传递）
error_description	String	错误详情（响应错误时必传递）

正常响应：

{
  "access_token": "XXXXXX",
  "refresh_token": "XXXXXX"，
  "expires_in":17600000
  }

错误响应:

{
  "error":"errorCode",
  "error_description":"description"
 }

注： access_token 有效期请设置成 1 天以上(2-3天最佳)

例：

https://XXXXX/token?grant_type=refresh_token&client_id=XXXXX&client_secret=XXXXXX&refresh_token=XXXXXX

请求方法： POST

参数说明：
  grant_type：更新access_token的授权方式为refresh_token
  client_id: 在厂商平台上注册的应用Id
  client_secret:在厂商平台上注册应用的secret
  refresh_token: 上一次授权获取的refresh_token

注：示例中的链接API( https://XXXXX/token) 为开放平台中的Access Token Url 字段。

更新 access_token 响应结构如下(响应格式 application/json)：

字段	类型	解释说明
access_token	String	访问token（响应正确时必传递）
refresh_token	String	进行刷新access_token的刷新token （响应正确时必传递）
expires_in	long	过期时间时长（响应正确时必传递）
error	String	错误响应码（响应错误时必传递）
error_description	String	错误详情（响应错误时必传递）

正常响应：

{
  "access_token": "XXXXXX",
  "refresh_token": "XXXXXX"，
  "expires_in":17600000
  }

错误响应:

{
  "error":"errorCode",
  "error_description":"description"
 }

注意事项：

获取 access_token 或者刷新 access_token 出现错误情况时 http response status code 请返回 200 ，接入方的内部异常请接入方自行包装异常信息