# 海康机器人 RCS‑2000 V4.2 接口协议（对外发布）
>文档类别：厂内物流机器人控制系统
>文档编号：RCS‑2000 V4.2
>版权所有 ©杭州海康机器人股份有限公司

## 版权声明
本文档由海康机器人公司开发，其版权受中华人民共和国版权法保护。海康机器人拥有本文的全部版权，未经本公司许可，任何单位及个人不得对本文中的任何部分进行转印、影印或复印。

## 信息反馈
海康机器人尽最大的努力保证本手册的准确性和完整性。如果您在使用中发现问题，希望及时将情况反馈给我们以完善产品，我们将非常感谢您的支持。

### 总公司联系方式
- 公司总机：0571‑88967998
- 技术支持电话：0571‑86611880(工作日9:30‑17:30)
- 传真：0571‑88805843
- 地址：中国杭州市滨江区东流路700号
- 邮编：310052
- 公司E‑mail：hikrobot@hikrobotics.com
- 公司网站：www.hikrobotics.com

## 目录
1. [协议概述](#1‑协议概述)
    - 1.1 请求首部字段
    - 1.2 请求报文消息体
    - 1.3 加密签名
    - 1.4 响应首部字段
    - 1.5 响应报文消息体
    - 1.6 响应状态码
    - 1.7 响应报文消息体通用code
2. [业务接口说明](#2‑业务接口说明)
    - 2.1 机器人调度API 接口说明
    - 2.2 反馈接收SPI 接口说明
3. [任务下发接口调用示例](#3‑任务下发接口调用示例)
4. [典型调度场景](#4‑典型调度场景)
5. [更新说明](#5‑更新说明)

---

# 1 协议概述
>海康调度系统调用上层系统的接口，获取连接超时时间默认为30 秒，数据返回超时时间默认为60 秒，超时情况下，调度系统会返回连接失败。

## 1.1 请求首部字段
|字段名|数据类型|最大字节数|是否必需|说明|
|---|---|---|---|---|
|Authorization|字符串|N/A|否|固定格式：`nonce="wab1tkh",method="HMAC‑SHA256",timestamp="2021‑01‑01T00:00:00+08:00"`|
|Content‑Type|字符串|N/A|否|固定取值：`application/json;charset=UTF‑8`|
|X‑lr‑appkey|字符串|32|否|由调度系统颁发给业务系统的唯一标识|
|X‑lr‑request‑id|字符串|16|是|业务请求的唯一标识|
|X‑lr‑version|字符串|12|否|API 接口版本，为了保证接口的向下兼容，同样的 API 接口可能存在多个版本实现|
|X‑lr‑trace‑id|字符串|32|否|全链路追踪标识，用于协查上下游故障，需要在响应中原样返回。建议使用 UUID|
|X‑lr‑source|字符串|32|否|指令的来源，便于调试和故障定位|

## 1.2 请求报文消息体
只能使用**JSON格式(UTF‑8编码方式)**或空字符串(无字符)。不能使用JSON对象数组或其他格式。业务请求的参数信息应当放在请求报文消息体当中。

**请求报文样例**
```http
POST /api/robot/controller/tasks HTTP/1.1 
Host: 10.10.10.10:1010
Authorization: nonce="wab1tkh",method="HMAC‑SHA256",timestamp="2021‑01‑01T00:00:00+08:00"
X‑lr‑appkey: a4f********b324
X‑lr‑version: v1.0 
X‑lr‑trace‑id: 605****8a0b
X‑lr‑request‑id: 393****a6c1 
Content‑Type: application/json;charset=UTF‑8 
Content‑Length: 512 
Date: Fri, 26 Mar 2021 06:46:14 GMT 

{"warehouseId":"371****b108",……,"zoneCode":"c7a6****371b"}
```

## 1.3 加密签名
应用注册中的第三方应用，如开启加密，请求时需带上签名。`appSecret`为应用注册中的私钥。
>请求完整示例如上所示，其中只有请求行、特定的首部字段、空行、报文消息体参与签名，即需要从请求报文原文中去除不参与签名的首部字段，将参与签名的首部字段名按下表编号的顺序排序，同时首部字段名改为大写。

**参与签名的首部字段**
|编号|参与签名的首部字段|是否必填|
|---|---|---|
|1|AUTHORIZATION|是|
|2|HOST|是|
|3|X‑LR‑APPKEY|是|
|4|X‑LR‑REQUEST‑ID|是|
|5|X‑LR‑SOURCE|否|
|6|X‑LR‑TRACE‑ID|否|
|7|X‑LR‑VERSION|是|

签名生成逻辑：
> 签名 = MD5( 加盐哈希算法(appSecret,请求报文拼接后的原串) )
> 加盐哈希算法可选：
> 1）HMAC‑SHA256（推荐）
> 2）HMAC‑SHA512
> 使用MD5对加盐哈希算法的散列值再次哈希，产生128(16字节)的散列值。

>请求的签名应当携带在**查询参数**的最后，参数名为`sign`。

**Authorization头部参数说明**
|参数名|数据类型|字节数|是否必须|说明|
|---|---|---|---|---|
|nonce|字符串|8|是|随机数。建议每次请求都不同，以便于更有效的抵御彩虹表攻击；也可以定时更换|
|method|字符串|N/A|是|加盐哈希算法，固定枚举值：`HMAC‑SHA256`、`HMAC‑SHA512`|
|timestamp|字符串|N/A|是|请求发出的时间，遵循本文档关于时间格式秒精度的定义|

>重放攻击验证：服务端取出timestamp，加上业务允许合法请求时间，建议不超过**120秒**，判断请求是否超时。

## 1.4 响应首部字段
|字段名|数据类型|最大字节数|是否必须|说明|
|---|---|---|---|---|
|Content‑Type|字符串|N/A|否|固定取值：`application/json;charset=UTF‑8`|
|X‑lr‑request‑id|字符串|16|是|业务请求的唯一标识|
|X‑lr‑version|字符串|12|否|API接口版本|
|X‑lr‑trace‑id|字符串|32|否|全链路追踪标识，原样返回请求入参|

## 1.5 响应报文消息体
当HTTP 响应状态码为`200`时，响应报文消息体JSON对象格式：

|中文名称|字段名|数据类型|最大字节数|是否必须|说明|
|---|---|---|---|---|---|
|消息码|code|字符串|32|是|参见 1.6 章节通用响应 code 定义和各接口的消息码定义|
|提示消息|message|字符串|256|否|异常描述|
|业务数据|data|JSON 对象|10MB|否|返回的业务属性对象|

**正常响应报文样例**
```json
{
    "code":"SUCCESS",
    "message":"成功",
    "data": {
        "robotTaskCode": "abc**13"
    }
}
```

**业务异常响应报文样例**
```json
{
    "code":"Err_Internal",
    "message":"内部未知错误",
    "data":null
}
```

## 1.6 响应状态码
|状态码|说明|
|---|---|
|200|HTTP协议层面处理成功，但是仍可能出现业务异常，需要根据响应报文消息体的消息码判断|
|401|签名认证失败。原因可能是签名无效、签名过期、appKey和appSecret失效，需要重新更新请求时间后加签，或需要调度系统重新颁发appKey和appSecret|
|403|权限不足。例如业务系统试图取消不由其创建的任务|
|406|请求的Content‑Type不符合要求|
|400|其他由于客户端请求错误导致的异常，无法通过重试解决，需要检查请求的格式是否符合要求|
|500|服务端的异常，可以通过重试请求解决，重试次数与间隔需要根据业务实际情况设定|

>其余未列出状态码均按照标准HTTP协议处理即可。

## 1.7 响应报文消息体通用code
|Code|message|
|---|---|
|SUCCESS|成功|
|Err_Internal|内部未知错误|
|Err_DataValidationFailed|数据格式验证失败|
|Err_RequestDuplicate|请求重复|
|Err_InvalidVersion|请求版本不合法|

---

# 2 业务接口说明
服务前缀统一：`/rcs/rtas`，完整请求路径 = 服务前缀 + 路径。

## 2.1 机器人调度API 接口说明
> WMS/MES作为**调用方**，主动调用RCS‑2000这一组API。

### 2.1.1【国标】任务组接口
- 接口路径：`/api/robot/controller/task/group`
- 请求方式：`POST`
- 幂等性：**是**

>接口说明
1. 任务组是任务的集合，当任务间有相互关系时，需要先调用任务组接口，描述任务组的策略，任务间的关系组合，再调用任务下发接口。
2. 任务策略包括按组顺序出库策略、按组分配策略。
3. 顺序出库下发规则：上层系统将 `groupSeq` 从小到大下发给 RCS‑2000，**上层系统需要控制下发顺序**，不支持先调接口发 groupSeq 大的，再调接口发 groupSeq 小的执行顺序出库。

**请求体字段**
|参数名|数据类型|最大字节数|是否必须|说明|
|---|---|---|---|---|
|groupCode|字符串|32|是|任务组编号，全局唯一|
|strategy|字符串|16|是|执行策略。枚举：`GROUP_SEQ`按组顺序出库；`GROUP_ASSIGN`按组分配任务(CTU专用)；`GROUP_CARRIER_ADJUST`载具整理(CTU理库)|
|strategyValue|字符串|32|否|GROUP_SEQ时必填：0组间无序组内无序；1组间及组内都有序；2组间有序组内无序；3组间无序组内有序；GROUP_CARRIER_ADJUST理库时必填|
|groupSeq|整数|8|否|组顺序(数字)，从1~9999999999|
|data|JSON对象数组|N/A|是|子任务集合，每个元素：`robotTaskCode`(任务号),`sequence`(组内顺序)|

**响应公共字段**：`code`/`message`/`data`，data内返回任务组信息。
专用消息码：`Err_TaskNotStart`上一组任务未下发；`Err_DataValidationFailed`任务序列号有误。

**请求示例**
```json
{
    "groupCode": "2e0d1ae0481f48b78b6a217ac2b54eb4",
    "strategy": "GROUP_SEQ",
    "strategyValue": "1",
    "groupSeq": 10,
    "targetRoute": {
        "type": "ZONE",
        "code": "A2"
    },
    "data": [
        {"robotTaskCode": "0a17e361eb5248bfab0508e4709f085e","sequence": 1},
        {"robotTaskCode": "1b30143f32914155ab194d55a95d54da","sequence": 2},
        {"robotTaskCode": "6541e925d1de4c448188068fcee75de5","sequence": 3}
    ]
}
```

### 2.1.2【国标】 任务下发接口
- 接口路径：`/api/robot/controller/task/submit`
- 请求方式：`POST`
- 幂等性：**是**

>接口说明：业务系统发送任务请求，物流机器人调度系统生成任务执行单，并下发执行。

**请求体字段**
|参数名|数据类型|最大字节数|是否必须|说明|
|---|---|---|---|---|
|taskType|字符串|16|是|任务类型，预制枚举：`PF‑LMR‑COMMON`普通搬运|
|targetRoute|对象数组|N/A|是|执行步骤集合，机器人关键路径（起点、终点）|
|initPriority|整数|8|否|初始优先级1‑120，数值越大优先级越高；调度会动态修正实际优先级|
|deadline|时间|N/A|否|任务截止时间，秒精度，优先级修正条件之一|
|robotType|字符串|N/A|否|`GROUPS`资源组 / `ROBOTS`机器人编号|
|robotCode|字符串数组|N/A|否|机器人编号集合|
|robotTaskCode|字符串|64|否|外部任务唯一编号；不传则调度系统生成返回|
|extra|JSON对象|N/A|否|自定义扩展透传字段|

>targetRoute子对象：
> - `type`：`SITE`站点；`ZONE`区域；`STORAGE`仓位；`CARRIER`载具等
> - `code`：对应编号
> - `operation`：`COLLECT`取货，`DELIVERY`送货，`ROTATE`旋转
> - `carrierInfo[]`：载具信息（载具类型、编号、层号）
> - `angleInfo`：角度信息

**响应data字段**：`robotTaskCode`（全局唯一任务号）
专用错误码：`Err_TaskTypeNotSupport`任务类型不支持；`Err_RobotGroupsNotMatch`机器人资源组不匹配；`Err_TargetRouteError`路径参数错误。

### 2.1.3 任务继续执行接口
- 路径：`/api/robot/controller/task/extend/continue`
- POST，幂等：是

>说明：一个任务包含多个步骤，每个步骤完成后，上层调用本接口驱动下一步骤；第一个步骤也需要调用此接口启动。若步骤设置autoStart自动开始，则可不调用；重复调用做幂等处理。

请求入参：
- triggerType：`SITE`站点 / `ROBOT`车号 / `TASK`任务链编号
- triggerCode：对应编号
- targetRoute：下一步目标路径对象
- extra：扩展字段

错误码：`Err_TaskNotStart`任务尚未开始；`Err_TaskFinished`任务已结束；`Err_TaskNotFound`任务找不到。

### 2.1.4【国标】任务取消接口
- 路径：`/api/robot/controller/task/cancel`
- POST，幂等：是

>说明：取消任务；软取消可下发回库任务；支持按任务号、机器人编号、载具编号批量取消。

请求体关键字段
|参数|说明|
|---|---|
|robotTaskCode|任务号，可选|
|cancelType|`CANCEL`软取消；`DROP`人工介入硬取消|
|carrierCode|载具编号，批量取消用|
|robotCode|机器人编号，批量取消用|
|reason|取消原因|
|returnTaskType|软取消回库流程类型，默认`PF‑TASK‑CANCEL‑RETURN`|
|targetRoute|取消后机器人目标位置|

### 2.1.5【国标】任务优先级设置接口
- 路径：`/api/robot/controller/task/priority`
- POST，幂等：是

>说明：任务创建后，修改初始优先级、截止时间；调度系统会综合工况动态调整实际执行优先级。

入参：
- robotTaskCode：任务编号（必填）
- initPriority：1‑120
- deadline：截止时间（可选）
- extra：扩展

### 2.1.6【国标】区域暂停与恢复机器人接口
- 路径：`/api/robot/controller/zone/pause`
- POST，幂等：是

入参：
- zoneCode：管控区域编号
- invoke：`FREEZE`急停暂停；`RUN`恢复运行

### 2.1.7【国标】区域归巢机器人接口
- 路径：`/api/robot/controller/zone/homing`
- POST，幂等：是

>让指定区域机器人前往归巢点位，支持归巢后关机、定时开机。

入参关键字段
- zoneCodes：区域编号集合
- autoShutdown：`YES`关机 / `NO`不关机
- bootTime：预设开机时间（autoShutdown=YES生效）
- expireTime：归巢超时时间

返回data：`homingCode`归巢指令编号；`robotCount`接收到指令的机器人数量。

### 2.1.8【国标】 区域驱离机器人接口
- 路径：`/api/robot/controller/zone/banish`
- POST，幂等：是

>将区域内机器人驱离，禁止进入该区域。
返回`banishCode`驱离指令编号。

### 2.1.9【国标】区域封锁与恢复接口
- 路径：`/api/robot/controller/zone/blockade`
- POST，幂等：是

>封锁：禁止机器人进入该区域；不强制区内机器人离开。
invoke枚举：`BLOCKADE`封锁；`OPENUP`解封。

### 2.1.10【国标】载具与站点绑定接口
- 路径：`/api/robot/controller/carrier/bind`
- POST，幂等：是

>代表载具放置在该站点；前提：载具、站点无占用任务。
入参：`carrierCode`载具编号，`siteCode`站点编号，`carrierDir`载具角度。

### 2.1.11【国标】载具与站点解绑接口
- 路径：`/api/robot/controller/carrier/unbind`
- POST，幂等：是

>解绑载具‑站点；carrierCode/siteCode至少传一个。

### 2.1.12 存储对象与搬运对象绑定解绑接口
- 路径：`/api/robot/controller/site/bind`
- POST，幂等：是

>slot：仓位/站点；invoke=`BIND`绑定 / `UNBIND`解绑；支持料箱、载具绑定解绑。

### 2.1.13【国标】 载具禁用与启用
- 路径：`/api/robot/controller/carrier/lock`
- POST，幂等：是

invoke：`LOCK`禁用；`UNLOCK`启用；传入`carrierCode`。

### 2.1.14【国标】站点禁用与启用
- 路径：`/api/robot/controller/site/lock`
- POST，幂等：是

invoke：`LOCK`禁用；`UNLOCK`启用；传入`siteCode`站点编号。

### 2.1.15 外设执行通知接口【返回0】
- 路径：`/rcs/rtas/spi/wcs/robot/eqpt/notify`
- POST，幂等：是

>上层通知调度：电梯、自动门等外设动作完成。
>旧版本返回code=0；V4.2.8使用`notifyGbt`接口返回`SUCCESS`。

### 2.1.16【国标】预调度任务下发接口
- 路径：`/api/robot/controller/task/pretask`
- POST，幂等：是

>提前调度机器人到达点位等待业务任务。
入参：`siteCode`站点；`nextTaskTime`预计多久后执行真实任务，单位秒。

### 2.1.17【国标】查询任务状态接口
- 路径：`/api/robot/controller/task/query`
- POST，幂等：是

>根据`robotTaskCode`查询单条任务状态。
返回taskStatus枚举：`QUEUE`队列中；`WAIT`等待；`EXECUTING`执行；`MANUALED`人工完成；`FINISHED`已完成；`CANCELLED`已取消。

### 2.1.18【国标】查询机器人状态接口
- 路径：`/api/robot/controller/robot/query`
- POST，幂等：是

传入`singleRobotCode`机器人编号，返回：电量、坐标、速度、在线状态、任务状态、携带载具编号、告警信息。

### 2.1.19【国标】查询载具状态接口
- 路径：`/api/robot/controller/carrier/query`
- POST，幂等：是

传入`carrierCode`，返回：所在站点、绑定任务号、坐标、载具状态、仓位编号、所属机器人编号。

### 2.1.20 物料绑定接口
- 路径：`/api/robot/controller/matlabel/bind`
- POST，幂等：是

>载具绑定物料标签。入参：carrierCode，matLabel物料标签。

### 2.1.21 物料解绑接口
- 路径：`/api/robot/controller/matlabel/unbind`
- POST，幂等：是

### 2.1.22 外设执行通知接口【V4.2.8 返回SUCCESS】
- 路径：`/rcs/rtas/spi/wcs/robot/eqpt/notifyGbt`
- POST，幂等：是
>新版本国标外设通知，返回code=SUCCESS，兼容电梯、自动门。

## 2.2 反馈接收SPI 接口说明
>**SPI：RCS‑2000作为调用方，主动回调上层WMS/MES服务地址，推送事件、告警、状态。需要在RCS后台配置上层回调地址。**

### 2.2.1【国标】任务执行过程回馈接口
- 回调路径示例：`/api/robot/reporter/task`
>任务事件上报：任务开始、离开储位、任务完成等事件。
values.method：`start`任务开始；`outbin`走出储位；`end`任务完成。

### 2.2.2 请求资源接口
- 回调路径：`/api/robot/reporter/resource`
>RCS向上层申请资源：申请站点、仓位、载具。applyType：`APPLY_SITE`申请站点、`APPLY_BIN`申请仓位。上层返回目标点位信息。

### 2.2.3 请求外设接口
- 回调路径：`/api/robot/reporter/eqpt`
>RCS向上层请求电梯、自动门外设资源。

### 2.2.4【国标】 机器人归巢完成回馈接口
- 回调路径示例：`/api/robot/reporter/zone/homing`
>归巢全部完成/超时回调通知上层。后台需要开启业务通知开关`ZONE_HOMING`。

### 2.2.5【国标】区域驱离机器人完成回馈接口
- 回调路径示例：`/api/robot/reporter/zone/banish`
驱离全部完成或超时通知；后台开启开关`ZONE_BANISH`。

### 2.2.6【国标】机器人异常告警上报接口
- 回调路径示例：`/api/robot/reporter/robot/warning`
>机器人严重故障告警上报，仅推送一次；后台开启开关`AMR_ALARM`。

### 2.2.7【国标】任务异常告警上报接口
- 回调路径示例：`/api/robot/reporter/task/warning`
>任务执行异常告警上报，仅推送一次；后台开启开关`TASK_ALARM`。

### 2.2.8 绑定解绑通知
- 回调路径示例：`/api/robot/reporter/bind`
>载具/仓位发生绑定、解绑动作时RCS回调上层；后台开启开关`BIND`。
invoke=`BIND`绑定 / `UNBIND`解绑。

# 3 任务下发接口调用示例
>文档包含潜伏车、CTU、叉车、滚筒车等各类机器人`task/submit`完整http+json请求样例，详见原始PDF文档3章节。

# 4 典型调度场景
1. 场景一：背货架AMR 在货架底下待命任务调度场景
2. 场景二：普通背货架任务调度场景
3. 场景三：辊筒AMR 任务调度场景
4. 场景四：CTU 输送线预调度+入库
5. 场景五：CTU 梳齿式工作站入库
6. 场景六：潜伏车顺序出库场景（任务组GROUP_SEQ典型用法）
7. 场景七：潜伏车搬运与外设交互场景

>每个场景给出：上层系统 ↔ HIK调度系统交互步骤、对应接口编号。

**潜伏车顺序出库重点说明**
>方式一（推荐）
>1）先调用**任务组接口2.1.1**，定义groupCode、策略、顺序；
>2）多次调用**任务下发2.1.2**，传入groupCode下发子任务。
>
>方式二（不推荐）：任务下发接口直接携带groupCode、sequence、seqType。

# 5 更新说明
|更新时间|更新人员|更新内容|
|---|---|---|
|2024/8/30|王勇52|1.编写4.2 接口文档|
|2024/9/3|王勇52|1.增加典型调度场景|
|2025/8/11|王勇52|1.修改预调度接口任务数字段描述|

---

>说明：本Markdown为文档结构化转写，部分超长http请求样例做简化；实际开发请以PDF原始报文样例复制使用。
>核心关键点总结（开发提示）
>1. API（WMS调用RCS）：2.1开头；SPI回调（RCS调用WMS）：2.2开头，需要RCS后台配置上层回调地址。
>2. 全部POST，JSON；签名使用HMAC‑SHA256，签名放url query参数sign。
>3. 任务顺序出库：优先使用任务组接口2.1.1。
>4. 外设交互两套通知接口：旧版notify（code=0）；新版notifyGbt（code=SUCCESS）V4.2.8+。
>5. 告警、归巢、驱离、绑定解绑回调，需要在RCS后台业务通知开启对应开关，否则不会推送SPI。

如果你需要，我可以进一步输出一份：**WMS对接海康RCS‑2000V4.2极简对接清单（字段清单+时序）**。