# 博瑞云音箱云喇叭API对接文档

**Repository Path**: ma-xiaofeng520/speaker-brhk

## Basic Information

- **Project Name**: 博瑞云音箱云喇叭API对接文档
- **Description**: 免费API接口，支持GET\POST，自定义播报内容，博瑞云音箱云喇叭，收款播报，点餐播报，叫号播报，适应各种场景播报。

1.云喇叭是用来在网络程序开发中使用的设备，个人微信及支付宝收款不能使用。
2.需要有开发能力的人员才能使用，喇叭通过2G/4G/WIFI链接，通过GET/POST方式网络接口使喇叭播报收款提示。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://www.yuque.com/docs/share/a2617233-7d39-4bda-8b77-f398420bd5bc?# 《收款云音箱云喇叭API开发接口文档（2021-10-7）》
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-10-23
- **Last Updated**: 2025-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



![输入图片说明](564654.png)

# 云音箱服务对接指南
  
 [（流量版喇叭对接，可以只看3.1小节）](#31_WIFI_182)
 
# 一、名词解释 (开发前必读)
 
### 1、云音箱 ID (SPEAKERID、sn)： 喇叭标签上的SN码
云音箱机身上帖有云音箱的 ID 码，每台云音箱拥有唯一永久 ID，SPEAKERID由字母、数字组成， 在生产过程中写入云音箱，云音箱出厂后不会再改变。 
 
### 2、TOKEN (接口凭证)： 必须
2.1、程序调用接口控制音箱播报的凭证，预先**联系客服**申请分配，使得程序对该  SPEAKERID 有操控权限。只要设备授权给TOKEN，一个TOKEN可以控制无数个设备。
******2.2、TOKEN涉及设备的操作权限，推荐内置在程序内部，做为常量。不要轻易泄露。
 
### 3、version（接口版本）：(非常重要)
**由于喇叭硬件的变动，可能带来接口的变动，用此参数区分，要求开发者后台预留（1-9）个版本选项，喇叭机身的标签中，会注明对应的version**
**比如 **
![输入图片说明](version.png)

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

# 二、接口 
 
## 1、通讯协议（作为了解）
 
#### 1）接口网关：
[https://speaker.17laimai.cn](https://speaker.17laimai.cn) 
#### 2）协议和端口号：
 HTTP 80，**HTTPS 443**  
#### 3）请求方式：GET 或 POST (推荐使用POST,数据更安全) 
#### 4) 内容类型 contentType：支持大多数类型

####    application/json 或者 application/x-www-form-urlencoded 或者 multipart/form-data

#### 5）提交数据格式：
```
id=SPEAKERID&uid=USERID&price=PRICEVALUE&token=TOKEN&version=VERSION
```
#### 6）返回数据格式：JSON
| 参数 | 类型 | 说明  | 必须 |
| --- | --- | --- | --- |
| errcode | integer | 返回码 | * |
| errmsg | string | 返回码描述  | * |
| detail | string | 返回的数据 |   |

 
#### 7）网关返回码
| 0  | 成功 |
| --- | --- |
| 1  | 未知错误 |
| 2  | SPEAKERID 不存在 |
| 3  | SPEAKERID 已经被其它用户 ID 绑定 |
| 4  | SPEAKERID 已经被同一用户 ID 绑定 |
| 5  | SPEAKERID 未被任何用户 ID 绑定 |
| 6  | 未提供 SPEAKERID |
| 8  | 此 token 无此 SPEAKERID 权限，检查VERSION 、检查音箱ID、检查TOKEN |
| 9  | 无效的 token |
| 17  | 重复的请求 |

 
本文档接口表格中各列意义说明： 
·        “参数”列: 指提交 GET 或 POST 方式时带的参数名称字符串，编程时使用
·        “意义”列: 解释参数名称的意义，仅为了利于记忆，不是编程时的字符串 
·        “必须”列：带*号表示此参数是必须的，不能缺少
 
 
## 2、基础播报接口
基础接口为云音箱正常工作的必备接口 

 
### 2.2 支付语音播报（WIFI\流量版通用）
将支付结果提交到云音箱服务器、服务器将支付结果推送给云音箱，云音箱接收后播报。
** 注意：310、330使用此方法时，必须先调用绑定方法进行绑定，notify方法不需要，流量版推荐notify方法。**
**1）URL：**[**https://speaker.17laimai.cn/add.php**](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]的整形值，【传'0'则不播报前缀】目前定义如下：   ** 210WIFI版支持**  :  1支付宝  2微信支付  3云支付  4余额支付  5微信储值  6微信买单  7银联刷卡  8会员卡消费  9会员卡充值  10翼支付  11退款  12支付宝退款  13微信退款   14银行卡退款  15银联退款  16工行e支付  18QQ钱包到账  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  | 订单号|一个字符串，最大 63个字节，由软件端自定义产生。此参数对云音箱或服务器工作状态没有影响。| * |
| descs  | DESCRIPTION  | 代理商可以给此支付消息一个描述字符串，最大 255个字节。此参数对云音箱或服务器工作状态没有影响。 |  |


备注：
云音箱收到支付结果后，播放内容为：支付类型 + 金额 
 
例子：
```
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 | 返回的数据 |   |

 
### 2.2 通知语音播报（不支持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 | 播报内容 | 通知消息内容，长度最长128个字节 数字处理策略见[3.1.1备注](#31_WIFI_182)如果需要断句，则添加逗号“,” | * |
| seq  | SEQUENCY  | 用 于通讯 去重复 的顺序号 ，范围 为 [0,4294967295] ( 即  [0,0xFFFFFFFF])的整数。每次提交时请改变此值（比如按顺序  加 1）。  假如服务器在 200 秒（暂定值）内收到两个或多个 SEQUENCY相同、并且提交的内容也相同的请求，则认为是重复提交，  将忽略此请求，并返回错误码 17。  此参数缺省时，服务器对此次请求不做去重检查，此次请求  也不作为后续去重检查的比较依据。| |
| vol  | 音量  | 指音量设置值，范围为 0 到 100，代表从无音到最大声。 (**弃用**)   |   |
| speed | 语速 | 语速，速度范围为0-100，默认为50 (**弃用**) |   |
| trace_no  | 订单号| 一个字符串，最大 63个字节，由软件端自定义产生。此参数对云音箱或服务器工作状态没有影响。 |   |

```
例子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元,为你优惠10元 
```
ID为10000091的云音箱播报语音 “支付宝到账120元,实收110元,星POS为你优惠10元”
#### 2.2.1备注：数字处理策略 ，适用于编号播报，车牌播报等非金额格式的播报。
当message参数中，数字是按金额来播报的，比如“123”，播报为“一百二十三”，如果要按号码、编号来播报，则需要把特殊内容用“**[**”“**]**”方括号包裹起来，
比如：
1、订单编号**[123]**收款66元,则播报为“订单编号一二三收款六十六元”;
2、**[津A8526]**正常通行，则播报为“津A八五二六”正常通行
​

3) 返回参数：

| 参数 | 类型 | 说明  | 必须 |
| --- | --- | --- | --- |
| errcode | integer | 返回码，参见 [网关返回码](#网关返回码) | * |
| errmsg | string | 返回码描述  | * |
| detail | string | 返回的数据 |   |

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

### 3.1 云音箱绑定或解绑（WIFI版必用，流量版选用）
**注意：310、330使用add播报方法时，必须先调用绑定方法进行绑定，其它型号可以不绑定；另外notify方法，全部型号可以不调用绑定方法，流量版推荐notify方法。**
 
1）URL:  [**https://speaker.17laimai.cn/bind.php**](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 | 返回的数据 |   |

 


### 3.2 更改语音信息 （灰度测试）
更改开机语音，自定义播报前缀。**(**仅适用于**402、404、502、504、340)**
 
**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&version=3   
```
表示将云喇叭 ID 10000091 开机语音设置为 “欢迎光临”，关机语音为“谢谢使用”
例子：
```
https://speaker.17laimai.cn/modify_bootvoicewav.php?id=10000091&token=123456789021&sound=欢迎光临&type=0
&version=3
```
表示将云喇叭 ID 10000091 开机语音设置为 “欢迎光临”
3) 返回参数：

| 参数 | 类型 | 说明  | 必须 |
| --- | --- | --- | --- |
| errcode | integer | 返回码，参见 [网关返回码](#网关返回码) | * |
| errmsg | string | 返回码描述  | * |
| detail | string | 返回的数据 |   |

## 4、定时任务

### 4.1、POST 请求（推荐使用）

POST /task.php

#### 请求参数
|名称|类型|必选|说明|
| --- | --- | --- | --- |
|id|string|是|云音箱SN编号|
|version|integer|是|按各型号标注的VERSION版本，由用户配置时选择，预留1-9供选择|
|token|string|是|代理商的 token, 预先通过安全渠道分配，使得代理商对该云音箱 有操作权限|
|message|string|否|播报内容。创建时必选|
|m|integer|否|0：删除定时任务，1：创建定时任务。创建时必选|
|at|string|否|任务执行时间 10位时间戳。创建时必选|
|task_id|string|否|创建定时任务成功后返回的任务ID，删除时必传|

### 4.2、GET 请求

GET /task.php

#### 请求参数


|名称|类型|必选|说明|
| --- | --- | - | --- |
|id|string|是|云音箱SN编号|
|version|integer|是|按各型号标注的VERSION版本，由用户配置时选择，预留1-9供选择|
|token|string|是|代理商的 token, 预先通过安全渠道分配，使得代理商对该云音箱 有操作权限|
|message|string|否|播报内容。创建时必选|
|m|integer|否|0：删除定时任务，1：创建定时任务。创建时必选|
|at|string|否|任务执行时间 10位时间戳。创建时必选|
|task_id|string|否|创建定时任务成功后返回的任务ID，删除时必传|

### 4.3、响应示例

创建成功

~~~json
{
  "errcode": 0,
  "errmsg": "success",
  "detail": {
    "task_id": "52b83e069770e05ba0a640e6ae2a010a"
  }
}
~~~

创建失败

~~~json
{
  "errcode": -1,
  "errmsg": "创建失败,任务时间至少10秒以后",
  "detail": null
}
~~~

删除失败

~~~json
{
  "errcode": -1,
  "errmsg": "删除失败,task_id不正确",
  "detail": null
}
~~~

删除成功

~~~json
{
  "errcode": 0,
  "errmsg": "success",
  "detail": null
}
~~~

#### 返回数据结构

状态码 **200**
|名称|类型|必选|约束|中文名|说明|
| --- |---|---|---|---|---|
|» errcode|integer|true|none|none|
|» errmsg|string|true|none|none|
|» detail|object|true|none|none|
|»» task_id|string|true|none|none|
# 三、常见问题
### 1.  此token 无此 SPEAKERID 权限
1）：检查version,是否与当前设备型号对应正确，[version(接口版本对应表)](#ffvN1)。
2）：检查TOKEN是否正确，是否完整
3）：联系我们，协助检查。

![输入图片说明](imagesimage.png)
【备注云喇叭】