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)接口网关:
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 |
|
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):联系我们,协助检查。