机器人信息查询

机器人信息服务提供 6 个接口，覆盖机器人列表查询、状态报告、单台与批量状态获取。包含 V1 和 V2 两代接口，V2 提供更详细的 S 系列机器人设备状态。 Base URL: https://openapi.gs-robot.com 所有接口均需 OAuth Bearer Token 认证。

列出机器人

GET /v1alpha1/robots

分页获取当前账号下的机器人列表，支持按关系类型过滤。

请求参数 (Query)

参数名	类型	必填	说明
page	int	否	页码
pageSize	int	否	每页数量
relation	string	否	关系类型，如 `contract`

口诀分页 + 关系过滤

响应参数

参数名	类型	说明
robots	array	机器人列表
robots[].serialNumber	string	序列号
robots[].name	string	名称
robots[].displayName	string	显示名称
robots[].modelFamilyCode	string	型号系列代码
robots[].modelTypeCode	string	型号类型代码
robots[].online	boolean	在线状态
robots[].hardwareVersion	string	硬件版本
robots[].softwareVersion	string	软件版本
page	int	当前页码
pageSize	int	每页数量
total	string	总数

口诀列表 + 分页元数据

{
  "robots": [
    {
      "serialNumber": "GS101-00A0-A7L-0000",
      "name": "清洁机器人-A",
      "displayName": "大厅清洁机器人",
      "modelFamilyCode": "GS101",
      "modelTypeCode": "GS101-A",
      "online": true,
      "hardwareVersion": "1.0.0",
      "softwareVersion": "2.3.1"
    }
  ],
  "page": 1,
  "pageSize": 10,
  "total": "1"
}

列出机器人状态报告

GET /v1alpha1/robots/{robotId}/statusReports

查询指定机器人在给定时间范围内的在线/离线时长报告。

请求参数 (Query)

参数名	类型	必填	说明
timeSpan.startTime.seconds	number	是	开始时间戳（秒）
timeSpan.endTime.seconds	number	是	结束时间戳（秒）
utcOffset.seconds	number	否	UTC 偏移（秒）

口诀时间范围 + 时区偏移

响应参数

参数名	类型	说明
reports	array	报告列表
reports[].date	string	日期（YYYY-MM-DD）
reports[].onlineDuration	string	在线时长（秒）
reports[].offlineDuration	string	离线时长（秒）

口诀按日汇总在线/离线时长

{
  "reports": [
    {
      "date": "2026-06-01",
      "onlineDuration": "43200",
      "offlineDuration": "43200"
    }
  ]
}

V1 获取机器人状态

GET /v1alpha1/robots/{serialNumber}/status

获取单台机器人的实时状态，包含位置、任务、电量、急停等信息。

响应参数

参数名	类型	说明
serialNumber	string	序列号
name	string	名称
position.latitude	number	纬度
position.longitude	number	经度
position.angle	number	角度
taskState	string	任务状态
online	boolean	在线状态
speed	number	速度
battery.charging	boolean	充电状态
battery.percentage	number	电量百分比
emergencyStop	boolean	急停状态
localizationInfo	object	定位信息
device	object	设备状态

口诀位置 + 任务 + 电量 + 设备

{
  "serialNumber": "GS101-00A0-A7L-0000",
  "name": "清洁机器人-A",
  "position": {
    "latitude": 31.2304,
    "longitude": 121.4737,
    "angle": 90.0
  },
  "taskState": "IDLE",
  "online": true,
  "speed": 0.0,
  "battery": {
    "charging": false,
    "percentage": 85.0
  },
  "emergencyStop": false
}

V1 批量获取机器人状态

GET /v1alpha1/robots/-/status:batchGet

一次请求获取多台机器人的实时状态，序列号以逗号分隔传入。

请求参数 (Query)

参数名	类型	必填	说明
names	string	是	机器人序列号（多个用逗号分隔）

口诀逗号分隔的序列号列表

响应参数

参数名	类型	说明
robotStatuses	array	机器人状态列表（结构同 V1 获取机器人状态）

口诀批量返回，结构复用单台接口

# 批量查询示例
GET /v1alpha1/robots/-/status:batchGet?names=GS101-00A0-A7L-0000,GS101-00A0-A7L-0001

V2 获取 S 机器人状态

GET /openapi/v2alpha1/s/robots/{serialNumber}/status

V2 版本的单台机器人状态查询，返回与 V1 相同的基础字段，额外包含更详细的设备状态信息。适用于 S 系列机器人。

响应参数

响应结构同 V1 获取机器人状态，额外包含更详细的设备状态信息。

V2 批量获取 S 机器人状态

GET /openapi/v2alpha1/s/robots/*/status:batchGet

V2 版本的批量机器人状态查询。与 V1 批量接口不同，此接口通过 请求体 (Body) 传递序列号。

请求参数 (Body)

参数名	类型	必填	说明
names	string	是	机器人序列号

口诀Body 传参，非 Query

响应参数

参数名	类型	说明
robotStatus	array	机器人状态列表

口诀字段名为 robotStatus（非 robotStatuses）

接口对照总览

接口	方法	路径	版本	传参方式
列出机器人	GET	/v1alpha1/robots	V1	Query
状态报告	GET	/v1alpha1/robots/{robotId}/statusReports	V1	Query
单台状态	GET	/v1alpha1/robots/{serialNumber}/status	V1	Path
批量状态	GET	/v1alpha1/robots/-/status:batchGet	V1	Query
S 单台状态	GET	/openapi/v2alpha1/s/robots/{serialNumber}/status	V2	Path
S 批量状态	GET	/openapi/v2alpha1/s/robots/*/status:batchGet	V2	Body

口诀6 接口 = 列表1 + 报告1 + 状态4（V1单/批 + V2单/批）

✓推荐做法

新项目优先使用 V2 接口获取更丰富的设备状态
批量查询代替循环单台查询，减少请求次数
使用分页参数控制列表接口的返回量

✗不推荐

混淆 V1 和 V2 批量接口的传参方式（Query vs Body）
忽略 total 字段为 string 类型的事实
在高频轮询场景下不做请求合并

⚠常见误区

V2 批量接口响应字段为 robotStatus（单数），而 V1 为 robotStatuses（复数）
状态报告接口的时长字段（onlineDuration/offlineDuration）为 string 类型（秒），需自行转换

接口调用返回预期数据结构，分页和批量查询工作正常