云音箱服务对接指南

一、名词解释

1、云音箱 ID (SPEAKERID)：

云音箱机身上帖有云音箱的 ID 码，每台云音箱拥有唯一永久 ID，SPEAKERID由字母、数字组成，在生产过程中写入云音箱，云音箱出厂后不会再改变。

2、TOKEN:

厂商分配给每个代理商的唯一 token, 通过安全渠道提供给代理商，使得代理商对它购买的SPEAKERID 有操作权限。若报文中提交的token错误或token无权操作报文中提交的SPEAKERID，服务器会返回错误。

token是一个长度为12字节的字符串，包含数字和英文字母，区分大小写。基于安全角度，token可能会不定期更新，厂商会提前通知代理商。

例如：厂商给某个代理的 token 是 105827801114，并向其销售了 speakerid 为 1000 到 1999 的一千个云音箱，则该代理用 105827801114这个 token 能且仅能操作 speakerid 为 1000 到 1999 的云音箱。其它代理由于不知道这个 token，无法操作这一千个云音箱。

3、代理商 ID (AGENCYID):

token 的前 4 位即为 AGENCYID，每个代理商唯一。是一个 1000 到 9999 的数值。例如，某代理商的 token 为 105827801114，即此代理商的 AGENCYID 为 1058。

4、用户ID (USERID)：

代理商会给每位云音箱使用人分配一个唯一的帐号，这个帐号会有相关联的支付服务商下商户账号，用来接收相应的收款消息。一个用户帐号可以绑定多个云音箱，目前暂定单个用户最多可以绑定的有效喇叭数为 300 个。这个 USERID 是字符串，长度最大 255 字节，可使用英文字母和数字和下划线，区分大小写。例如: 某个饭店商户在代理商注册了个帐户叫“张三”，为避免重复，并且为了使用字母和数字，代理商分配给他的帐号名为”zhang3_2017”，于是代理商可以用”zhang3_2017”来绑定例如 ID 为 1090 的云音箱，并且代理商用”zhang3_2017”来提交支付消息，服务器会将此支付消息推送到 ID 为 1090 的云音箱。

二、接口

1、通讯协议

1）接口地址：https://speaker.17laimai.cn

2）协议和端口号： HTTP 80，HTTPS 443

3）请求方式：GET 或 POST

4）提交数据格式：

id=SPEAKERID&uid=USERID&price=PRICEVALUE&token=TOKEN

5）返回数据格式：JSON

2、基础接口

基础接口为云音箱正常工作的必备接口，代理商必须实现

2.1 云音箱绑定或解绑

最终用户在手机专用客户端（或网页）上输入（或扫描）云收款 ID，提交到云音箱服务器，服务器的数据表将此用户帐号与云音箱 ID 作关联。出于安全考虑，代理商在将账号与云音箱 ID 作绑定前，要确认操作人是该云音箱的拥有者。比如，用户在申请绑定时，代理商提交一条随机支付消息到该云音箱，用户收听播报价格后输入给代理商，代理商确认用户输入的数字与提交的数字相同，即可验证。原理类似于手机验证码。出于安全考虑，已经绑定过帐号的云音箱 ID 不允许更改绑定到其它帐号，除非原帐户人申请解绑此云音箱。

1）URL: https://speaker.17laimai.cn/b...

2）请求参数：

例子1：

https://speaker.17laimai.cn/b...

表示申请将用户 ID AF337099 与云音箱 335 绑定

例子2：

https://speaker.17laimai.cn/b...

表示申请将用户 ID AF337099 与云音箱 335 解除绑定

3) 返回参数：

2.2 支付语音播报

将支付结果提交到云音箱服务器、服务器将支付结果推送给云音箱，云音箱接收后播报。

1）URL：https://speaker.17laimai.cn/a...

2）请求参数：

参数

意义

解释

必须

SPEAKERID

指该云音箱的 ID

uid

USERID

用户帐号 ID，申请与云音箱 ID 绑定的用户帐号 ID，必须每个用户唯一

price

PRICEVALUE

指支付金额值的字符串，单位为分，范围为 1 至
2147483647，即 1 分到 2 千多万。

PRICE_TYPE

支付类型，此参数会让云音箱播放不同的提示语音
一个[0,255]的整形值，目前定义如下：
1 支付宝

2 微信支付

3 云支付

4 余额支付

5 微信储值

6 微信买单

7 银联刷卡

8 会员卡消费

9 会员卡充值

10 翼支付

11 退款

12 支付宝退款

13 微信退款

14 银行卡退款

15 银联退款

16 工行e支付

18 QQ钱包到账

19 京东支付

20 用户取消支付

22 西银惠支付

token

TOKEN

代理商的 token, 预先通过安全渠道分配，使得代理商对该 SPEAKERID 有操作权限

vol

VOLUME

指音量设置值，范围为 0 到 100，代表从无音到最大声。

seq

SEQUENCY

用于通讯去重复的顺序号，范围为[0,4294967295] (即[0,0xFFFFFFFF])的整数。每次提交时请改变此值（比如按顺序加 1）。
假如服务器在 200 秒（暂定值）内收到两个或多个SEQUENCY 相同、并且提交的内容也相同的请求，则认为是重复提交，服务器将忽略此提交，并返回错误码 17。此参数缺省时，服务器对此次请求不做去重检查，此次请求也不作为后续去重检查的比较依据。

trace_no

TRACE_
NUMBER

代理商用于追踪此支付消息的一个字符串，最大 63个字节，由代理商软件产生。之后代理商可以用此trace_no 通过用“支付消息历史查询接口”查询该条支付消息。此参数对云音箱或服务器工作状态没有影响。

descs

DESCRIPTION

代理商可以给此支付消息一个描述字符串，最大 255个字节。之后代理商用 “支付消息历史查询接口”查询支付消息时，可以看到此描述。此参数对云音箱或服务器工作状态没有影响。

suffix

VOLUMESUFFIX

是否开启自定义收款消息后缀， 1表示开启

备注：

云音箱收到支付结果后，播放内容为：支付类型 + 金额 + 后缀，后缀和前缀可以通过“更改语音信息”接口修改

例子：

https://speaker.17laimai.cn/a...

表示代理商的 token 为 105827801114，向 id 为 335 的云音箱提交支付金额为 38.79 元的支付结果

3) 返回参数：

参数

类型

说明

必须

errcode

integer

返回码，参见网关返回码

errmsg

string

返回码描述

detail

string

返回的数据

3、可选接口

代理商可根据情况实现可选接口，可选接口不影响云音箱的正常使用。

3.1 通知语音播报

将通知消息提交到云音箱服务器、服务器将支付结果推送给云音箱，云音箱接收后播报。

备注：该接口为2G版音箱专用接口，通过2G版音箱自带的TTS播放，WIFI版音箱不可用

1）URL：https://speaker.17laimai.cn/n...

2）请求参数：

参数

意义

解释

必须

SPEAKERID

云音箱的 ID

token

代理商的 token

代理商的 token, 预先通过安全渠道分配，使得代理商对该SPEAKERID 有操作权限

message

MESSAGE

通知消息内容，长度最长128个字节

seq

SEQUENCY

用于通讯去重复的顺序号，范围为 [0,4294967295] ( 即
[0,0xFFFFFFFF])的整数。每次提交时请改变此值（比如按顺序
加 1）。
假如服务器在 200 秒（暂定值）内收到两个或多个 SEQUENCY相同、并且提交的内容也相同的请求，则认为是重复提交，
将忽略此请求，并返回错误码 17。
此参数缺省时，服务器对此次请求不做去重检查，此次请求
也不作为后续去重检查的比较依据。

vol

VOLUME

指音量设置值，范围为 0 到 100，代表从无音到最大声。

speed

SPEED

语速，速度范围为0-100，默认为65

trace_no

TRACE_
NUMBER

例子1：
https://speaker.17laimai.cn/n...

ID为10000091的云音箱播报语音 “你的验证码为6688”

例子1：
https://speaker.17laimai.cn/n...

ID为10000091的云音箱播报语音 “支付宝到账120元,实收110元,星POS为你优惠10元”

3) 返回参数：

参数

类型

说明

必须

errcode

integer

返回码，参见网关返回码

errmsg

string

返回码描述

detail

string

返回的数据

3.2 更改语音信息

更改开机语音，自定义播报前缀，播报后缀。

1）URL：https://speaker.17laimai.cn/m..._bootvoice.php

2）请求参数：

参数

意义

解释

必须

SPEAKERID

云音箱的 ID

token

TOKEN

代理商的 token, 预先通过安全渠道分配，使得代理商对该SPEAKERID 有操作权限

sound

SOUNDCOTENT

声音内容

中文最长15字

其他字节30字节

type

TYPE

类型

0 表示开机欢迎声音

1 支付信息播报前缀

2 支付信息播报后缀

seq

SEQUENCY

descs

DESCRIPTION

代理商可以给此绑定请求提供一个描述字符串，最大 255 个
字节。之后代理商用 “ 绑定状态查询接口”查询绑定消息时，
可以看到此描述。
此参数对云音箱或服务器工作状态没有影响。

例子：
https://speaker.17laimai.cn/m..._bootvoice.php?id=10000091&token=105827801114&sound=欢迎光临&type=0

表示将云喇叭 ID 10000091 开机语音设置为 “欢迎光临”

3) 返回参数：

参数

类型

说明

必须

errcode

integer

返回码，参见网关返回码

errmsg

string

返回码描述

detail

string

返回的数据

3.3 云音箱绑定状态查询

查询某些（或某个）云音箱 ID，或者某个用户帐号的绑定情况。

1) URL： https://speaker.17laimai.cn/list_bind.php

2) 请求参数：

参数

意义

解释

必须

ids

START_SPEAKERID

查询方式

方式一

云音箱的起始 ID，如果为空，表示不限制起始 ID

ide

END_SPEAKERID

云音箱的结束 ID，如果为空，表示不限制结束 ID

SPEAKERID

方式二

云音箱的 ID可以是单个喇叭 ID，也可以是范围或枚举。范围以减号连接，包含两头值；枚举以逗号分隔。
例如:
1000,1005,1008-1011,1015
表示喇叭 ID 为:
1000,1005,1008,1009,1010,1011,101

uid

USERID

方式三

用户帐号 ID，申请与云音箱 ID 绑定的用户帐号 ID，必须每个用户唯一

START_TIME

查询条件

指只查询这个时间或这个时间之后的记录，时间格式如下：一段 14 字节的字符串 , 格式为
YYYYMMDDHHmmss其中四字节年，两字节月份，两字节日，两字节小时(24 小时制)，两字节分钟，两字节秒

例如： 20170927173500 表示2017 年 9 月 27 日 17 时 35 分零秒此参数如果缺省，表示不限制起始时间。

END_TIME

指只查询这个时间或这个时间之前的记录，时间格式同上。此参数如果缺省，表示不限制结束时间。

descs

DESCRIPTION

查询代理绑定消息时提交的 DESC 标识。目前暂不提供%的模糊查询

FORMAT

返回格式

指定数据返回格式， 0 为内部调试用的 Html 表格格式， 1 为纯文本， 2为 Microsoft Excel 的.csv， 3 为 json；缺省时为 3

PAGE

显示分页

输出的页号，整数值，从 0 开始。为了防止每次返回数据太多造成服务器超时，服务器每次只返回PAGESIZE 条(缺省为 200)记录。p=0 时表示返回最开头的 200 条，即第 0 条到第 199 条。p=1 表示返回第 200 到第 399 条。以此类推。当用户查询到 p=n 时返回记录数为零，说明可以停止继续查询后续页。此参数缺省值为 0。此参数当 m=0 时无效，因为 html 表格已经自动分页。

PAGEITEM

指定当前显示页是从第几条结果开始显示。
例如 pi=350，表示当前页是从第 350条结果开始。
此参数缺省值为 0。此参数不要与 PAGE 同时用，否则会
忽略 PAGE 参数。例如，当 PAGESIZE 为 200 时， PAGE为 2 与 PAGEITEM 为 400 的效果与等同。此参数当 m=0 时无效，因为 html 表格已经自动分页。

PAGESIZE

每页显示的结果条数。缺省为 200。此参数当 m=0 时无效，因为 html 表格已经自动分页。

token

TOKEN

代理商的 token

代理商的 token, 预先通过安全渠道分配，使得代理商对该 SPEAKERID 有操作权限

例子1：

https://speaker.17laimai.cn/list_bind.php?ids=1000&ide=1030&uid=wangxi2017&token=105827801114

表示查询云音箱范围为 1000 到 1030 并且用户 ID 为 wangxi2017 的绑定记录

例子2:

https://speaker.17laimai.cn/list_bind.php?fm=0&id=1000&token=105827801114

表示查询云音箱 ID 1000 的绑定记录

3) 返回参数：

参数

类型

说明

必须

errcode

integer

返回码，参见网关返回码

errmsg

string

返回码描述

detail

string

返回的数据

detail 说明：

1)结果表中的 userid, 前 4 位为代理商 ID (AGENCYID)，第 6 位开始才是真实用户 ID。（这是为了保证不同代理商用相同用户 ID 时，用户 ID 在表中是唯一的）例如: userid 1000_wangxi2007, 其真实用户 id 为 wangxi2007结果表中 real_userid 是真实用户 id

2)结果表中 active, 值 1 表示绑定是有效状态，值 0 表示以前绑定过但是后来已经解绑了。

3.4 查询云音响操作权限

代理商查询其对哪些喇叭有操作权

1）URL：https://speaker.17laimai.cn/list_speakeragency.php

2）请求参数：

参数

意义

解释

必须

ids

START_SPEAKERID

查询方式

方式一

云音箱的起始 ID，如果为空，表示不限制起始 ID

ide

END_SPEAKERID

云音箱的结束 ID，如果为空，表示不限制结束 ID

SPEAKERID

方式二

uid

USERID

方式三

用户帐号 ID，申请与云音箱 ID 绑定的用户帐号 ID，必须每个用户唯一

START_TIME

查询条件

例如： 20170927173500 表示2017 年 9 月 27 日 17 时 35 分零秒此参数如果缺省，表示不限制起始时间。

END_TIME

指只查询这个时间或这个时间之前的记录，时间格式同上。此参数如果缺省，表示不限制结束时间。

descs

DESCRIPTION

查询代理绑定消息时提交的 DESC 标识。目前暂不提供%的模糊查询

FORMAT

返回格式

指定数据返回格式， 0 为内部调试用的 Html 表格格式， 1 为纯文本， 2为 Microsoft Excel 的.csv， 3 为 json；缺省时为 3

PAGE

显示分页

PAGEITEM

PAGESIZE

每页显示的结果条数。缺省为 200。此参数当 m=0 时无效，因为 html 表格已经自动分页。

token

TOKEN

代理商的 token

代理商的 token, 预先通过安全渠道分配，使得代理商对该 SPEAKERID 有操作权限

例子1：

https://speaker.17laimai.cn/list_speakeragency.php?ids=1000&ide=1500token=105827801114

查询ID范围从1000 到 1500 云音箱是否有权限

例子2:

https://speaker.17laimai.cn/list_bind.php?fm=0&id=1000&token=105827801114

表示查询云音箱 ID 1000 是否有权限

3) 返回参数：

参数

类型

说明

必须

errcode

integer

返回码，参见网关返回码

errmsg

string

返回码描述

detail

string

返回的数据

detail 说明：

{"total_count":1,"list_count":1,"records":{"0":{"ID":"649138","datetime":"2017-11-2820:37:57","speakerid":"1432","agencyid":"1004","active":"1","descs":null}}}

1) 结果表中的 speakerid, 即表示该代理商有权限的喇叭。

2)结果表中 active, 值 1 表示是有效状态，值 0 表示以前分配过但是后来已经被工厂删除权限了。

3.5 查询第一条未播放语音

代理商向服务器提交支付消息后，假如云音箱未取走这些支付消息，将会按时间先后存在服务器虚拟队列中。代理商可用这个接口查询这个队列中最早的一条未被取走的支付消息。例如，代理商向服务器提交云音箱 ID 为 335 的支付消息，先后四次提交分别为 1.35元， 3.77 元， 6.78 元， 4.66 元。而云音箱取走了 1.35 元这条消息。那么代理商用这个接口查询的结果是 3.77 元。等到云音箱又先后取走了 3.77 元、 6.78 元这两条消息，那么这个接口的查询结果将为 4.66 元。如果要查询详细支付消息历史，请使用后文的支付消息历史查询接口。同时，这个接口也可以查询当前音量值设置值，音量值是最后一次提交的设置值，与是否被云音箱取走无关。

1）URL：https://speaker.17laimai.cn/get_last.php

2）请求参数:

参数

意义

解释

必须

SPEAKERID

指该云音箱的 ID

token

TOKEN

代理商的 token

例子：

https://speaker.17laimai.cn/get_last.php?id=10000091&token=105827801114

查询 ID 为 3998 的云音箱的支付消息和音量。

3) 返回参数：

参数

类型

说明

必须

errcode

integer

返回码，参见网关返回码

errmsg

string

返回码描述

detail

string

返回的数据

detail 说明：
若无错误，并且此 ID 有新支付消息，服务器应该回复如下文本字符串：{"price":支付金额,"volume":音量,"price_type":支付类型}其中:支付金额: 一个表示整数的字符串，单位为分，范围为 1 至 2147483647，即 1 分到 2 千多万。音量: 一个表示整数的字符串，范围为 0-100。（出于用户体验考虑，建议只回复40-100 的值，否则音量太小可能会听不清）金额和音量之间的分隔号是半角英文逗号”,”例如：{"price":3877,"volume":80,"price_type":0 } 表示支付金额 38.77 元，支付类型为通用类，当前音量为 80%，。2. 若无错误，但此 ID 没有新支付消息，服务器应该回复如下文本字符串：{"price":0,"volume":音量,"price_type":0}例如:
{"price":0,"volume":70,"price_type":0} 表示未有新支付消息，当前音量为 70%

3.6 查询历史支付消息

查询提交过的历史支付结果消息。

1）URL：https://speaker.17laimai.cn/l...

2）请求参数

参数

意义

解释

必须

ids

START_SPEAKERID

查询方式

方式一

云音箱的起始 ID，如果为空，表示不限制起始 ID

ide

END_SPEAKERID

云音箱的结束 ID，如果为空，表示不限制结束 ID

SPEAKERID

方式二

uid

USERID

方式三

用户帐号 ID，申请与云音箱 ID 绑定的用户帐号 ID，必须每个用户唯一

START_TIME

查询条件

例如： 20170927173500 表示2017 年 9 月 27 日 17 时 35 分零秒此参数如果缺省，表示不限制起始时间。

END_TIME

指只查询这个时间或这个时间之前的记录，时间格式同上。此参数如果缺省，表示不限制结束时间。

descs

DESCRIPTION

查询代理绑定消息时提交的 DESC 标识。目前暂不提供%的模糊查询

FORMAT

返回格式

指定数据返回格式， 0 为内部调试用的 Html 表格格式， 1 为纯文本， 2为 Microsoft Excel 的.csv， 3 为 json；缺省时为 3

PAGE

显示分页

PAGEITEM

PAGESIZE

每页显示的结果条数。缺省为 200。此参数当 m=0 时无效，因为 html 表格已经自动分页。

token

TOKEN

代理商的 token

代理商的 token, 预先通过安全渠道分配，使得代理商对该 SPEAKERID 有操作权限

例子：

https://speaker.17laimai.cn/l...

查询喇叭 ID 为 335,336,337,338，在 2017-09-27 当天的记录，开头 200 条，返回纯文本格式

3) 返回参数：

参数

类型

说明

必须

errcode

integer

返回码，参见网关返回码

errmsg

string

返回码描述

detail

string

返回的数据

detail 说明：

查询后，云服务器回复的内容是该云音箱的历史消息列表。

智能云喇叭收款云音箱云喇叭API接口开发文档

云音箱服务对接指南

一、名词解释

二、接口

1、通讯协议

2、基础接口

2.1 云音箱绑定或解绑

2.2 支付语音播报

3、可选接口

3.1 通知语音播报

3.2 更改语音信息

3.3 云音箱绑定状态查询

3.4 查询云音响操作权限

3.5 查询第一条未播放语音

3.6 查询历史支付消息

你可能感兴趣的:(物联网,智能硬件,api)