本文档详细介绍TUTK SDK V4版本设备端消息推送（带图片上传）的开发规范，包括HTTP请求参数、接口调用方式、测试示例及错误码说明，助力开发者快速实现设备端事件推送及图片上传能力。
一、说明
设备端通过 HTTP/HTTPS 协议向服务器推送事件（如移动侦测、门铃触发），支持纯文本事件和图片上传。推送配置（URL、Token）从 APP 端获取，格式如下：
推送配置格式示例
{
"func": "DmPush",
"args": [
{
"url": "https://host:port/hestia/v4/dm/create/event",
"token": "Token"
}
]
}
注意：设备端需将 APP 下发的 URL 和 Token 持久化存储，推送时直接读取使用。
二、HTTP 请求
（一）请求基础信息
| 项目 | 说明 |
|---|---|
| 请求 URL | 从 APP 端获取（固定格式：https://host:port/hestia/v4/dm/create/event） |
| 请求方法 | POST（推荐）/ GET |
| 请求头部 | Authorization: Bearer <token>（token 从 APP 端获取） 不上传图片：Content-Type: application/json 上传图片：Content-Type: multipart/form-data |
（二）请求参数说明
| 参数类型 | 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|---|
| 必选参数 | udid | String | 是 | 40位字符串（20位 certkey + 20位设备 UID 拼接） |
| 必选参数 | starttime | int64 | 是 | 事件开始的 Unix 时间戳，单位：秒 |
| 必选二选一参数 | type | String | 二选一 | 事件类型字符串（如 "motionSensor"、"doorbell"） → 若 type=doorbell，服务器自动转换 tag 为： {
"tag": [
{
"sensor": "oldDesign",
"props": [
{
"type": "doorbell"
}
]
}
]
} |
| tag | String | 二选一 | base64 加密后的事件标识数据（符合 RFC 4648 标准），具体请参考：tag格式定义 | |
| 可选参数 | notify | String | 否 | 值为 "silent" 时跳过推送通知 |
| upload | File | 否 | 图片文件（仅上传图片时需带，格式：upload=@本地图片路径） → 限制：图片大小 ≤ 300KB，无格式限制（推荐 JPG/PNG） |
（三）响应说明
| 项目 | 说明 |
|---|---|
| 状态码 | 200 成功 400 参数错误 401 认证失败 |
| 响应体 result | 空字符串（成功）、失败原因描述（失败） |
| 错误码 | -3012：token 失效（设备已被 APP 移除） |
三、测试示例（curl）
（一）纯事件触发（不上传图片）
请求示例（curl）
curl -XPOST \
-H 'Authorization: Bearer 63bbd75e6af944f202f9adef' \
-H 'Content-Type: application/json' \
-d '{
"udid": "TUTKKALAY20000000000FVUA9T3WKFZMUHPGY1Y1",
"starttime": 1717654305,
"tag": "W3sic2Vuc29yIiA6ICJtb3Rpb24iLCJwcm9wcyIgOlt7InR5cGUiIDogIm1vdGlvblNlbnNvciJ9XX1d"
}' \
https://asia-dm.kalay.us/hestia/v4/dm/create/event
（二）事件触发 + 图片上传
请求示例（curl）
curl -XPOST \
-H 'Authorization: Bearer 63bbd75e6af944f202f9adef' \
-F 'upload=@upload_image.jpg' # 本地图片路径（相对/绝对路径均可）
-F 'tag=W3sic2Vuc29yIiA6ICJtb3Rpb24iLCJwcm9wcyIgOlt7InR5cGUiIDogIm1vdGlvblNlbnNvciJ9XX1d' \
-F 'starttime=1720767184' \
-F 'udid=TUTKKALAY20000000000FVUA9T3WKFZMUHPGY1Y1' \
https://asia-dm.kalay.us/hestia/v4/dm/create/event
注意事项
1. 测试前需替换示例中的 token、udid、图片路径等为实际有效值；
2. 图片上传时需确保文件大小不超过 300KB，否则会返回 400 参数错误；
3. 若返回 401 认证失败，需检查 token 是否有效或设备是否被 APP 移除。
