电梯控制协议

获取 Access Token (OAuth 2.0)

POST /v1/oauth2/token

您的系统需提供权限认证服务，支持 OAuth2 认证机制。客户端通过 client_credentials 授权类型获取访问令牌。

参数名	类型	必填	说明
grantType	string	是	授权类型，如 `client_credentials`
clientId	string	是	客户端标识符
clientSecret	string	是	客户端密钥

口诀请求参数

参数名	类型	说明
accessToken	string	访问令牌
tokenType	string	令牌类型
expiresIn	number	有效期（秒）

口诀响应参数

创建 WebSocket 连接

WEBSOCKET /v1/connect

Gausium 通过向 /v1/connect 接口发送请求，并附带 accessToken，与您的 WebSocket 服务建立连接。

wss://${您服务的域名}/v1/connect?accessToken=ACCESS_TOKEN

参数名	类型	必填	说明
accessToken	string	是	访问令牌（查询参数）

口诀查询参数

预约电梯

WEBSOCKET /v1/connect | type: V1_RESERVE

Gausium 通过 WebSocket 客户端向您的服务端发送“电梯预约”请求。预约成功后，机器人才能进行后续的呼叫和乘梯操作。

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳（毫秒）
liftId	string	是	电梯唯一标识
carId	string	是	轿厢标识
type	string	是	请求类型 `V1_RESERVE`
fromAreaId	string	是	出发区域标识
toAreaId	string	是	目的区域标识

口诀请求参数

参数名	类型	说明
code	number	返回码
msg	string	返回信息
data	object	数据内容

口诀响应参数

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29008	LIFT_FULLY_RESERVED	Elevator is fully reserved

口诀返回码

呼叫电梯到出发区域

WEBSOCKET /v1/connect | type: V1_CALL_FROM

Gausium 通过 WebSocket 客户端向您的服务端发送“呼叫电梯到出发区域”请求。如果呼叫成功，您应返回“呼叫成功”消息；如果呼叫失败，您应返回“呼叫失败”消息。

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳（毫秒级）
liftId	string	是	电梯唯一标识
carId	string	是	轿厢标识
type	string	是	请求类型 `V1_CALL_FROM`
fromAreaId	string	是	出发区域标识
toAreaId	string	是	目的区域标识

口诀请求参数

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b2",
  "timestamp": 1692448625002,
  "liftId": "1b3ace92-95e7-4d35-89a5-391c0ac8298e",
  "carId": "1001010",
  "type": "V1_CALL_FROM",
  "fromAreaId": "1000",
  "toAreaId": "2000"
}

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29009	LIFT_NOT_RESERVED	Elevator cannot be used without reservation

口诀返回码

呼叫电梯到目的区域

WEBSOCKET /v1/connect | type: V1_CALL_TO

Gausium 通过 WebSocket 客户端向您的服务端发送“呼叫电梯到目的区域”请求。如果呼叫成功，您应返回“呼叫成功”消息；如果呼叫失败，您应返回“呼叫失败”消息。

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳（毫秒级）
liftId	string	是	电梯唯一标识
carId	string	是	轿厢标识
type	string	是	请求类型 `V1_CALL_TO`
fromAreaId	string	是	出发区域标识
toAreaId	string	是	目的区域标识

口诀请求参数

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b2",
  "timestamp": 1692448625002,
  "liftId": "1b3ace92-95e7-4d35-89a5-391c0ac8298e",
  "carId": "1001010",
  "type": "V1_CALL_TO",
  "fromAreaId": "1000",
  "toAreaId": "2000"
}

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29009	LIFT_NOT_RESERVED	Elevator cannot be used without reservation

口诀返回码

取消电梯使用

WEBSOCKET /v1/connect | type: V1_CALL_CANCEL

机器人完成乘梯或者终止乘梯时，Gausium 通过 WebSocket 客户端向您的服务端发送“取消电梯使用”请求。如果取消成功，您应返回“取消成功”；如果取消失败，您应返回“取消失败”。

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳
liftId	string	是	电梯唯一标识
carId	string	是	轿厢标识
type	string	是	请求类型 `V1_CALL_CANCEL`
fromAreaId	string	是	出发区域标识
toAreaId	string	是	目的区域标识
reason	string	是	取消原因：`COMPLETED`（已完成）/ `TERMINATED`（被终止）

口诀请求参数

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b3",
  "timestamp": 1692448625003,
  "liftId": "1b3ace92-95e7-4d35-89a5-391c0ac8298e",
  "carId": "1001010",
  "type": "V1_CALL_CANCEL",
  "fromAreaId": "1000",
  "toAreaId": "2000",
  "reason": "COMPLETED"
}

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29009	LIFT_NOT_RESERVED	Elevator cannot be used without reservation

口诀返回码

请求电梯保持开门

WEBSOCKET /v1/connect | type: V1_OPEN_DOOR

当机器人进梯或出梯时，Gausium 通过 WebSocket 客户端向您的服务端发送“电梯保持开门”请求。若请求成功，您应返回“开门成功”消息，并保持电梯门开启；若请求失败，您应返回“开门失败”消息。

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳
liftId	string	是	电梯唯一标识，校验和当前会话电梯标识相同时才进行操作
carId	string	是	轿厢标识，校验和当前会话轿厢标识相同时才进行操作
areaId	string	是	区域标识，校验和当前会话出发/目的区域标识相同时才进行操作
type	string	是	请求类型 `V1_OPEN_DOOR`
duration	number	是	开门持续时间（秒）

口诀请求参数

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b4",
  "timestamp": 1692448625004,
  "liftId": "1b3ace92-95e7-4d35-89a5-391c0ac8298e",
  "carId": "1001010",
  "areaId": "1000",
  "type": "V1_OPEN_DOOR",
  "duration": 60
}

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29009	LIFT_NOT_RESERVED	Elevator cannot be used without reservation

口诀返回码

请求电梯关门

WEBSOCKET /v1/connect | type: V1_CLOSE_DOOR

当机器人完成进梯或出梯后，Gausium 通过 WebSocket 客户端向您的服务端发送“电梯关门”请求。若请求成功，您应返回“关门成功”消息，并关闭电梯门；若请求失败，您应返回“关门失败”消息。

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳
liftId	string	是	电梯唯一标识，校验和当前会话电梯标识相同时才进行操作
carId	string	是	轿厢标识，校验和当前会话轿厢标识相同时才进行操作
areaId	string	是	区域标识，校验和当前会话出发/目的区域标识相同时才进行操作
type	string	是	请求类型 `V1_CLOSE_DOOR`
delay	number	是	关门延迟时间（秒）

口诀请求参数

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b5",
  "timestamp": 1692448625005,
  "liftId": "1b3ace92-95e7-4d35-89a5-391c0ac8298e",
  "carId": "1001010",
  "areaId": "1000",
  "type": "V1_CLOSE_DOOR",
  "delay": 5
}

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29009	LIFT_NOT_RESERVED	Elevator cannot be used without reservation

口诀返回码

订阅电梯运行状态

WEBSOCKET /v1/connect | type: V1_LIFT_STATUS

Gausium 通过 WebSocket 客户端向您的服务端发送“订阅电梯运行状态”请求。若订阅成功，您应返回“订阅成功”消息，并在订阅有效期内，当电梯状态发生变化时推送最新状态；若订阅失败，您应返回“订阅失败”消息。

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳
liftIds	array	是	电梯唯一标识数组，最大长度 100
type	string	是	请求类型 `V1_LIFT_STATUS`
duration	number	是	订阅持续时间（秒）

口诀请求参数

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b6",
  "timestamp": 1692448625006,
  "liftIds": ["1b3ace92-95e7-4d35-89a5-391c0ac8298e", "2b3ace92-95e7-4d35-89a5-391c0ac82986c"],
  "type": "V1_LIFT_STATUS",
  "duration": 1200
}

状态推送参数

订阅成功后，电梯状态发生变化时，您的服务端会通过 WebSocket 推送以下数据：

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
liftId	string	是	电梯唯一标识
type	string	是	请求类型 `V1_LIFT_STATUS`
carId	string	是	电梯轿厢 ID
areaId	string	是	楼层区域标识
doorId	string	是	门标识
status	string	是	门状态：`OPENING` / `OPENED` / `CLOSING` / `CLOSED`
direction	string	是	电梯运行方向：`UP` / `DOWN` / `STOP`
timestamp	long	是	门状态时间戳
duration	int	条件	门状态持续时间（秒），门状态为 `OPENED` 时必须

口诀状态推送字段

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "liftId": "1b3ace92-95e7-4d35-89a5-391c0ac8298e",
  "type": "V1_LIFT_STATUS",
  "carId": "1001010",
  "areaId": "1000",
  "doorId": "1",
  "status": "OPENED",
  "direction": "UP",
  "timestamp": 1692448631000,
  "duration": 60
}

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29009	LIFT_NOT_RESERVED	Elevator cannot be used without reservation

口诀返回码

订阅电梯运行模式

WEBSOCKET /v1/connect | type: V1_LIFT_MODE

Gausium 通过 WebSocket 客户端向您的服务端发送“订阅电梯运行模式”请求。若订阅成功，您应返回“订阅成功”消息，并在订阅有效期内，当电梯可用状态发生变化时推送状态；若订阅失败，您应返回“订阅失败”消息。

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳
liftIds	array	是	电梯唯一标识数组，最大长度 100
type	string	是	请求类型 `V1_LIFT_MODE`
duration	number	是	订阅持续时间（秒）

口诀请求参数

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b7",
  "timestamp": 1692448625007,
  "liftIds": ["1b3ace92-95e7-4d35-89a5-391c0ac8298e", "2b3ace92-95e7-4d35-89a5-391c0ac82986c"],
  "type": "V1_LIFT_MODE",
  "duration": 1200
}

模式推送参数

订阅成功后，电梯可用状态发生变化时，您的服务端会通过 WebSocket 推送以下数据：

参数名	类型	必填	说明
sessionId	string	是	会话唯一标识
liftId	string	是	电梯唯一标识
type	string	是	请求类型 `V1_LIFT_MODE`
status	string	是	电梯可用状态：`AVAILABLE` / `UNAVAILABLE`
timestamp	long	是	当前时间戳
message	string	否	电梯不可用具体描述信息，如 `FIRE`

口诀模式推送字段

电梯可用时推送示例：

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "liftId": "1b3ace92-95e7-4d35-89a5-391c0ac8298e",
  "type": "V1_LIFT_MODE",
  "status": "AVAILABLE",
  "timestamp": 1692448633000
}

电梯不可用时推送示例：

{
  "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
  "liftId": "1b3ace92-95e7-4d35-89a5-391c0ac8298e",
  "type": "V1_LIFT_MODE",
  "status": "UNAVAILABLE",
  "timestamp": 1692448633000,
  "message": "FIRE"
}

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29009	LIFT_NOT_RESERVED	Elevator cannot be used without reservation

口诀返回码

获取电梯配置

GET /v1/lift/config

您提供电梯 ID 列表，Gausium 通过调用该接口查询并获取电梯配置信息。此接口为标准 HTTP GET 请求，需在请求头中携带 authorization 令牌。

参数名	类型	必填	说明
requestId	string	是	请求唯一标识
timestamp	number	是	请求时间戳
liftIds	array	是	电梯唯一标识数组，最大长度 100
type	string	是	请求类型 `V1_LIFT_CONFIG`

口诀查询参数

curl --location --globoff 'https://${您服务的域名}/v1/lift/config?requestId=d6718b31-84b2-46a3-8438-898284a5f4b7&timestamp=1692448625007&liftIds=["1b3ace92-95e7-4d35-89a5-391c0ac8298e","2b3ace92-95e7-4d35-89a5-391c0ac82986c"]&type=V1_LIFT_CONFIG' \
--header 'authorization: ${accessToken}'

响应数据结构

参数名	类型	说明
code	number	返回码
msg	string	返回信息
data	array	电梯配置列表

口诀响应参数

参数名	类型	说明
liftId	string	电梯唯一标识
displayName	string	电梯显示名称
destinations	array	目的地列表
cars	array	轿厢列表

口诀data 数组元素

参数名	类型	说明
areaId	string	区域标识
floorId	string	楼层标识
displayName	string	楼层显示名称
doorId	number	门标识

口诀destinations 数组元素

参数名	类型	说明
carId	string	轿厢标识
doors	array	门列表

口诀cars 数组元素

{
  "code": 0,
  "msg": "SUCCESS",
  "data": [{
    "liftId": "d6718b31-84b2-46a3-8438-898284a5f4b7",
    "displayName": "电梯1",
    "destinations": [
      {"areaId": "1000", "floorId": "1", "displayName": "-1F", "doorId": 1},
      {"areaId": "2000", "floorId": "2", "displayName": "11F", "doorId": 1},
      {"areaId": "3000", "floorId": "3", "displayName": "2F", "doorId": 2}
    ],
    "cars": [
      {"carId": "1001010", "doors": [1, 2]},
      {"carId": "1001011", "doors": [1, 2]}
    ]
  }]
}

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable

口诀返回码

通用响应格式

所有 WebSocket 请求均遵循统一的响应格式，包含 code、msg 和 data 三个字段。

成功响应

{
  "code": 0,
  "msg": "SUCCESS",
  "data": {
    "timestamp": 1692448632000,
    "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
    "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b7"
  }
}

错误响应

{
  "code": 29001,
  "msg": "NO_LIFT_AVAILABLE",
  "data": {
    "timestamp": 1692448632000,
    "sessionId": "f6518b31-84b2-46a3-8438-898284a5f7c9",
    "requestId": "d6718b31-84b2-46a3-8438-898284a5f4b7"
  }
}

通用返回码

以下为所有接口共用的返回码定义：

返回码	说明	提示语
0	OK	Operation completed successfully
29001	NO_LIFT_AVAILABLE	Elevator is unavailable
29008	LIFT_FULLY_RESERVED	Elevator is fully reserved
29009	LIFT_NOT_RESERVED	Elevator cannot be used without reservation

口诀全局返回码

✓推荐做法

先通过 OAuth 2.0 获取 accessToken 再建立 WebSocket 连接
在每次电梯操作前先发送 V1_RESERVE 预约请求
机器人完成乘梯后务必发送 V1_CALL_CANCEL（reason 为 COMPLETED）释放电梯资源
订阅状态/模式时设置合理的 duration 值，到期后重新订阅
处理所有返回码，特别是 29001（电梯不可用）和 29009（未预约）

✗不推荐

不要跳过预约步骤直接呼叫电梯
不要忘记在乘梯结束后取消电梯占用
不要将 accessToken 硬编码，应定期刷新
不要忽略 WebSocket 连接断开后的重连逻辑

⚠常见误区

开关门请求中的 liftId、carId、areaId 必须与当前会话一致，否则操作不会执行
duration 字段在 V1_OPEN_DOOR 中表示开门持续秒数，在 V1_CLOSE_DOOR 中 delay 表示关门延迟秒数，不要混淆
状态推送中 duration 字段仅在门状态为 OPENED 时必须填写

完整实现电梯控制全生命周期：认证 -> 连接 -> 预约 -> 呼叫 -> 开门 -> 关门 -> 取消，并正确处理状态订阅和异常返回码