V3接口概述

欢迎使用高仙开放平台 V3 接口。V3 接口以机器人基础数据、地图资源、任务与排班、临时任务和指令操作为核心，提供统一的 JSON 请求、统一的响应结构以及每个接口独立的在线调试能力。本页帮助你理解完整的接口版图；首次接入请先阅读同级的「快速开始」页面。

兼容性与接入前提

兼容性

OpenAPI V3 接口只确保兼容 AIO 1.6 及以上软件版本。调用前请确认机器人已在当前开发者账号下绑定，并且相关地图、任务工作模式说明中的工作模式和任务资源已在机器人端可用。

调用业务接口前，需要完成以下准备：

1. 在开发者中心创建应用，取得 ClientID 和 ClientSecret。
2. 创建 AccessKey，取得 AccessKeyID 和 AccessKeySecret。
3. 在「认证服务」中获取 OAuth 访问令牌，并在令牌过期前刷新令牌。

接口版图

业务域	内容
认证服务	获取 OAuth 令牌、刷新 OAuth 令牌。两个接口沿用旧版 OAuth 地址。
基础信息	查询机器人列表和当前状态快照。
地图数据	查询机器人地图、地图画布、充电桩点位和地图资源。
任务与排班	管理组合任务定义；查询任务工作模式、机器人任务能力和任务资源；创建、修改、删除及查询标准/简化排班；启动或跳过临时任务。
指令操作	查询指令状态、查询指令记录、开始导航，以及任务指令对照表。

具体接口按上述业务域组织在左侧导航中。任务与排班是一个完整业务域，其中既包含任务定义和能力资源查询，也包含标准排班、简化排班和临时任务，不应只理解为“任务能力查询”。

通用调用约定

• 请求方式：除认证接口外，所有接口均使用 POST，请求体为 JSON，并设置 Content-Type: application/json。
• 接口前缀：业务接口统一以 /openapi/v3/ 开头；获取/刷新 OAuth 令牌沿用 /gas/api/v1alpha1/oauth/token。
• 鉴权：调用业务接口时，在请求头中携带 Authorization: Bearer {access_token}。认证接口本身通过请求体中的应用凭证和 AccessKey 凭证换取令牌。
• 请求限制：接口页面会标明单次请求的数量上限、必填字段和资源前置条件；请以每个接口页面的字段说明为准。
• 统一响应：业务接口返回 {code, msg, data}。code = 0 表示成功；非 0 时为六位错误码，msg 提供错误提示，data 通常为空。

认证与指令调用流程

推荐按以下顺序完成一次完整调用：

1. 使用应用信息和 AccessKey 获取 access_token。
2. 在业务请求头中携带 Authorization: Bearer {access_token}。
3. 对需要异步下发的机器人指令，保存响应中的 requestId。
4. 使用「查询指令状态」或「查询指令记录」确认指令下发和执行结果。cmdStatus = 6 固定返回 cmdResultCode = 6880 和 cmdResultMessage = success，只表示指令已成功下发，不等同于机器人已经完成动作；START_FUSION_TASK 在 Provider 返回运行实例时还会包含 taskInstanceId。
5. access_token 过期后，使用 refresh_token 调用刷新接口，避免重新授权。

状态、地图与坐标说明

机器人状态快照不是实时数据，接口页面会说明平均延迟。在线状态下才会返回电量、当前任务、地图和位置等运行字段；机器人离线时，这些字段可能为空或使用接口约定的默认值。只有在机器人已完成定位、存在可用网格坐标且地图元数据完整时，服务才能填充坐标；缺少任一条件时不要把空坐标解释为机器人位于原点。

地图和任务资源接口返回的 mapId、地图 UUID、分区、路径、点位和工作模式需要按接口之间的前置关系组合使用。创建组合任务或排班前，建议先查询「能力与资源查询」中的任务资源，再根据返回的资源标识构造任务或排班请求。

在线调试

每个接口页面都提供「在线调试」面板：

• 表单会根据字段 example 预填参数，并标记必填字段和固定字段；
• 修改参数时会同步生成可复制的 curl 命令；
• 可以直接发送请求查看响应。若浏览器受到跨域限制，请复制 curl 到终端执行；
• 调试真实机器人前，请确认当前令牌、机器人序列号、地图和资源属于同一开发者账号及环境。

如需开始第一次调用，请进入同级的「快速开始」页面；如需查找具体请求字段、响应样例或命令类型，请从左侧对应业务域进入接口页面。