开放 API

SENSORO 向开发者提供开放 API 接口，方便开发者对接 IoT 云平台。

本文档说明接口的鉴权方式：参考 API权限检验 - 消息体签名。

生产环境域名：https://iot-api.sensoro.com

异步任务

一、传输周期设置

适用设备类型：除 α 传输模块外，各类传感器

POST /developers/device/interval

  Request: {
      sns: [SN1, SN2],
      cfg: {
          interval: 5
      }
  }
  //请求失败 sns 应非空字符串数组
  {
      err_code: 5020610,
      err_msg: "sns is required array of strings"
  }
  //请求失败 interval 取值应为 >60 的整数
  {
      err_code: 5020612,
      err_msg: "interval is a required integer greater than 60"
  }

请求接口说明

参数	类型	是否必须	说明
sns	String	是	传感器 sn 数组
interval	Number	是	传输周期

返回结果：

    Response:
        err_code: 0,
        data: {
            scheduleNo : "ED-20180428-200855", // 任务批次号
            ok: [{sn: SN1, taskId: 123456}],
            unsupportSns:[SN2...],
            unexistSns:[SN3...]
        }
    }

返回结果说明：

参数	类型	是否必须	说明
err_code	Number	是	错误码
ok	Array	是	创建成功设备数组
taskId	Number	是	针对每个sn的任务ID
scheduleNo	String	是	任务批次号
unsupportSns	Array	是	不支持此种任务的设备列表
unexistSns	Array	是	系统中不存在的设备列表

二、紧急报警设置

适用设备类型：除 α 传输模块与 α 传感器外的各类传感器

POST /developers/device/threshold

    Request: {
        sns: [SN1,SN2,....],
        deviceType: 'co',
        cfg: {
            pm2_5AlarmHigh: 100
            pm10AlarmHigh: 100,
            pm1AlarmHigh: 100
        }
    }

请求接口说明

参数	类型	设备类型	说明
sn	String	all	传感器 sn
deviceType	String	all	传感器类型
threshold	Object	all	配置内容
coAlarmHigh	Number	co	一氧化碳报警阈值
co2AlarmHigh	Number	co2	二氧化碳报警阈值
so2AlarmHigh	Number	so2	二氧化硫报警阈值
no2AlarmHigh	Number	no2	二氧化氮报警阈值
ch4AlarmHigh	Number	ch4	甲烷报警阈值
nh3AlarmHigh	Number	nh3	氨气报警阈值
pm2_5AlarmHigh	Number	pm	pm2.5 报警阈值
pm10AlarmHigh	Number	pm	pm10 报警阈值
pm1AlarmHigh	Number	pm	pm1 报警阈值
lpgAlarmHigh	Number	lpg	液化石油气报警阈值
ch2oAlarmHigh	Number	tvoc	甲醛报警阈值
tempAlarmHigh	Number	temp_humi	温度报警阈值（max）
tempAlarmLow	Number	temp_humi	温度报警阈值（min）
humiAlarmHigh	Number	temp_humi	湿度报警阈值（max）
humiAlarmLow	Number	temp_humi	湿度报警阈值（min）
o3AlarmHigh	Number	o3	臭氧浓度报警阈值
angleAlarmHigh	Number	angle	倾斜角度报警阈值

备注：上表中的传感器阈值至少有一项存在

返回结果：

    Response:
        err_code: 0,
        data: {
            scheduleNo : "ED-20180428-200855", // 任务批次号
            ok: [{sn: SN1, taskId: 123456}],
            unsupportSns:[SN2...],
            unexistSns:[SN3...]
        }
    }

    // coAlarmHigh 取值应为 >0 的整数
    {err_code: 5020614, err_msg: "coAlarmHigh should be a positive integer"}
    // co2AlarmHigh 取值应为 >0 的整数
    {err_code: 5020615, err_msg: "co2AlarmHigh should be a positive integer"}
    // so2AlarmHigh 取值应为 >0 的整数
    {err_code: 5020616, err_msg: "so2AlarmHigh should be a positive integer"}
    // no2AlarmHigh 取值应为 >0 的整数
    {err_code: 5020617, err_msg: "no2AlarmHigh should be a positive integer"}
    // ch4AlarmHigh 取值应为 >0 的整数
    {err_code: 5020618, err_msg: "ch4AlarmHigh should be a positive integer"}
    // pm2_5AlarmHigh 取值应为 >0 的整数
    {err_code: 5020619, err_msg: "pm2_5AlarmHigh should be a positive integer"}
    // pm10AlarmHigh 取值应为 >0 的整数
    {err_code: 5020620, err_msg: "pm10AlarmHigh should be a positive integer"}

返回结果说明：同上

三、自定义数据下行--传输模块

适用设备类型： α 传输模块

POST /developers/device/cdata

    Request: {
        sns: [SN,...],
        data: "2a3d4e5f1123baf12de3"
    }

请求接口说明

参数	类型	是否必须	说明
sn	String	是	传感器 sn
data	String	是	配置内容

注：data 为16进制字符串

返回结果：

    Response:
        err_code: 0,
        data: {
            scheduleNo : "ED-20180428-200855", // 任务批次号
            ok: [{sn: SN1, taskId: 123456}],
            unsupportSns:[SN2...],
            unexistSns:[SN3...]
        }
    }
    // 设备未找到
    {err_code: 5020613, errmsg: "data is required hex string"}

返回结果说明：同上

四、自定义数据下行--下行解析器

适用设备类型：全部设备

POST /developers/device/:dataPacker/data

    Request: {
        sns: [SN,...],
        data: {
            // 此处内容需根下行解析器内容定义,例如 dataPacker = 'tracker' ,则 data中可为如下值：
            // cmd: 'emergenceStart',
            // emergenceTime: 30
        }
    }

请求接口说明

参数	类型	是否必须	说明
dataPacker	String	是	需要使用的解析器类型
sn	String	是	传感器 sn
data	Object	是	配置内容

返回结果：

    Response:
        err_code: 0,
        data: {
            ok: [{sn: SN1, taskId: 123456}], // 创建成功的SN 及任务 id 列表
            scheduleNo : "ED-20180428-200855", // 任务批次号
            unexistSns:[SN3...] // 未找到的设备 SN 列表
        }
    }

    // 参数非法
    {
        "err_info": "", // 下行解析器中定义的详细错误信息
        "err_code": 704,
        "err_msg": "Invalid Params"
    }

返回结果说明：同上

设备数据

一、获取传感器基本信息

GET /developers/device/:sn

返回结果：

    Response:{
        err_code: 0,
        data: {
            sn: "1122334455667788",
            name: "设备名称",
            tags: ["标签一", "标签二"]
            deviceType: "node",
            firmwareVersion: "",
            hardwareVersion: "",
            battery: "",
            interval: "",
            band: "",
            txPower: "",
            sf: "",
            normalStatus: 0,
            status: ""
        }
    }

    // 设备未找到
    {err_code: 5010107, err_msg: "device not found"}

返回结果说明：

参数	类型	是否必须	说明
err_code	Number	是	错误码
sn	String	是	"1122334455667788"
name	String	是	传感器名称
tags	Array	是	标签列表
deviceType	String	是	设备类型
firmwareVersion	String	是	固件版本
hardwareVersion	String	是	硬件版本
battery	String	是	电量
interval	String	是	周期
band	String	是	频段
txPower	String	是	功率
sf	String	是	扩频
normalStatus	Number	是	见下表
status	String	是	见下表

normalStatus 及 status 取值及含义：

normalStatus	status	说明
-1	"inactive"	未激活
0	"normal"	正常
1	"error"	报警
2	"danger"	紧急报警
3	"timeout"	超时未上报
4	"offline"	离线（超时超过两天）

二、获取传感器数据列表

GET /developers/device/list

请求参数：

    Query: {
        page: 1, // 指定页码
        count: 100, // 分页条数，非必须，默认值： 20
    }

返回结果：

    Response:{
        err_code: 0,
        data: {
            items: [{
                sn: "1122334455667788",
                name: "设备名称",
                tags: ["标签一", "标签二"]
                deviceType: "node",
                firmwareVersion: "",
                hardwareVersion: "",
                battery: "",
                interval: "",
                band: "",
                txPower: "",
                sf: "",
                normalStatus: 0,
                status: ""
            }],
            page_info: {
                current_page: 1, // 当前页数
                count: 10, // 总页数
                items_count: 200 // 记录总数
            }
        }
    }

    // 返回数据条数不超过 1000
    {err_code: 5010108, err_msg: "count should be a positive integer and le 1000"}

三、获取基站基本信息

GET /developers/station/:sn

返回结果：

    Response:{
        err_code: 0,
        data: {
            sn: "1122334455667788",
            name: "设备名称",
            tags: ["标签一", "标签二"],
            type: "station",
            firmwareVersion: "",
            hardwareVersion: "",
            lonlat: [],
            netacm : "cellular",
            normalStatus: 0,
            status: "",
            prevUpTime: 1517801384845,
            band: "SE433"
        }
    }

    // 设备未找到
    {err_code: 5010107, err_msg: "device not found"}
    {err_code: 5020601, err_msg: "invalid params"}

返回结果说明：

参数	类型	是否必须	说明
err_code	Number	是	错误码
sn	String	是	设备编号
name	String	是	基站名称
tags	Array	是	标签列表
type	String	是	基站类型
firmwareVersion	String	是	固件版本
hardwareVersion	String	是	硬件版本
lonlat	Arrary	是	经纬度信息
netacm	String	是	联网方式
normalStatus	Number	是	同传感器表
status	String	是	同传感器表
band	String	是	频段信息
prevUpTime	Number	是	最近上报时间

netacm 取值 wifi | cellular | ethernet

normalStatus 及 status 取值及含义同传感器

四、获取基站数据列表

GET /developers/station/list

请求参数：

    Query: {
        page: 1, // 指定页码
        count: 100, // 分页条数，非必须，默认值： 20
    }

返回结果：

    Response:{
        err_code: 0,
        data: {
            items: [{
                sn: "1122334455667788",
                name: "基站名称",
                tags: ["标签一", "标签二"],
                type: "station",
                firmwareVersion: "",
                hardwareVersion: "",
                lonlat: [],
                netacm : "cellular"
                normalStatus: 0,
                status: "",
                prevUpTime: 1517801384845,
                band: "SE433"
            }],
            page_info: {
                current_page: 1, // 当前页数
                count: 10, // 总页数
                items_count: 200 // 记录总数
            }
        }
    }

    // 返回数据条数不超过 1000
    {err_code: 5010108, err_msg: "count should be a positive integer and le 1000"}

五、获取传感器数据历史

GET /developers/device/:sn/log

请求参数举例

Query: {
    startTime: 1479980803078,
    endTime: 1479980811283,
    page: 1,
    count: 100,
    order: "asc"
}

参数说明:

参数	是否必有	类型	示例值	说明
startTime	否	Number	1479980803078	数据起始时间
endTime	否	Number	1479980811283	数据截止时间
page	否	Number	1	页数，默认为 1
count	否	Number	100	返回数据条数，默认为 100 条，不超过 1000
order	否	String	desc	排序方式。desc 为降序， asc 为升序，默认为降序

返回参数举例

Response: {
    err_code: 0,
    data: [{
        msgId: "582249abc744925bcbfaea2a",
        createdTime: 1478642091182,
        sn: "10B30117C6BCA37D",
        data: {
            temperature: 21.029142379760742,
            light: 0.0010000000474974513,
            humidity: 30.61346435546875,
            battery: 99
        }
    },{
        msgId: "58224979c744925bcbfaea0e",
        createdTime: 1478642041151,
        sn: "10B30117C6BCA37D",
        data: {
            temperature: 21.018417358398438,
            light: 0.0010000000474974513,
            humidity: 30.5753173828125,
            battery: 99
        }
    }, ......]
}

成功参数说明

参数	是否必有	类型	示例值	说明
err_code	是	Number	0	错误代码，0成功
data	是	Array	[]	终端传感器历史数据列表

失败参数说明

参数	是否必有	类型	示例值	说明
err_code	是	Number	-1	系统繁忙，请稍后再试
err_code	是	Number	5010108	返回数据条数不能超过 1000 条

六、关联设备到商户（商户添加设备）

POST /developers/device/relation

请求参数举例

    Request: {
        sns: [SN1, SN2, SN3]
    }

返回参数举例

Response: {
    err_code: 0,
    data: {
        ok:['8877665544332211'],
        thisOwner:['1122334455667788'],
        otherOwner:[],
        notFound:[]
    }
}

参数说明

参数	是否必有	类型	示例值	说明
sns	是	Array	['1122334455667788', '8877665544332211']	要关联设备sn数组

成功参数说明

参数	是否必有	类型	示例值	说明
err_code	是	Number	0	错误代码，0成功
data	是	Object	{}	包含错误码以外的其他返回结果
ok	是	Array	[]	关联成功的 sn 数组
thisOwner	是	Array	[]	已经属于此商户的 sn 数组
otherOwner	是	Array	[]	已经属于其他商户的 sn 数组
notFound	是	Array	[]	系统中未找到的 sn 数组

失败参数说明

参数	是否必有	类型	示例值	说明
err_code	是	Number	5010101	sns 是必传参数
err_code	是	Number	500	服务器错误

七、解除设备与商户的关联关系（商户删除设备）

DELETE /developers/device/relation

请求参数举例

    Request: {
        sns: [SN1, SN2, SN3]
    }

返回参数举例

Response: {
    err_code: 0,
    data: {
        ok:['1122334455667788'],
        notFound:['8877665544332211']
    }
}

参数说明

参数	是否必有	类型	示例值	说明
sns	是	Array	['1122334455667788', '8877665544332211']	要关联设备sn数组

成功参数说明

参数	是否必有	类型	示例值	说明
err_code	是	Number	0	错误代码，0成功
data	是	Object	{}	包含错误码以外的其他返回结果
ok	是	Array	[]	解除关联成功的 sn 数组
notFound	是	Array	[]	系统中未找到的 sn 数组

失败参数说明

参数	是否必有	类型	示例值	说明
err_code	是	Number	5010101	sns 是必传参数
err_code	是	Number	500	服务器错误

八、修改设备信息（名称、标签、坐标）

PUT /developers/:type/info

请求参数举例

    // type 取值为  'device' or 'station'
    // data 数组长度不得 > 1000
    Request: {
        data: [{
            sn: '1122334455667788',
            name:'设备名称'
            tags: ['标签1','标签2'],
            lonlat: [114.25751, 22.376788]
        },{
            sn: '8877665544332211',
            name:'设备名称'
        }...]
    }

返回参数举例

Response: {
    err_code: 0,
    data: {
        ok:['1122334455667788'],
        notFound:['8877665544332211']
    }
}

参数说明

参数	是否必有	类型	示例值	说明
sn	否	String	'1122334455667788'	设备SN
name	否	String	'设备名称'	设备名称
tags	否	Array	['标签1','标签2']	标签数组
type	是	String	'device'	传感器或基站 SN
data	是	Array	{sn: '1122334455667788', name:'设备名称'}	乘载需要更新的数据
lonlat	否	Array	[114.25751, 22.376788]	地理位置坐标

成功参数说明

参数	是否必有	类型	示例值	说明
err_code	是	Number	0	错误代码，0成功
data	是	Object	{}	包含错误码以外的其他返回结果
ok	是	Array	[]	解除关联成功的 sn 数组
notFound	是	Array	[]	系统中未找到的 sn 数组

失败参数说明

参数	是否必有	类型	示例值	说明
err_code	是	Number	5020601	参数错误
err_code	是	Number	500	服务器错误

开放API

开放 API

目录

异步任务

一、传输周期设置

二、紧急报警设置

三、自定义数据下行--传输模块

四、自定义数据下行--下行解析器

设备数据

一、获取传感器基本信息

二、获取传感器数据列表

三、获取基站基本信息

四、获取基站数据列表

五、获取传感器数据历史

六、关联设备到商户（商户添加设备）

七、解除设备与商户的关联关系（商户删除设备）

八、修改设备信息（名称、标签、坐标）

开放 API

目录

异步任务

一、传输周期设置

二、紧急报警设置

三、自定义数据下行--传输模块

四、自定义数据下行--下行解析器

设备数据

一、获取传感器基本信息

二、获取传感器数据列表

三、获取基站基本信息

四、获取基站数据列表

五、获取传感器数据历史

六、 关联设备到商户（商户添加设备）

七、 解除设备与商户的关联关系（商户删除设备）

八、 修改设备信息（名称、标签、坐标）

六、关联设备到商户（商户添加设备）

七、解除设备与商户的关联关系（商户删除设备）

八、修改设备信息（名称、标签、坐标）