云音箱服务对接指南
（流量版喇叭对接，可以只看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）：联系我们，协助检查。
【备注云喇叭】
