小鹰开放平台告警对接V1.0.2

版本历史（最新：V1.0.2 / 2026-01-12）
版本 更新日期 更新说明 修改人
V1.0.2 2026-01-12 新增部分告警类型 严永龙
V1.0.1 2025-09-10 将鉴权示例代码移至新文档《生成sign的示例代码》
新增加unkonw的警报类型
新增加截图、录像的事件消息		 陈鲁彬
V1.0.0 2025-09-09 新建文档 陈鲁彬

一 、适用范围

本文档适用于所有设备

二、对接说明

2.1、准备工作

2.1.1、设备ID必须存在于小鹰开放平台

设备交付给客户后，需要确保设备ID存在于小鹰开放平台。否则会影响后续流程。可以与您的销售/商务对接人确保这一步已经完成。 

2.1.2、密钥 服务端内部密钥

为了保证数据的真实性，开放平台管理员会提供appid和服务端内部密钥，用于保障数据的权限和真实可靠性。其中服务端内部密钥不可以泄露，必须存放在服务端。

请务必勿将密钥放在前端html、app或小程序中。密钥泄露后可能导致巨大影响，需及时重置或联系管理员重置。

2.1.3、事件名称及ID标识

事件名称 唯一标识 备注
心跳 ping 部分设备默认不开启心跳。
设备在线 online 设备在线
设备离线 offline 心跳周期计算后的结果，不一定准确。
火灾警报 fire
人形侦测 person
移动侦测 move
告警视频 alarm_video 一般是在录像成功后发送视频地址给
截图成功 get_image_success 截图下载地址放在消息的url字段
录视频成功 record_video_success 视频下载地址放在消息的url字段
未知 unknow 非上述协议内的消息，均认为是unknow
烟雾警报 smoke_alarm
设备低电 low_power_warning
设备休眠 sleep
设备复位 reset
离岗检测 leave_position_on_duty
电动车检测 car_invasion
设备录入/更新 device_upsert ["xxxx","ssss","www","33"]

三、报警与事件

3.1、接收设备上报事件消息

3.1.1、提供回调地址

https://example.com/DEMO_RESOURCE 

3.1.2、http 方法及模块事件发送的请求示例

POST

CURL
curl -XPOST -H "Content-Type: application/json; charset=utf-8" "https://example.com/DEMO_RESOURCE" -d '{
    "did": "DEMO_DEVICE_001",
    "e": "person",
    "t": 18902981762,
    "sign": "",
    "eventID": "37dy12di980",
    "url": "https://example.com/DEMO_RESOURCE",
    "nonce": 
}'

3.1.3、回调示例字段说明

字段 说明 备注
did 设备的唯一ID device_id、IMEI均能表示设备唯一编号，传值时至少传一个
e 事件的alias 参考“事件名称及ID标识”表
t 报警时间 服务器接收到设备报警时的时间戳。因设备的时间不一定准确，所以不是设备本身的时间。
sign 校验字段 通过算法得到一个字符串，并与此字段比较。相同则代表本次数据可靠。
eventID 事件id
url 资源地址，一般是图片或视频 有效期一般为一小时，需要及时下载到开发者的服务器。部分机型没有上报图片。运营前，请先调试设备后再投入使用。
sign 生成说明：

请参考：《生成sign的示例代码》

参数 传值 备注
DID 传设备的唯一ID，传DID 有传DID，则不需要再传IMEI。
IMEI 设备的IMEI，或传空字符串
vpOpenID 传前面提到的 open id
timestamp 报警时间，传 t 服务器接收到设备报警时的时间戳。因设备的时间不一定准确，所以不是设备本身的时间。
nonce 随机字符串，传8~12位
data 传 "e=${事件的alias}&alarmID=${alarmID}&cover=${cover}" e：取报警时间 
alarmID：取警报id 
cover：取图片地址 ，没有则传空字符串
服务端内部密钥 传前面提到的密钥 服务端内部密钥

四、其它api

4.1、获取告警截图

在告警发生时，一般会将图片地址跟随事件消息一并传给开发者服务器。建议在一小时内完成下载并保存到自己的服务器。

4.2、获取告警视频

在告警发生后，服务端完成视频录制时，会实时将视频发送给开发者服务器。建议在一小时内完成下载并保存到自己的服务器。