本文檔詳細(xì)介紹TUTK SDK V4版本設(shè)備端消息推送（帶圖片上傳）的開發(fā)規(guī)范，包括HTTP請(qǐng)求參數(shù)、接口調(diào)用方式、測(cè)試示例及錯(cuò)誤碼說明，助力開發(fā)者快速實(shí)現(xiàn)設(shè)備端事件推送及圖片上傳能力。
一、說明
設(shè)備端通過 HTTP/HTTPS 協(xié)議向服務(wù)器推送事件（如移動(dòng)偵測(cè)、門鈴觸發(fā)），支持純文本事件和圖片上傳。推送配置（URL、Token）從 APP 端獲取，格式如下：
推送配置格式示例
{
"func": "DmPush",
"args": [
{
"url": "https://host:port/hestia/v4/dm/create/event",
"token": "Token"
}
]
}
注意：設(shè)備端需將 APP 下發(fā)的 URL 和 Token 持久化存儲(chǔ)，推送時(shí)直接讀取使用。
二、HTTP 請(qǐng)求
（一）請(qǐng)求基礎(chǔ)信息
| 項(xiàng)目 | 說明 |
|---|---|
| 請(qǐng)求 URL | 從 APP 端獲?。ü潭ǜ袷剑?span id="4utls6qs" class="code-inline">https://host:port/hestia/v4/dm/create/event） |
| 請(qǐng)求方法 | POST（推薦）/ GET |
| 請(qǐng)求頭部 | Authorization: Bearer <token>（token 從 APP 端獲?。?br/>不上傳圖片：Content-Type: application/json 上傳圖片：Content-Type: multipart/form-data |
（二）請(qǐng)求參數(shù)說明
| 參數(shù)類型 | 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|---|
| 必選參數(shù) | udid | String | 是 | 40位字符串（20位 certkey + 20位設(shè)備 UID 拼接） |
| 必選參數(shù) | starttime | int64 | 是 | 事件開始的 Unix 時(shí)間戳，單位：秒 |
| 必選二選一參數(shù) | type | String | 二選一 | 事件類型字符串（如 "motionSensor"、"doorbell"） → 若 type=doorbell，服務(wù)器自動(dòng)轉(zhuǎn)換 tag 為： {
"tag": [
{
"sensor": "oldDesign",
"props": [
{
"type": "doorbell"
}
]
}
]
} |
| tag | String | 二選一 | base64 加密后的事件標(biāo)識(shí)數(shù)據(jù)（符合 RFC 4648 標(biāo)準(zhǔn)），具體請(qǐng)參考：tag格式定義 | |
| 可選參數(shù) | notify | String | 否 | 值為 "silent" 時(shí)跳過推送通知 |
| upload | File | 否 | 圖片文件（僅上傳圖片時(shí)需帶，格式：upload=@本地圖片路徑） → 限制：圖片大小 ≤ 300KB，無格式限制（推薦 JPG/PNG） |
（三）響應(yīng)說明
| 項(xiàng)目 | 說明 |
|---|---|
| 狀態(tài)碼 | 200 成功 400 參數(shù)錯(cuò)誤 401 認(rèn)證失敗 |
| 響應(yīng)體 result | 空字符串（成功）、失敗原因描述（失敗） |
| 錯(cuò)誤碼 | -3012：token 失效（設(shè)備已被 APP 移除） |
三、測(cè)試示例（curl）
（一）純事件觸發(fā)（不上傳圖片）
請(qǐng)求示例（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
（二）事件觸發(fā) + 圖片上傳
請(qǐng)求示例（curl）
curl -XPOST \
-H 'Authorization: Bearer 63bbd75e6af944f202f9adef' \
-F 'upload=@upload_image.jpg' # 本地圖片路徑（相對(duì)/絕對(duì)路徑均可）
-F 'tag=W3sic2Vuc29yIiA6ICJtb3Rpb24iLCJwcm9wcyIgOlt7InR5cGUiIDogIm1vdGlvblNlbnNvciJ9XX1d' \
-F 'starttime=1720767184' \
-F 'udid=TUTKKALAY20000000000FVUA9T3WKFZMUHPGY1Y1' \
https://asia-dm.kalay.us/hestia/v4/dm/create/event
注意事項(xiàng)
1. 測(cè)試前需替換示例中的 token、udid、圖片路徑等為實(shí)際有效值；
2. 圖片上傳時(shí)需確保文件大小不超過 300KB，否則會(huì)返回 400 參數(shù)錯(cuò)誤；
3. 若返回 401 認(rèn)證失敗，需檢查 token 是否有效或設(shè)備是否被 APP 移除。
