扫码授权接口联调文档

1，授权接口通过淘宝开放平台（简称 TOP平台 ）对外开放，淘宝开放平台提供的接口简称 TOP接口 。以下为TOP平台介绍文档：https://open.taobao.com/doc.htm?docId=73&docType=1
2，阅读SDK使用文档
https://open.taobao.com/doc.htm?docId=103376&docType=1
3，阅读天猫精灵通用授权文档
https://open.taobao.com/api.htm?docId=44760&docType=2&scopeId=16667

扫码授权架构

扫码授权分为以下组件：
1，天猫精灵客户端，负责调用getCode接口获取二维码、展示二维码，然后轮询授权结果
2，天猫精灵通用授权服务，提供通用授权相关TOP接口
3，天猫精灵APP，提供扫码授权功能，需要下载最新版APP（3.19以上），点击APP右上角的扫码按钮扫二维码授权
4，TVS服务，授权成功后使用获取的accessToken访问TVS服务

扫码授权时序图

下面是完整的扫码授权步骤。

1，APPKEY授权

提供appkey给阿里进行接口授权（线下流程）。授权完成之后在淘宝开放平台控制台能看到appkey获取到的权限包，此时应该包括下面的权限包：

2，注册设备device_id

备注：如是一型一密请忽略此步骤,直接查看第三步。

1，注册设备SN或MAC

登陆 AliGenie开发者平台 , 点击 我的产品设备 ，会出现如下图的下拉框，请点击 MAC/SN管理 。
根据你实际情况选择MAC或SN，上传你的设备MAC或SN列表文档。

2，申请一机一密信息，并下载设备密钥文档

进入 产品管理->配置->测试验证/发布管理 ，审批通过后你就可以下载生成的设备密钥文档。
注:申请 发布管理 中的量产认证后就无法申请 测试验证 中的认证了

如有下图这样的提示，请至 开放管理中 根据实际清空完善信息

如有下图这样的提示,请至 语音接入->特色问答定制 中补全信息

文档内容：
Product ID是产品ID
Device Secret是一机一密的密钥
SN地址是三方设备DeviceId
Md5值此字段可忽略

3，调用getCode（获取授权码）接口，获取授权码

1，下载sdk

sdk下载见文档：https://open.taobao.com/doc.htm?docId=101618&docType=1

2，计算设备签名

以下设备签名算法阿里线下提供封装好的java sdk，其他语言的签名需要自己实现
一机一密【硬】与一型一密签名方式有所不同

一机一密【硬】

算法中AES密钥AES1, AES2可以在设备信息中获取

签名算法：
a，获取AES密钥AES1, AES2, AES采用AES128/CBC/NoPading,每个秘钥包含了IV和秘钥本身；
b，获取一机一密密钥secret（就是上图获取的密钥）；
d，用一机一密密钥secret计算签名密钥final_secret,计算方式如下
final_secret = AES2_encode(Base64Utils.decode(AES1_decode(secret)).subString(32))
e，用签名密钥final_secret计算签名device_signature，计算方式如下
stringBody = clientId_deviceId_timestamp
device_signature = toHexString(hmacSHA256Encrypt(stringBody,final_secret))

一型一密

根据如图所示下载产品配置文件，获取dev_secret
签名算法：
stringBody = clientId_deviceId_timestamp
device_signature = toHexString(hmacSHA256Encrypt(stringBody,dev_secret))

最终签名结果是一个json字符串，包含timestamp以及deviceSignature，此json串作为第3步device_signature的入参

{\"deviceSignature\":\"d6c9a3468b202\",\"timestamp\":1565250383}

3，调用getCode获取设备注册码

备注：如报错，请联系tvs开发人员。
接口文档如下：
https://open.taobao.com/api.htm?docId=44924&docType=2≻opeId=16667

核心输入参数：
设备标识符clientId
三方设备iddevice_id
设备签名device_signature，传入第二步生成的JSON串

核心输出参数：
code是授权码，用于扫码授权后调用getToken流程。
qrcode是一个JSON串，用于后面的扫码授权流程。

{\"code\":\"codeXS\",\"qrcode\":\"https://app-aicloud.alibaba.com/download?clientId=XXX&authCode=XXX&api=XXX\"}

解析后结构如下：

{
	"code": "codeXS",
	"qrcode": "https://app-aicloud.alibaba.com/download?clientId=XXX&authCode=XXX&api=XXX"
}

code用于轮询授权结果，qrcode用于生成二维码，细节见后面的步骤。

4，用天猫精灵app扫码，完成用户授权

1，获取 联调用天猫精灵app （线下流程），然后登录天猫精灵app。
2，将第四步中获取到的qrcode生成为二维码，可以使用在线工具直接生成：http://tool.oschina.net/qr。
2，使用app扫码，如果提示操作成功，则完成了用户授权。

5，调用getToken接口获取授权结果

1，调用getToken接口：
接口文档：https://open.taobao.com/api.htm?docId=44921&docType=2&scopeId=16667
核心入参：
auth_code 对应第四步中获取到的code；
核心出参：
acces_token accessToken，用户访问天猫精灵云端语音服务。
user_open_id 天猫精灵用户开放id，对应的天猫精灵用户的id。
uuid 天猫精灵设备id。

6，访问TVS云端服务

1，TVS1.0
参考以下文档：https://doc-bot.tmall.com/docs/doc.htm?spm=0.7629140.0.0.43891780UsHOEb&treeId=566&articleId=118042&docType=1
文档中提到的token用第5步获取的accessToken就可以了，如果能正常访问TVS服务，说明扫码授权联调成功。

7，更多接口

访问以下接口，完成token刷新以及设备查询，具体信息见接口文档
刷新token
设备列表
设备详情
设备解绑

产品化

以上扫码授权流程产品化还需要：
1，getCode获取的authCode超时时间为30分钟，三方设备需要定时获取新的authCode；
2，三方设备需要在展示二维码后轮询getToken接口，获取授权结果，建议间隔2s轮询一次（一次调用完成后2s后再发起轮询）
3，建议三方设备在展示二维码并轮询getToken接口时,设置一个3~5分钟的超时机制

FAQ

关于此文档暂时还没有FAQ