设备管理 API

REST API 说明

逸付技术有限公司

物联网设备管理平台 API 文档（V1.0）

1. 文档说明

1.1 文档目的

本文档定义了逸付技术有限公司物联网设备管理平台的标准接口规范，适用于：

消防物联网设备接入（烟感、喷淋、电气火灾监测等）
智慧校园设备接入（门禁、环境监测、能耗设备等）
第三方系统集成（平台对接 / SaaS / 本地部署）

1.2 接口基础信息

项目内容API Base URLhttps://api.yifutech.com/v1数据格式JSON请求方式HTTPS编码格式UTF-8认证方式Token / AppKey

1.3 通用响应格式

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

字段类型说明codeint0成功，非0失败messagestring返回信息dataobject业务数据

2. 认证接口

2.1 获取 Token

接口地址

POST /auth/token

请求参数

{
  "appKey": "your_app_key",
  "appSecret": "your_app_secret"
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "accessToken": "xxxxx",
    "expiresIn": 7200
  }
}

3. 设备管理接口

3.1 设备注册

接口

POST /devices/register

说明

设备首次接入平台时调用

请求参数

{
  "deviceSn": "SN123456789",
  "deviceName": "烟感探测器-01",
  "deviceType": "smoke_detector",
  "productKey": "fire_iot_v1",
  "location": "教学楼A-3楼",
  "projectId": "10001"
}

设备类型示例

类型描述smoke_detector烟感water_pressure水压electric_fire电气火灾access_control门禁env_sensor环境监测

3.2 设备列表查询

GET /devices

请求参数

参数类型说明pageint页码sizeint页大小deviceTypestring设备类型

3.3 设备详情

GET /devices/{deviceId}

3.4 设备删除

DELETE /devices/{deviceId}

3.5 设备状态更新（心跳）

POST /devices/heartbeat

说明

设备周期上报在线状态

{
  "deviceSn": "SN123456789",
  "status": "online",
  "timestamp": 1710000000
}

4. 设备数据上报

4.1 通用数据上报

POST /devices/data

请求参数

{
  "deviceSn": "SN123456789",
  "data": {
    "temperature": 26.5,
    "humidity": 60,
    "smoke": 0.02
  },
  "timestamp": 1710000000
}

4.2 消防报警上报（重点）

POST /devices/alarm

请求参数

{
  "deviceSn": "SN123456789",
  "alarmType": "fire_alarm",
  "level": "high",
  "value": 85,
  "location": "教学楼A-3楼",
  "timestamp": 1710000000
}

报警类型

类型说明fire_alarm火灾报警smoke_alarm烟雾报警water_alarm水压异常electric_alarm电气火灾

5. 设备控制接口

5.1 下发控制指令

POST /devices/command

请求参数

{
  "deviceSn": "SN123456789",
  "command": "restart",
  "params": {}
}

常见指令

指令说明restart重启设备reset恢复出厂open开启设备close关闭设备

5.2 查询指令执行结果

GET /devices/command/{commandId}

6. 项目（场景）管理

6.1 项目创建

POST /projects

{
  "projectName": "XX中学智慧消防",
  "type": "school",
  "address": "上海市XX区"
}

6.2 项目设备列表

GET /projects/{projectId}/devices

7. 日志与告警

7.1 告警列表

GET /alarms

7.2 告警详情

GET /alarms/{alarmId}

7.3 设备日志

GET /devices/{deviceId}/logs

8. WebSocket 实时通信

8.1 连接地址

wss://api.yifutech.com/ws

8.2 推送内容

{
  "type": "alarm",
  "data": {
    "deviceSn": "SN123456789",
    "alarmType": "fire_alarm"
  }
}

9. 错误码定义

code含义0成功1001参数错误1002未授权1003设备不存在1004Token过期2001设备离线3001系统异常

10. 安全规范

所有接口必须使用 HTTPS
Token 必须放在 Header 中：

Authorization: Bearer {token}

建议增加：
- IP 白名单
- 请求签名（防止重放攻击）
- 设备证书认证（高安全场景）