开放 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: {
            ok: [{sn: SN1, taskId: 123456}],
            unsupportSns:[SN2...],
            unexistSns:[SN3...]
        }
    }

返回结果说明:

参数 类型 是否必须 说明
err_code Number 错误码
ok Array 创建成功设备数组
taskId Number 针对每个sn的任务ID
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: {
            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: {
            ok: [{sn: SN1, taskId: 123456}],
            unsupportSns:[SN2...],
            unexistSns:[SN3...]
        }
    }
    // 设备未找到
    {err_code: 5020613, errmsg: "data is required hex string"}

返回结果说明:同上

设备数据

一、获取传感器基本信息

  • 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 服务器错误