Skip to main content

常见问题

本页汇总 V3 接口接入过程中的高频问题。先看V3 统一错误码能解决大部分失败场景；本页侧重「为什么这样设计」「怎么改请求」以及从 V1/V2 迁移时的差异。

凭证与认证​

1. 如何成为开发者并创建 AccessKey？​

账号注册与凭证申请在各接口版本之间完全一致。AccessKey 凭证本身只区分 V1 与 V3 两个版本，没有 V2 版本；V2 接口属于旧版 OpenAPI 体系，使用 V1 版本 AccessKey 换取的令牌即可调用。完整步骤统一维护在快速开始：

  1. 邀请注册高仙开发者：组织内邀请，或由管理员在 IAM 客户中心代管理其他组织。
  2. 激活开发者账号：按激活邮件完成激活。
  3. 创建 AccessKey：在开发者中心「我的 AccessKey」创建，同时获得 AccessKeyID、AccessKeySecret、ClientID 和 ClientSecret。
应用管理已停止使用

原「应用管理」不再用于创建应用。新建 AccessKey 时系统会自动生成应用信息，无需再单独创建应用。

2. V1 的 AccessKey 能直接调 V3 接口吗？​

可以。V1 AccessKey 可以在开发者中心升级到 V3，但升级后 ClientID 仍为空值，需要继续使用原「应用管理」中的 ClientID。新建 V3 AccessKey 才会一次性下发 AccessKeyID、AccessKeySecret、ClientID 和 ClientSecret 四项凭证。

3. access_token 多久过期？需要每次调用前重新获取吗？​

默认有效期 24 小时。不要在每次业务调用前重新获取令牌，应按返回的 expires_in 提前刷新。令牌过期后使用 refresh_token 调用刷新 OAuth 令牌，无需重新授权。

4. 一直返回 110002，但令牌刚拿到？​

按以下顺序检查：

  1. Authorization 头的值是否为 Bearer {access_token}，Bearer 与令牌之间是一个空格。
  2. 是否把 AccessKeySecret 当成了 access_token。两者不能互换。
  3. 令牌是否来自当前环境。测试环境令牌不能调生产环境。
  4. 是否有网关或代理改写了 Authorization 头。

5. 返回 110003 无权限，但令牌是有效的？​

110003 表示认证通过但没有资源权限，最常见原因是请求里的 robotSn 没有绑定到当前账号。先用查询机器人列表确认该机器人是否在当前账号的授权范围内。

6. AccessKeySecret 丢了还能找回吗？​

看不到历史明文，但可以恢复使用：在开发者中心「我的 AccessKey」对该条目执行下载Secret重新下载，或更新Secret生成新密钥。更新后旧 Secret 立即失效，需要同步更新服务端配置。

请求与响应​

7. HTTP 状态码是 200，但接口明明失败了？​

这是 V3 的约定。业务错误统一返回 HTTP 200，真实结果在响应体的 code 字段。请始终解析 code，code = 0 才是成功。非 200 的 HTTP 状态只在网关层拦截时出现。

8. 返回 100003 参数错误，但 msg 看不出哪个字段错了？​

msg 是给人看的英文提示，不保证精确到字段。建议按顺序核对：

  1. 必填字段是否都传了，字段名大小写是否一致。
  2. 枚举字段是否用了接口页列出的取值。
  3. 单次数组长度是否超过接口页标注的上限。
  4. 数字字段是否误传成了字符串。

9. 返回 100026 限流怎么办？​

降低并发，按指数退避重试，不要立即密集重试。批量场景建议串行化或分批提交。

10. 反馈问题时提供什么信息最快定位？​

至少提供：traceId、调用的接口路径、请求时间（精确到分钟）、请求体（脱敏后）。traceId 能直接对应云端日志，比截图更有效。

11. 分页上限是多少？V1/V2 的 200 还适用吗？​

不适用。V3 的单页上限统一是 100，V1/V2 时代的 200 不再生效。常用取值：

场景上限
V3 分页接口 pageSize1 ~ 100
状态快照 robotSnList单次最多 100 台
列表类过滤 robotSnList单次最多 100 台

超出上限通常返回 100003。

12. 分页参数名为什么有些接口是 pageNumber，有些是 page？​

V3 大部分分页接口使用 pageNumber / pageSize，但任务报告分页接口沿用旧版命名 page / pagesize（注意是全小写）。这是历史字段兼容的结果，不是文档笔误。请以每个接口页的字段表为准，不要跨接口套用。

13. V3 接口的域名是什么？​

V3 接口统一以 /openapi/v3/ 开头，host 随环境不同，请以各接口页 curl 示例中的 host 为准。

V1/V2 使用的 https://openapi.gs-robot.com/ 不能直接替换成 V3 路径，两者是不同服务。

机器人与状态​

14. 状态快照是最新的吗？​

不是。状态数据非实时更新，最大延迟约 30 秒。不要用快照的坐标做实时避障或安全判断，也不要基于过期状态下发指令。

如果业务上需要更强的确定性（例如先判断任务是否结束再下发下一条），建议把等待窗口放宽到 60 秒并配合任务状态复核。

15. 控制机器前要不要先取一次状态？​

要。 下发指令前应先获取机器人当前状态，再基于最新状态决定指令内容。用两小时前的状态去发指令，机器人的实际位置和状态可能已经变化，存在安全风险。

16. 机器人离线时，为什么状态字段是空的，坐标是 0？​

离线状态下电量、当前任务、地图、位置等运行字段可能缺失或使用接口约定的默认值。坐标还需要同时满足三个条件才能填充：机器人已完成定位、存在可用网格坐标、地图元数据完整。坐标为 0 不代表机器人位于原点，不要据此做位置纠偏。

17. workState 是什么？为什么没有 V1 的 taskState？​

V3 状态快照返回 workState，它是机器人工作状态码的原始数值，直接透传，不在云端做二次转换，且仅在线时返回。

V1 的 taskState（空闲 / 执行中 / 任务暂停 / 其他）不属于 V3 契约，不能照搬到 V3 字段上。如果业务需要判断「任务是否在跑」，建议改用任务实例 taskInstanceId、taskName 与任务报告接口组合判断。

18. 位置坐标的 angle、gridPosition、worldPosition 怎么读？​

三者描述的是同一位置的三种表达：

字段含义
position.angle机器人朝向角度（度）。
position.gridPosition栅格坐标 x / y，整数格点。
position.worldPosition.position世界坐标 x / y / z，浮点，单位与地图 resolution 相关。
position.mapInfo地图元数据：gridWidth、gridHeight、originX、originY、resolution。

需要把栅格坐标换算成世界坐标时，必须同时用到 mapInfo 的原点与分辨率，只用 gridPosition 无法还原真实位置。

19. 返回 210002 机器人离线？​

该指令要求机器人在线才能下发。等机器人重新上线后重试，或先用状态快照确认在线状态再下发。

20. 返回 210000 不支持？​

说明机器人没有声明支持目标任务或指令。常见原因是机型能力不符，或软件版本低于 AIO 1.6。V3 接口只确保兼容 AIO 1.6 及以上版本。可先用查询机器人组合任务能力确认机器人实际支持范围。

21. 部署了梯控的现场，如何知道机器人当前在几楼？​

V3 没有独立的「楼层」字段。通用做法是在地图命名中体现楼栋与楼层，通过状态快照的 currentMapName / currentMapId 间接得到楼层信息。建议制定统一的地图命名规范，而不是在对接侧维护楼层映射表。

22. 怎么判断机器人属于 M 线还是 S 线？​

看 modelFamilyCode：

modelFamilyCode归属
s、swS 线
40、50、omineM 线
75L 线，能力与调用方式按 M 线的接口处理

V3 已经不需要按 M / S 选择不同接口，同一套接口对全系机型生效，modelFamilyCode 只用于判断机型能力差异（例如支持的工作模式、任务子项类型）。无法归类的型号按 S 线处理。

23. 充电中或低功耗时能下发指令吗？​

分两种情况，不要一概而论：

  • 控制类指令（导航、暂停、继续、停止等）：机器人在充电桩上充电时无法执行，需要先让机器人离桩。
  • 清洁任务：非低电量且在充电时可以创建，机器人在具备条件后再执行；低电量时应先充电。

低功耗状态不影响接收指令，但实际执行仍取决于电量和任务状态。

24. cleaningMode 的可用取值从哪获取？​

不要写死枚举，取机器人实际上报的能力。V3 用查询任务工作模式按 robotSn 获取，返回的 mode、strength、subType、type 组合成任务里的工作模式。

任务报告里的 cleaningMode 是执行时实际使用的工作模式名称，用于回看，不要拿它反推可选范围。

25. 车端多久上报一次位置？​

机器人移动中约 1 秒一次，静止约 3 秒一次。但状态快照接口不是按这个频率更新，它按更低频率聚合，最大延迟约 30 秒。需要贴近实时的位置跟踪时，不要依赖快照轮询。

地图​

26. mapId 该传哪个值？​

传地图的 localMapUuid。如果返回 230010，说明传入的 mapId 不是 localMapUuid，或两者不一致。先用查询机器人地图取得正确的标识。

27. 返回 220002 地图资源不属于指定地图？​

分区、路径、点位都必须来自同一张地图。跨地图混用资源会触发该错误，请先确认资源查询结果中的地图标识与请求一致。

28. 只查到自动分区，我框选的区域怎么查？​

V3 的分区查询返回的是自动分区。页面上手工「框选」的区域不属于分区，体现在任务资源的 paths 中：调用查询任务资源，取 data.maps[].paths。

需要按框选区域执行时，用排班任务承载该资源，而不是按分区下发临时任务。

29. 地图坐标或画布是空的？​

地图的路径与坐标数据依赖车端主动上报到云端。较早的软件版本不提供这条上报链路，只能返回地图元数据（尺寸、分辨率等），paths / regions 以及画布内容会为空。

先确认机器人软件版本是否支持上报；不支持时需要升级车端版本，这不是接口参数问题，改参数无法解决。

任务与排班​

30. 下发任务该调哪个 V3 接口？​

V3 按任务类型拆分，不再用一个通用 command 接口：

场景接口
执行一次性的组合任务开始组合任务
执行已保存的长期组合任务定义先在任务定义管理中维护定义，再启动
按日历周期执行标准排班或简化排班
导航 / 暂停 / 继续 / 停止指令操作

V1 时代按机型与软件版本选择不同路径的做法在 V3 不再适用，统一按任务类型选择。

31. 创建组合任务成功了，为什么机器人没有动？​

创建组合任务只是保存任务定义，不会触发执行。需要再调用开始组合任务，并保存返回的 requestId 用于查询执行结果。

32. 返回 230014 或 230015？​

230014 表示任务运行时或任务子项不存在，常见于用已结束的 taskId 继续下发指令。230015 表示任务状态不允许当前指令，或任务版本已变化。建议重新查询任务状态后再决定下一步，不要盲目重试同一条指令。

33. 返回 230013 排班开始日期早于当前日期？​

排班不允许从过去开始。请把开始日期调整为今天或之后；跨时区场景要注意传入时间按现场时区解释。

34. 返回 230019 充电点未指定？​

当前地图存在多个充电点，但请求没有指定目标。先调用查询充电桩点位列表，再在请求中带上具体充电点。

35. 任务启动失败，返回 20101000xx 这类 10 位码？​

这是车端业务码，不属于云端六位错误码，统一在任务启动失败错误代码中查询。云端最外层 code 永远按 V3 号段返回。

36. 机器人正在执行任务时，再下发一个任务会怎样？​

V3 没有任务排队机制。同一台机器人同一时刻只执行一个任务，新任务与当前任务冲突时返回 230015（任务状态或版本冲突），不会自动排队等前一个任务结束。

调用顺序固定为：先停止当前任务并确认结果，再下发新任务。是否允许高优先级任务顶替当前任务由车端版本决定，不要依赖该行为设计业务流程。

37. 跨地图导航需要满足什么条件？​

需要同时满足三个条件：目标地图与当前地图连通、属于同一站点、站点已绑定电梯。任一条件不满足时，指令可能下发成功但在执行阶段失败。

下发前先用查询机器人地图确认 mapId，并确认地图之间的通行关系。

任务报告​

38. V3 支持按时间段查任务报告吗？​

支持。 这是相对 V1/V2 的增强：V1/V2 不支持按时间段查询，而 V3 的分页查询任务报告提供 endTimeMin / endTimeMax 两个参数，按任务结束时间过滤。

注意两点：

  1. 时间格式为 yyyy-MM-dd HH:mm:ss，且是机器人本地时间，不是 UTC。
  2. robotSn 为必填，不能用一次请求跨机器人聚合。

39. 为什么今天的任务报告查不到？​

任务报告上报需要机器人联网。若机器人网络不佳或离线，报告可能无法在当天送达。例如 6 月 1 日执行任务、6 月 2 日设备才联网上传，那么 6 月 1 日的报告要到 6 月 2 日之后才能查到。

排查顺序：确认机器人在线 → 用较宽的时间范围重查 → 确认查询时间用的是机器人本地时间。

40. 任务报告的地图图片怎么取？​

先用分页查询任务报告拿到任务报告标识，再用查询任务报告地图图片取图片。

V1 的 GenerateRobotTaskReportPng 与 ListRobotTaskReports 属于不同接口体系，V3 不要混用；languageCode 需要 IETF 语言标签（如 zh-CN、en-US）。

41. durationSeconds 是 0，是不是算错了？​

不是。startTime 与 endTime 描述任务的时间区间，而 durationSeconds 只统计真正执行作业的时间。任务因电量不足、回充、现场受阻等原因没有实际作业时，即使区间跨了十几分钟，durationSeconds 仍可能是 0。

判断任务是否真的执行过，看 completionPercentage、actualCleaningAreaSquareMeter、areaNameList，不要只看时间差。

42. 任务报告里没有 taskId / planId，正常吗？​

正常。这两个字段不是所有机型与版本都会上报：

  • taskId：仅部分 AIO 版本（40 / 50 / S 系列）上报。
  • planId：在上面基础上还要求任务由排班计划触发，临时任务没有 planId。

缺失时用 id 作为报告唯一标识，用 taskInstanceId 关联同一次执行实例。

43. 任务报告的时间字段是什么格式？​

查询接口与推送接口不一致，这是最容易踩的坑：

来源格式
分页查询任务报告响应里的 startTime / endTime 是 Unix 秒（示例 1785722400）；查询参数 endTimeMin / endTimeMax 是 yyyy-MM-dd HH:mm:ss 的机器人本地时间
任务报告推送startTime / endTime 是 Unix 毫秒（示例 1714124784000）

把推送里的毫秒值直接当秒传给查询接口，会落到极远的时间点导致查不到数据。跨接口比对前先统一单位。

推送侧的完整字段清单见任务报告推送。

事件推送与回调​

44. 怎么判断某个故障已经恢复？​

按 incidentId 关联报警与恢复，用 incidentStatus 区分状态：

字段判断依据
incidentId同一故障的报警与恢复使用相同 ID。同类故障再次发生时是新的 incidentId，不会复用
incidentStatus1 表示报警，0 表示恢复
endTime未恢复时为空字符串

几个必须处理的边界：

  1. 乱序：推送并发发出，恢复可能先于报警到达。已收到某 incidentId 的恢复后，再收到同 ID 的报警应忽略；也可按 startTime 排序兜底。
  2. H0 没有恢复消息：H0 是一次性事件通知，没有开始 / 结束状态，不要等它的恢复事件。
  3. 可能丢消息：推送失败最多重试 3 次，成功后不再发送。恢复消息丢失会让系统一直认为故障未解决，建议对长时间未收到恢复的故障做定期人工复核。
  4. 恢复的语义：incidentStatus = 0 既可能是机器人自行恢复，也可能是现场处理后恢复，不能据此判断处理方式。

字段定义、推送格式与验签方式见事件推送与回调验签。

45. 哪些等级的告警会被推送？​

incidentLevel 决定对外可见性：

等级含义对外可见性
H0事件通知（非告警）可见，一次性消息，无恢复事件
H1埋点统计可见
H2常规状态1 分钟内恢复则不可见
H4协助 / 问题1 分钟内恢复则不可见
H5隐患可见
H6故障1 分钟内恢复则不可见

此外还需要客户已配置告警模板，并受事件滤波频率设置影响。所以「某个告警没收到推送」应先核对等级、模板与滤波配置，再判断是否消息丢失。

各等级的完整定义见事件推送的 payload.content.incidentLevel 表。

指令操作​

46. cmdStatus = 6 且 cmdResultCode = 6880，是不是任务已经完成了？​

不是。cmdStatus = 6 固定返回 6880 和 success，只表示指令已成功下发，不代表机器人完成动作。要确认执行结果，需要继续查询任务状态或机器人状态快照。

47. 指令重复下发了怎么办？​

写指令接口支持可选的 Idempotency-Key 请求头。传入时服务端会去除首尾空格并限制最多 128 字符，同一幂等键重试会复用已有指令记录，不会重复下发。网络超时后重试建议带上同一个幂等键。

48. 指令下发后什么时候能查到结果？​

指令是异步的。拿到 requestId 后，用查询指令状态轮询单条结果，或用查询指令记录批量核对历史下发。

调试与文档​

49. 接口调不通 / 不返回数据，怎么排查？​

按顺序检查：

  1. 路径：V3 业务接口都以 /openapi/v3/ 开头，不要沿用 /openapi/v1alpha1/ 等旧路径。
  2. 方法：V3 业务接口统一 POST + JSON body，用 GET 会落到网关层。
  3. host：是否用了当前环境的域名。
  4. 认证：Authorization: Bearer {access_token} 是否正确。
  5. 响应体：HTTP 200 也可能是业务失败，必须看 code。

50. 在线调试面板发请求失败，提示跨域？​

浏览器受同源策略限制，部分环境会拦截跨域请求。这是浏览器行为，不是接口故障。复制面板生成好的 curl 命令，在终端或服务端执行即可。

51. V3 接口对机器人软件版本有要求吗？​

有。V3 接口只确保兼容 AIO 1.6 及以上软件版本。低于该版本的机器人请继续使用 V1/V2 接口。

52. 找不到某个 V1 接口对应的 V3 接口？​

V3 左侧导航目前分为认证服务、基础信息、指令操作、地图数据、任务与排班、机器人推送服务、云梯控对接接口协议七个分组。其中「机器人推送服务」与「云梯控对接接口协议」属于协议说明与回调约定，不随 V3 版本变化，已整体纳入 V3 导航，内容与旧版一致。V1/V2 的其余 REST 接口尚未全部迁移，可按分组在导航中确认；未覆盖的接口继续使用旧版路径。

与 V1/V2 的关键差异​

从 V1/V2 迁移时，以下几处最容易踩坑：

项目V1/V2V3
业务错误码4/5 位固定 6 位，号段见统一错误码
成功判断部分接口用 success只看 code = 0
分页上限200100
任务下发按机型 / 版本选不同 command 路径按任务类型拆分接口
机器人列表范围relation 可选 contract / 空不提供 relation 参数，默认范围由 AccessKey 版本决定：V3 凭证默认当前用户绑定，V1 凭证默认终端客户
任务状态字段taskState 四个语义值workState 原始数值透传
任务报告时间过滤不支持支持 endTimeMin / endTimeMax
任务报告分页参数page / pagesize多数接口为 pageNumber / pageSize，任务报告仍为 page / pagesize

其中「机器人列表范围」需要特别注意：V3 的查询机器人列表默认范围由换取 token 时使用的 AccessKey 版本决定：

  • V3 版本 AccessKey：默认返回当前用户直接绑定的机器人。
  • V1 版本 AccessKey：默认返回该客户作为终端客户名下的机器人。

也就是说，同一账号分别用两种版本的 AccessKey 换取 token 后调用同一个接口，可能拿到不同的机器人列表。这属于授权范围语义差异，不是数据缺失。V3 的机器人列表不提供关系参数，需要合同客户范围的机器人清单时，请继续使用旧版列出机器人并传入 relation=contract。