巴法文档中心

Appearance

简介 ​

如果硬件设备使用API接口，可以将https去掉s作http接口使用。

创建单个主题 ​

用户创建主题

POST接口

数据类型 "Content-Type": "application/x-www-form-urlencoded"

https://pro.bemfa.com/v1/addtopic

参数是否必须说明
uid是用户私钥
topic是主题值，仅限字母、数字
type是类型类型
name否主题昵称，中英文不限

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

topic字段值说明：

根据topic字段后三位判断主题类型

当主题名字后三位是001时为插座设备。

当主题名字后三位是002时为灯泡设备。

当主题名字后三位是003时为风扇设备。

当主题名字后三位是004时为传感器设备。

当主题名字后三位是005时为空调设备。

当主题名字后三位是006时为开关设备。

当主题名字后三位是009时为窗帘设备。

请求正常响应：

{
    "code": 0,
    "message": "OK",
    "data": 0
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40006设备已存在
40009主题错误，仅限字母、数字，最大长度64

创建多个主题 ​

用户创建主题

POST接口

数据类型 Content-Type: application/json

https://pro.bemfa.com/vs/web/v1/addTopics

参数是否必须类型说明
openID是字符串类型用户私钥
topics是字符串数组主题值，最多一次可创建20个
type是int整型主题类型
room否字符串类型房间
group否字符串类型分组
adminID否int整型企业ID

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

topic字段值说明：

根据topic字段后三位判断主题类型

当主题名字后三位是001时为插座设备。

当主题名字后三位是002时为灯泡设备。

当主题名字后三位是003时为风扇设备。

当主题名字后三位是004时为传感器设备。

当主题名字后三位是005时为空调设备。

当主题名字后三位是006时为开关设备。

当主题名字后三位是009时为窗帘设备。

请求体示例：

{
    "openID": "00ad90fe27444dff9d5ee32b94c5ae08",
    "type": 3,
    "topics": [
        "xxsn001",
        "xxsn1002",
        "xxsn2002",
        "xxsn042",
        "led002"
    ],
    "group": "分组一",
    "adminID": 0
}

请求正常响应：

{
    "code": 0,
    "msg": "success",
    "data": {
        "code": 0,
        "message": ""
    }
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40006设备已存在

删除主题 ​

用户删除主题

POST接口

数据类型 "Content-Type": "application/x-www-form-urlencoded"

https://pro.bemfa.com/v1/deltopic

参数是否必须说明
uid是用户私钥
topic是主题名称，仅限字母、数字类型
type是设备类型

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

请求正常响应：

{
    "code": 0,
    "message": "OK",
    "data": 0
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40004uid或topic错误

推送消息 ​

向主题推送消息，支持POST协议：

1、POST接口

JSON格式

数据类型 "Content-Type": "application/json; charset=utf-8

API: https://apis.bemfa.com/va/postJsonMsg

参数是否必须说明
uid是用户私钥，巴法云控制台获取
topic是主题名，可在控制台创建
type是主题类型，当type=1时是MQTT协议，3是TCP协议
msg是消息体，要推送的消息，自定义即可，比如on，或off等等
wemsg否发送到微信的消息，自定义即可。如果携带此字段，会将消息发送到微信

请求体示例：

{
    "uid": "7801e4ba1bf7406593d47250797860fd",
    "topic": "led002",
    "type": 3,
    "msg": "on"
}

正确返回：

{
    "code": 0,
    "message": "OK",
    "data": 0
}

code 字段说明：

code状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

推送示例可参考:

topic

2、POST接口

数据类型 "Content-Type": "application/x-www-form-urlencoded"

API: https://apis.bemfa.com/va/postmsg

参数是否必须说明
uid是用户私钥，巴法云控制台获取
topic是主题名，可在控制台创建
type是主题类型，当type=1时是MQTT协议，3是TCP协议
msg是消息体，要推送的消息，自定义即可，比如on，或off等等
wemsg否发送到微信的消息，自定义即可。如果携带此字段，会将消息发送到微信

正确返回：

{
    "code": 0,
    "message": "OK",
    "data": 0
}

code 字段说明：

code状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

推送示例可参考:

topic

获取消息 ​

获取主题消息，支持GET协议：

1、HTTP GET接口

API: https://apis.bemfa.com/va/getmsg

参数是否必须说明
uid是用户私钥，巴法云控制台获取
topic是主题名，可在控制台创建
type是主题类型，当type=1时是MQTT协议，3是TCP协议
num否获取的历史数据条数，不填默认默认是1，最大5000

正确返回：

{
    "code": 0,
    "message": "OK",
    "data": [
        {
            "msg": "on",
            "time": "2022-08-03 17:26:34",
            "unix": 1659518794
        }
    ]
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

data内字段说明：

字段说明
msg获取的主题消息
time消息发送的时间，时区UTC/GMT+08:00
unix消息发送的时间戳

获取设备所有分组 ​

GET接口

API: http://apis.bemfa.com/vb/api/v1/allGroup

参数是否必须说明
openID是用户私钥，巴法云控制台获取
type是主题名，可在控制台创建

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

示例：http://apis.bemfa.com/vb/api/v1/allGroup?openID=00ad90fe27444dff9d5ee32b94c5ae08&type=3

正确返回：

{
    "code": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "name": "未分组",
                "num": 2
            },
            {
                "name": "设备一",
                "num": 5
            },
            {
                "name": "设备二",
                "num": 4
            }
        ]
    }
}

data字段说明：

字段说明
name分组名称
num分组内设备数量

通过分组获取设备 ​

GET接口

API: http://apis.bemfa.com/vb/api/v1/groupTopic

参数是否必须类型说明
openID是字符串类型用户私钥
type是int整型主题类型
group否字符串类型分组

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

示例：http://apis.bemfa.com/vb/api/v1/groupTopic?openID=00ad90fe27444dff9d5ee32b94c5ae08&type=1&group=未分组

正确返回：

{
    "code": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "topic": "1245001",
                "type": 1,
                "sid": "",
                "time": "2024-06-27 10:51:58",
                "unix": 1719456718,
                "online": false,
                "name": "插座",
                "room": "",
                "msg": "off"
            },
            {
                "topic": "2322006",
                "type": 1,
                "sid": "",
                "time": "2024-03-31 23:49:22",
                "unix": 1711900162,
                "online": false,
                "name": "开关",
                "room": "",
                "msg": "off"
            }
        ]
    }
}

data内字段说明：

字段说明
topic主题值
type设备类型
sid如果是分享设备，此字段是分享者密钥
time消息发送的时间，时区UTC/GMT+08:00
unix消息发送的时间戳
online是否在线
name主题名字
room房间名字
msg消息体

获取设备所有房间 ​

GET接口

API: http://apis.bemfa.com/vb/api/v1/allRoom

参数是否必须说明
openID是用户私钥，巴法云控制台获取
type是主题名，可在控制台创建

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

示例：http://apis.bemfa.com/vb/api/v1/allRoom?openID=00ad90fe27444dff9d5ee32b94c5ae08&type=3

正确返回：

{
    "code": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "name": "未分组",
                "num": 11
            }
        ]
    }
}

data字段说明：

字段说明
name名称
num设备数量

通过房间获取设备 ​

GET接口

API: http://apis.bemfa.com/vb/api/v1/roomTopic

参数是否必须类型说明
openID是字符串类型用户私钥
type是int整型主题类型
room否字符串类型房间

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

示例：http://apis.bemfa.com/vb/api/v1/roomTopic?openID=00ad90fe27444dff9d5ee32b94c5ae08&type=3&room=未分组

正确返回：

{
    "code": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "topic": "xxsn032",
                "type": 3,
                "sid": "",
                "time": "",
                "unix": 0,
                "online": false,
                "name": "",
                "room": "",
                "msg": ""
            },
            {
                "topic": "xxsn042",
                "type": 3,
                "sid": "",
                "time": "",
                "unix": 0,
                "online": false,
                "name": "",
                "room": "",
                "msg": ""
            }
        ]
    }
}

data内字段说明：

字段说明
topic主题值
type设备类型
sid如果是分享设备，此字段是分享者密钥
time消息发送的时间，时区UTC/GMT+08:00
unix消息发送的时间戳
online是否在线
name主题名字
room房间名字
msg消息体

获取所有主题信息 ​

1、GET接口

API: https://apis.bemfa.com/va/alltopic

参数是否必须说明
uid是用户私钥，巴法云控制台获取
type是主题类型，当type=1时是MQTT协议，3是TCP协议

正确返回：

{
    "code": 0,
    "message": "OK",
    "data": [
        {
            "topic": "cat002",
            "msg": "off",
            "name": "home light",
            "online": true,
            "tid": "light",
            "sid": "",
            "time": "2022-08-03 16:39:27",
            "unix": 1659515967
        },
        {
            "topic": "me001",
            "msg": "on",
            "name": "电视",
            "online": false,
            "tid": "outlet",
            "sid": "",
            "time": "2022-08-03 11:49:11",
            "unix": 1659498551
        }
    ]
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40003私钥错误

data内字段说明：

字段说明
topic主题值
msg消息体
name主题名字
online是否在线
tid设备类型
sid如果是分享设备，此字段是分享者密钥
time消息发送的时间，时区UTC/GMT+08:00
unix消息发送的时间戳

tid字段说明：

字段说明
outlet插座
light灯
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘

获取单个主题信息 ​

1、GET接口

API: https://apis.bemfa.com/vb/api/v1/topicInfo

参数是否必须类型说明
openID是字符串类型用户私钥
type是int整型主题类型
topic是字符串类型主题

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

正确返回：

{
    "code": 0,
    "msg": "success",
    "data": {
        "name": "灯",
        "msg": "off",
        "online": false,
        "onlineNum": 0,
        "pubOnline": false,
        "deviceType": "light",
        "shareOpenID": "",
        "group": "",
        "room": "客厅",
        "time": "2024-05-23 17:22:06",
        "unix": 1716456126,
        "createTime": "2023-09-13 16:40:21"
    }
}

data内字段说明：

参数类型说明
name字符串主题名称
msg字符串或json消息
onlinebool订阅是否在线
onlineNum整形订阅在线个数
pubOnlinebool发布者是否在线，半小时内是否有消息推送
onlineNum整形订阅在线个数
shareOpenID字符串分享者私钥，需base64解码
group字符串分组名，空是没有分组
room字符串房间名，空是没有房间
time字符串主题消息发送的时间，时区UTC/GMT+08:00
unix整形消息发送的时间戳
createTime字符串主题创建的时间，时区UTC/GMT+08:00

deviceType字段说明：

字段说明
outlet插座
light灯
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘

获取设备在线 ​

GET接口

API: https://apis.bemfa.com/va/online

参数是否必须说明
uid是用户私钥，巴法云控制台获取
topic是主题名，可在控制台创建
type是主题类型，当type=1时是MQTT协议，3是TCP协议

正确返回：

{
    "code": 0,
    "message": "OK",
    "data": false
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

data 字段说明：

状态码说明
true设备在线
false设备离线

修改设备房间 ​

POST接口

API: http://apis.bemfa.com/vb/api/v1/changeTopicRoom

请求参数：

参数是否必须类型说明
openID是字符串类型用户私钥
topicIDs是字符串数组主题值，最少修改一个，最多一次可修改50个
room否字符串类型房间 ，空值表示清空房间

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

请求示例：

{
    "openID":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topicIDs":["0D4061002"],
    "type":3,
    "rome":"客厅"
}

正确返回：

{
    "code": 0,
    "msg": "success",
    "data": {
        "code": 0
    }
}

data字段说明：

字段说明
code0成功

修改设备分组 ​

POST接口

API: http://apis.bemfa.com/vb/api/v1/changeTopicGroup

请求参数：

参数是否必须类型说明
openID是字符串类型用户私钥
topicIDs是字符串数组主题值，最少修改一个，最多一次可修改50个
group否字符串类型分组名 ，空值表示清空分组

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

请求示例：

{
    "openID":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topicIDs":["sn01"],
    "type":3,
    "group":"分组2"
}

正确返回：

{
    "code": 0,
    "msg": "success",
    "data": {
        "code": 0
    }
}

data字段说明：

字段说明
code0成功

修改主题昵称 ​

修改设备昵称

POST接口

数据类型 "Content-Type": "application/x-www-form-urlencoded"

https://apis.bemfa.com/va/setName

参数是否必须说明
uid是用户私钥
topic是主题名称，仅限字母、数字类型
type是类型类型
name是主题昵称

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

请求正常响应：

{
    "code": 0,
    "message": "OK",
    "data": 0
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误

获取主题昵称 ​

获取主题昵称

GET接口

https://apis.bemfa.com/va/getName

参数是否必须说明
uid是用户私钥
topic是主题名称
type是类型类型

type字段值说明

值说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本，内测中
7TCP协议设备V2版本，内测中

请求正常响应：

{
    "code": 0,
    "message": "OK",
    "data": "传感器"
}

data 字段是获取的主题昵称。

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40004密钥或主题错误

获取时间 ​

单片机使用建议使用http，端口80。https默认端口443。

GET接口

API: https://api.bemfa.com/api/time/now/

参数是否必须说明
type否type不填默认为1，type=1是只获取时间，等于2获取日期和时间

示例：https://api.bemfa.com/api/time/now/?type=1

esp8266示例下载: 点击下载

esp32示例下载: 点击下载

设备分享 ​

设备分享相关共有三个接口：设备分享，获取设备已分享列表，删除设备分享。

1、设备分享接口

POST接口

数据类型 "Content-Type": "application/x-www-form-urlencoded"

API: https://apis.bemfa.com/va/sharedevice

参数是否必须说明
uid是用户私钥，巴法云控制台获取
topic是主题名，可在控制台创建
type是主题类型，当type=1时是MQTT协议，3是TCP协议
name是设备昵称
email是接收人的邮箱

正确返回：

{
    "code": 0,
    "message": "OK",
    "data": null
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误
40005接入人邮箱错误或不存在
40005设备已存在

2、获取设备已分享列表

GET接口

API: https://apis.bemfa.com/va/getShareList

参数是否必须说明
uid是用户私钥，巴法云控制台获取
topic是主题名，可在控制台创建
type是主题类型，当type=1时是MQTT协议，3是TCP协议

正确返回：

{
    "code": 0,
    "message": "OK",
    "data": [
        {
            "email": "1217xxxxxx1@qq.com",
            "time": "2022-08-04 10:45:57",
            "unix": 1659581157
        },
        {
            "email": "1217xxxxxx2@qq.com",
            "time": "2022-08-04 10:45:59",
            "unix": 1659581159
        },
    ]
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

data内字段说明：

字段说明
email接收者邮箱
time消息发送的时间，时区UTC/GMT+08:00
unix消息发送的时间戳

3、删除分享

POST接口

数据类型 "Content-Type": "application/x-www-form-urlencoded"

API: https://apis.bemfa.com/va/delshare

参数是否必须说明
uid是用户私钥，巴法云控制台获取
topic是主题名，可在控制台创建
type是主题类型，当type=1时是MQTT协议，3是TCP协议
email是接收人的邮箱

正确返回：

{
    "code": 0,
    "message": "OK",
    "data": null
}

code 字段说明：

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误
40005接入人邮箱错误或不存在

巴法开放联盟

BeHome Alliance