巴法文档中心

Appearance

设备接口 ​

本文档介绍巴法云设备管理相关的API接口，包含主题创建、消息推送、设备查询等功能。

硬件设备说明

硬件设备可以使用HTTP协议访问API接口（将https改为http即可）。

创建单个主题 ​

创建一个新的设备主题。

接口信息 ​

  • 请求方法：POST
  • 请求地址：https://pro.bemfa.com/v1/createTopic
  • Content-Type：application/json

请求参数 ​

参数类型是否必须说明
uidstring是用户私钥
topicstring是主题值，仅限字母、数字
typenumber是设备协议类型
namestring否主题昵称，中英文不限
secretIdstring否API密钥对，用于已认证用户绑定、激活设备。实名认证后获取 点击跳转
secretKeystring否API密钥对，实名认证后获取 点击跳转

协议类型说明 ​

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

设备类型识别 ​

设备类型通过主题名称后三位数字识别：

后缀设备类型示例
001插座设备socket001, power001
002灯泡设备light002, led002
003风扇设备fan003, air003
004传感器设备sensor004, temp004
005空调设备ac005, aircon005
006开关设备switch006, btn006
009窗帘设备curtain009, blind009

请求示例 ​

json
{
    "uid": "00ad90fe27444dff9d5ee32b94c5ae08",
    "type": 3,
    "topic": "led002"
}

响应示例 ​

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

状态码说明 ​

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

创建多个主题 ​

批量创建多个设备主题，最多一次可创建20个。

接口信息 ​

  • 请求方法：POST
  • 请求地址：https://pro.bemfa.com/vs/web/v1/addTopics
  • Content-Type：application/json

请求参数 ​

参数类型是否必须说明
openIDstring是用户私钥
topicsstring[]是主题数组，最多20个
typenumber是设备协议类型
roomstring否设备房间
groupstring否设备分组
secretIdstring否API密钥对，用于已认证用户绑定、激活设备。实名认证后获取 点击跳转
secretKeystring否API密钥对，实名认证后获取 点击跳转

协议类型说明 ​

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

设备类型识别

设备类型通过主题名称后三位数字识别：

  • 001: 插座设备
  • 002: 灯泡设备
  • 003: 风扇设备
  • 004: 传感器设备
  • 005: 空调设备
  • 006: 开关设备
  • 009: 窗帘设备

请求示例 ​

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

响应示例 ​

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

状态码说明 ​

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

删除主题 ​

删除指定的设备主题。

接口信息 ​

  • 请求方法：POST
  • 请求地址：https://pro.bemfa.com/v1/deleteTopic
  • Content-Type：application/json; charset=utf-8

请求参数 ​

参数类型是否必须说明
uidstring是用户私钥
topicstring是主题名称（仅限字母、数字）
typenumber是设备协议类型

协议类型说明 ​

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

请求示例 ​

json
{
    "uid": "4d9ec352e0376f2110a0c601a2857225",
    "topic": "tttt006",
    "type": 3
}

响应示例 ​

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

状态码说明 ​

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

推送消息 ​

向指定主题发送消息，支持向微信推送通知。

接口信息 ​

  • 请求方法：POST
  • 请求地址：https://apis.bemfa.com/va/postJsonMsg
  • Content-Type：application/json; charset=utf-8

请求参数 ​

参数类型是否必须说明
uidstring是用户私钥（从控制台获取）
topicstring是主题名称
typenumber是主题类型（1=MQTT协议，3=TCP协议）
msgstring是消息内容（如：on、off等）
shareboolean否是否为分享设备
wemsgstring否微信推送消息（可选）

请求示例 ​

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

响应示例 ​

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

状态码说明 ​

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

使用示例 ​

可参考下图进行推送测试：

topic

接口信息 ​

  • 请求方法：GET

  • 请求地址：https://apis.bemfa.com/va/sendMessage

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

请求体示例：

http://apis.bemfa.com/va/sendMessage?uid=38fedc3d1dd04d87a19cc60a64577834&topic=000000002&type=3&msg=on

正确返回：

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

code 字段说明：

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

获取消息 ​

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

1、HTTP ### 接口信息

  • 请求方法：GET

  • 请求地址：https://apis.bemfa.com/va/getmsg

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

示例：https://apis.bemfa.com/va/getmsg?uid=d4c470e057e04a3e8b2fefd0b74b6b16&topic=23123001&type=3

正确返回：

{
    "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

  • 请求地址：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

  • 请求地址：http://apis.bemfa.com/vb/api/v2/groupTopic

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

type字段值说明

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

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

正确返回：

{
  "code": 0,
  "msg": "success",
  "data": {
    "data": [
      {
        "topic": "1245001",
        "type": 1,
        "share": false,
        "time": "2024-06-27 10:50:32",
        "unix": 1719456632,
        "online": false,
        "name": "插座",
        "room": "",
        "msg": "",
        "pubOnline": false,
        "deviceType": "outlet",
        "group": "",
        "createTime": "2024-06-27 10:50:32"
      },
      {
        "topic": "2322006",
        "type": 1,
        "share": false,
        "time": "2024-03-31 23:49:22",
        "unix": 1711900162,
        "online": false,
        "name": "开关",
        "room": "",
        "msg": "off",
        "pubOnline": false,
        "deviceType": "switch",
        "group": "",
        "createTime": "2024-03-31 23:40:35"
      }
    ]
  }
}

data内字段说明：

字段说明
topic主题值
type协议类型
share是否是分享设备
time消息发送的时间，时区UTC/GMT+08:00
unix消息发送的时间戳
online是否在线
name主题名字
room房间名字
msg消息体
pubOnline推送者是否在线
deviceType设备类型
group分组
createTime主题创建时间

deviceType字段说明：

字段说明
outlet插座
light灯
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘
thermostat温控器
waterheater热水器
television电视
airpurifier空气净化器

获取设备所有房间 ​

接口信息 ​

  • 请求方法：GET

  • 请求地址：http://apis.bemfa.com/vb/api/v1/allRoom

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

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

  • 请求地址：http://apis.bemfa.com/vb/api/v2/roomTopic

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

type字段值说明

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

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

正确返回：

{
  "code": 0,
  "msg": "success",
  "data": {
    "data": [
      {
        "topic": "0D4061002",
        "type": 3,
        "share": false,
        "time": "2024-06-27 09:53:59",
        "unix": 1719453239,
        "online": false,
        "name": "灯",
        "room": "",
        "msg": "on",
        "pubOnline": false,
        "deviceType": "light",
        "group": "",
        "createTime": "2024-06-21 16:06:38"
      },
      {
        "topic": "xxsn2002",
        "type": 3,
        "share": false,
        "time": "2024-09-11 11:28:13",
        "unix": 1726025293,
        "online": false,
        "name": "灯",
        "room": "",
        "msg": "",
        "pubOnline": false,
        "deviceType": "light",
        "group": "分组一",
        "createTime": "2024-09-11 11:28:13"
      }
    ]
  }
}

data内字段说明：

字段说明
topic主题值
type协议类型
share是否是分享设备
time消息发送的时间，时区UTC/GMT+08:00
unix消息发送的时间戳
online是否在线
name主题名字
room房间名字
msg消息体
pubOnline推送者是否在线
deviceType设备类型
group分组
createTime主题创建时间

deviceType字段说明：

字段说明
outlet插座
light灯
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘
thermostat温控器
waterheater热水器
television电视
airpurifier空气净化器

获取所有主题信息 ​

接口信息 ​

  • 请求方法：GET

  • 请求地址：http://apis.bemfa.com/vb/api/v2/allTopic

参数是否必须说明
openID是用户私钥，巴法云控制台获取
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主题值
type协议类型
share是否是分享设备
time消息发送的时间，时区UTC/GMT+08:00
unix消息发送的时间戳
online是否在线
name主题名字
room房间名字
msg消息体
pubOnline推送者是否在线
deviceType设备类型
group分组
createTime主题创建时间

deviceType字段说明：

字段说明
outlet插座
light灯
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘
thermostat温控器
waterheater热水器
television电视
airpurifier空气净化器

示例：http://apis.bemfa.com/vb/api/v2/allTopic?openID=4d9ec352e0376f2110a0c601a2857225&type=3

获取单个主题信息 ​

接口信息 ​

  • 请求方法：GET

  • 请求地址：http://apis.bemfa.com/vb/api/v2/topicInfo

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

type字段值说明

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

正确返回：

{
    "code": 0,
    "msg": "success",
    "data": {
        "name": "客厅灯",
        "msg": "on",
        "online": true,
        "onlineNum": 1,
        "pubOnline": false,
        "deviceType": "light",
        "share": false,
        "group": "",
        "room": "客厅",
        "time": "2025-07-30 16:40:13",
        "unix": 1753864813,
        "createTime": "2024-12-27 17:52:49"
    }
}

data内字段说明：

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

deviceType字段说明：

字段说明
outlet插座
light灯
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘
thermostat温控器
waterheater热水器
television电视
airpurifier空气净化器

示例：http://apis.bemfa.com/vb/api/v2/topicInfo?openID=4d9ec352e0376f2110a0c601a2857225&type=3&topic=0D4061002

获取设备在线 ​

接口信息 ​

  • 请求方法：GET

  • 请求地址：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

  • 请求地址：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

  • 请求地址：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
  • 请求地址：https://apis.bemfa.com/va/modifyName
  • Content-Type：application/json; charset=utf-8

请求参数 ​

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

type字段值说明

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

请求示例：

{
    "uid":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topic":"sn001",
    "type":3,
    "name":"卧室灯"
}

请求正常响应：

{
    "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

  • 请求地址：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/json; charset=utf-8

  • 请求地址：https://apis.bemfa.com/va/shareDevice

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

请求示例：

{
    "uid":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topic":"sn001",
    "type":3,
    "name":"卧室灯",
    "email":"133xxxxxxx@qq.com"
}

正确返回：

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

code 字段说明：

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

2、获取设备已分享列表

接口信息 ​

  • 请求方法：GET

  • 请求地址：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/json; charset=utf-8

  • 请求地址：https://apis.bemfa.com/va/deleteShare

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

请求示例：

{
    "uid":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topic":"sn001",
    "type":3,
    "email":"133xxxxxxx@qq.com"
}

正确返回：

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

code 字段说明：

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

巴法开放联盟

BeHome Alliance