推送服务 · 高仙机器人开放平台

事件推送

POST 回调 URL（由客户注册提供）

当机器人发生事件（告警或恢复）时，平台将事件信息推送至已注册的回调地址。messageTypeId 值为 1 表示事件推送。

推送参数

参数名	类型	说明
appId	string	鉴权标识
messageTypeId	int	推送类型（1 = 事件推送）
productId	string	机器人序列号
messageId	string	全局唯一消息 ID
traceId	string	链路追踪 ID
messageTimestamp	long	推送时间戳（毫秒）
payload	object	业务数据

口诀推送外层包含鉴权、消息标识和业务负载三部分

payload 字段

参数名	类型	说明
serialNumber	string	机器人序列号
modelTypeCode	string	机器人型号
content	object	事件内容

口诀payload 标识机器人身份和事件内容

payload.content 字段

参数名	类型	说明
incidentId	string	事件 ID
incidentCode	string	事件代码
incidentName	string	事件名称
incidentLevel	string	事件级别（H0-H7）
incidentStatus	int	状态（1 = 报警，0 = 恢复）
startTime	string	开始时间（ISO 8601 格式）
endTime	string	结束时间（ISO 8601 格式）
taskId	string	任务 ID

口诀content 描述事件的完整生命周期：标识、级别、状态和时间

{
  "appId": "your-app-id",
  "messageTypeId": 1,
  "productId": "GS101-00A0-A7L-0000",
  "messageId": "msg-uuid-001",
  "traceId": "trace-uuid-001",
  "messageTimestamp": 1704067200000,
  "payload": {
    "serialNumber": "GS101-00A0-A7L-0000",
    "modelTypeCode": "GS101",
    "content": {
      "incidentId": "inc-001",
      "incidentCode": "E1001",
      "incidentName": "急停按钮被按下",
      "incidentLevel": "H2",
      "incidentStatus": 1,
      "startTime": "2024-01-01T12:00:00Z",
      "endTime": "",
      "taskId": "task-001"
    }
  }
}

任务报告推送

POST 回调 URL（由客户注册提供）

当机器人完成任务后，平台将任务报告推送至已注册的回调地址。推送外层参数结构与事件推送相同，messageTypeId 为任务报告对应的类型值。

推送参数

推送外层参数与事件推送一致（appId、messageTypeId、productId、messageId、traceId、messageTimestamp、payload），其中 messageTypeId 为任务报告类型。

payload.taskReport 字段

参数名	类型	说明
taskId	string	任务 ID
startTime	long	开始时间
endTime	long	结束时间
cleaningArea	number	清洁面积
batteryStart	number	开始电量
batteryEnd	number	结束电量
consumables	object	消耗品状态

口诀任务报告包含时间范围、清洁面积、电量变化和消耗品信息

{
  "appId": "your-app-id",
  "messageTypeId": 2,
  "productId": "GS101-00A0-A7L-0000",
  "messageId": "msg-uuid-002",
  "traceId": "trace-uuid-002",
  "messageTimestamp": 1704070800000,
  "payload": {
    "taskReport": {
      "taskId": "task-001",
      "startTime": 1704067200000,
      "endTime": 1704070800000,
      "cleaningArea": 1500.5,
      "batteryStart": 95,
      "batteryEnd": 42,
      "consumables": {}
    }
  }
}

✓推荐做法

注册回调 URL 后验证连通性，确保平台能成功推送
使用 messageId 做幂等处理，避免重复消费
利用 traceId 进行全链路追踪和问题排查
对 incidentStatus 的报警和恢复事件成对处理

✗不推荐

不要忽略消息签名验证（appId 鉴权）
不要在回调处理中执行耗时操作，应异步处理后快速返回
不要假设推送顺序与事件发生顺序一致

⚠常见误区

回调 URL 不可达时平台可能重试，未做幂等会导致重复处理
事件推送的 endTime 在告警未恢复时可能为空字符串，需做空值判断

回调接口应在 3 秒内返回 200 状态码，超时或非 200 响应将触发重试机制