博瑞云音箱云喇叭开发文档API接口文档开发指南（21-12-20）

speaker_brhk

博瑞云音箱云喇叭自定义播报内容免费API接口

介绍
1.云喇叭是用来在网络程序开发中使用的设备，个人微信及支付宝收款不能使用。 2.需要有开发能力的人员才能使用，喇叭通过2G/4G/WIFI链接，通过GET/POST方式网络接口使喇叭播报收款提示。

安装教程
无需安装，使用GET POST 请求，即可直接调用

 

云音箱服务对接指南

  

 （流量版喇叭对接，可以只看3.1小节）

 

一、名词解释 (开发前必读)

 

1、云音箱 ID (SPEAKERID、sn)： 喇叭标签上的SN码

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

 

2、TOKEN (接口凭证)： 必须

程序调用接口控制音箱播报的凭证，预先联系客服申请分配，使得程序对该 SPEAKERID 有操控权限。只要设备授权给TOKEN，一个TOKEN可以控制无数个设备。

 

3、version（接口版本）：(非常重要)

由于喇叭硬件的变动，可能带来接口的变动，用此参数区分，要求开发者后台预留（1-9）个版本选项，喇叭机身的标签中，会注明对应的version

比如

型号	VERSION/接口版本	型号	VERSION/接口版本
210/310/330	1	402/404/502/504	3
204	2	901/902	9

二、接口 

 

1、通讯协议（作为了解）

 

1）接口网关：

https://speaker.17laimai.cn 

2）协议和端口号：

 HTTP 80，HTTPS 443  

3）请求方式：GET 或 POST (推荐使用POST,数据更安全) 

4）提交数据格式：

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

5）返回数据格式：JSON

参数	类型	说明	必须
errcode	integer	返回码	*
errmsg	string	返回码描述	*
detail	string	返回的数据

 

6）网关返回码

0	成功
1	未知错误
2	SPEAKERID 不存在
3	SPEAKERID 已经被其它用户 ID 绑定
4	SPEAKERID 已经被同一用户 ID 绑定
5	SPEAKERID 未被任何用户 ID 绑定
6	未提供 SPEAKERID
8	此 token 无此 SPEAKERID 权限
9	无效的 token
17	重复的请求

 

本文档接口表格中各列意义说明： 

·        “参数”列: 指提交 GET 或 POST 方式时带的参数名称字符串，编程时使用

·        “意义”列: 解释参数名称的意义，仅为了利于记忆，不是编程时的字符串 

·        “必须”列：带*号表示此参数是必须的，不能缺少

 

 

2、基础接口

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

 

2.1 云音箱绑定或解绑（WIFI版必用，流量版选用）

注意：310、330使用add播报方法时，必须先调用绑定方法进行绑定，其它型号可以不绑定；另外notify方法，全部型号可以不调用绑定方法，流量版推荐notify方法。

 

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

 

2）请求参数：

参数	意义	说明	必须
id	SPEAKERID	指该云音箱标签上的的 SN/ID	*
m	METHOD	0 为解绑， 1 为绑定, 4 强制解绑（不需提供原 USERID）	*
uid	USERID	开发者自定义，保持在你自己的系统程序内唯一即可,如：商家手机号	*
token	TOKEN	代理商的 token, 预先通过安全渠道分配，使得代理商对该 SPEAKERID 有操作权限	*
version	接口版本	按各型号标注的VERSION版本，由用户配置时选择，预留1-9供选择	*
seq	SEQUENCY	用 于通讯 去重复 的顺序号 ，范围 为 [0,4294967295] ( 即 [0,0xFFFFFFFF])的整数。每次提交时请改变此值（比如按顺序 加 1）。 假如服务器在 200 秒（暂定值）内收到两个或多个 SEQUENCY 相同、并且提交的内容也相同的请求，则认为是重复提交， 将忽略此请求，并返回错误码 17。 此参数缺省时，服务器对此次请求不做去重检查，此次请求 也不作为后续去重检查的比较依据。
descs	DESCRIPTION	代理商可以给此绑定请求提供一个描述字符串，最大 255 个 字节。之后代理商用 “ 绑定状态查询接口”查询绑定消息时， 可以看到此描述。 此参数对云音箱或服务器工作状态没有影响。

 

 

 

例子1：

https://speaker.17laimai.cn/bind.php?id=335&m=1&uid=AF337099&token=123456789021&version=1

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

 

例子2：

https://speaker.17laimai.cn/bind.php?id=335&m=0&uid=AF337099&token=123456789021&version=1

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

 

3) 返回参数：

参数	类型	说明	必须
errcode	integer	返回码，参见 网关返回码	*
errmsg	string	返回码描述	*
detail	string	返回的数据

 

 

2.2 支付语音播报（WIFI\流量版通用）

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

 注意：310、330使用此方法时，必须先调用绑定方法进行绑定，notify方法不需要，流量版推荐notify方法。

1）URL：https://speaker.17laimai.cn/add.php（WIFI版、流量版通用播报接口）

 

2）请求参数：

数：

参数	意义	解释	必须
id	SPEAKERID	指该云音箱标签上的的 SN/ID	*
uid	USERID	开发者自定义，保持在你自己的系统程序内唯一即可,如：商家手机号
price	PRICEVALUE	指支付金额值的字符串，单位为分，范围为 1 至 2147483647，即 1 分到 2 千多万。	*
pt	PRICE_TYPE	支付类型，此参数会让云音箱播放不同的提示语音 一个[0,255]的整形值，目前定义如下：
210WIFI版支持:1 支付宝 2 微信支付 3 云支付 4 余额支付 5 微信储值 6 微信买单 7 银联刷卡 8 会员卡消费9 会员卡充值10 翼支付11 退款 12 支付宝退款 13 微信退款 14 银行卡退款 15 银联退款 16 工行e支付 18 QQ钱包到账19 京东支付20 用户取消支付22 西银惠支付	（901、902）WIFI版支持且仅支持以下前缀1支付宝收款2微信收款3云闪付收款8会员卡消费9会员卡充值10翼支付收款成功11退款12支付宝退款13微信退款19京东收款成功20有用户取消订单	*
token	TOKEN	代理商的 token, 预先通过安全渠道分配，使得代理商对该 SPEAKERID 有操作权限	*
version	接口版本	按各型号标注的VERSION版本，由用户配置时选择，预留1-9供选择	*
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/add.php?id=335&price=3879&token=123456789021&version=1

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

 

3) 返回参数：

参数	类型	说明	必须
errcode	integer	返回码，参见 网关返回码	*
errmsg	string	返回码描述	*
detail	string	返回的数据

 

 

3、可选接口

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

3.1 通知语音播报（不支持WIFI版，流量版专用）

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

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

 

1）URL：https://speaker.17laimai.cn/notify.php （流量版专用播报接口，流量版可以只用到这一个接口，其它接口选用）

 

2）请求参数：

参数	意义	解释	必须
id	SPEAKERID	指该云音箱标签上的的 SN/ID	*
token	代理商的 token	代理商的 token, 预先通过安全渠道分配，使得代理商对该 SPEAKERID 有操作权限	*
version	接口版本	按各型号标注的VERSION版本，由用户配置时选择，预留1-9供选择	*
message	MESSAGE	通知消息内容，长度最长128个字节 数字处理策略见3.1.1备注如果需要断句，则添加逗号“,”	*
seq	SEQUENCY	用 于通讯 去重复 的顺序号 ，范围 为 [0,4294967295] ( 即 [0,0xFFFFFFFF])的整数。每次提交时请改变此值（比如按顺序 加 1）。 假如服务器在 200 秒（暂定值）内收到两个或多个 SEQUENCY 相同、并且提交的内容也相同的请求，则认为是重复提交， 将忽略此请求，并返回错误码 17。 此参数缺省时，服务器对此次请求不做去重检查，此次请求 也不作为后续去重检查的比较依据。
vol	VOLUME	指音量设置值，范围为 0 到 100，代表从无音到最大声。
speed	SPEED	语速，速度范围为0-100，默认为50 (仅限404、504)
trace_no	TRACE_ NUMBER	代理商用于追踪此支付消息的一个字符串，最大 63个字节，由代理商软件产生。之后代理商可以用此trace_no 通过用“支付消息历史查询接口”查询该条支付消息。此参数对云音箱或服务器工作状态没有影响。

例子1：https://speaker.17laimai.cn/notify.php?id=10000091&token=123456789021&version=1&message=你的验证码为6688 

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

 

例子1：https://speaker.17laimai.cn/notify.php?id=10000091&token=123456789021&version=1&message=支付宝到账120元,实收110元,星POS为你优惠10元 

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

3.1.1备注：数字处理策略 ，适用于编号播报，车牌播报等非金额格式的播报。

当message参数中，数字是按金额来播报的，比如“123”，播报为“一百二十三”，如果要按号码、编号来播报，则需要把特殊内容用“[”“]”方括号包裹起来，

比如：

1、订单编号[123]收款66元,则播报为“订单编号一二三收款六十六元”;

2、[津A8526]正常通行，则播报为“津A八五二六”正常通行

 

3) 返回参数：

参数	类型	说明	必须
errcode	integer	返回码，参见 网关返回码	*
errmsg	string	返回码描述	*
detail	string	返回的数据

3.2 更改语音信息 （灰度测试）

更改开机语音，自定义播报前缀。(仅适用于402、404、502、504)

 

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

    

2）请求参数：

---

参数	意义	解释	必须
id	SPEAKERID	云音箱的 ID	*
token	TOKEN	代理商的 token, 预先通过安全渠道分配，使得代理商对该 SPEAKERID 有操作权限	*
version	接口版本	按各型号标注的VERSION版本，预留1-9供用户配置音箱时选择	*
sound	开机铃声	声音内容中文最长15字其他字节30字节	*
off_text	关机铃声	中文，可选
type	TYPE	0 表示开机欢迎声音 传 off_text 时此值填写 1	*
seq	SEQUENCY	用 于通讯 去重复 的顺序号 ，范围 为 [0,4294967295] ( 即 [0,0xFFFFFFFF])的整数。每次提交时请改变此值（比如按顺序 加 1）。 假如服务器在 200 秒（暂定值）内收到两个或多个 SEQUENCY 相同、并且提交的内容也相同的请求，则认为是重复提交， 将忽略此请求，并返回错误码 17。 此参数缺省时，服务器对此次请求不做去重检查，此次请求 也不作为后续去重检查的比较依据。
descs	DESCRIPTION	代理商可以给此绑定请求提供一个描述字符串，最大 255 个 字节。之后代理商用 “ 绑定状态查询接口”查询绑定消息时， 可以看到此描述。 此参数对云音箱或服务器工作状态没有影响。

例子：https://speaker.17laimai.cn/modify_bootvoicewav.php?id=10000091&token=123456789021&sound=欢迎光临&off_text=谢谢使用&type=1   

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

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

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

3) 返回参数：

参数	类型	说明	必须
errcode	integer	返回码，参见 网关返回码	*
errmsg	string	返回码描述	*
detail	string	返回的数据

 

 

三、常见问题

1. 此token 无此 SPEAKERID 权限

1）：检查version,是否与当前设备型号对应正确，version(接口版本对应表)。

2）：检查TOKEN是否正确，是否完整

3）：联系我们，协助检查。