## 设备控制系统（WCS）开放式接口文档

> 江苏菲达宝开电气股份有限公司
>
> 主版本号：2.0
>
> 版本号：2.0.1
>
> 时间：2025年6月6日



### 注意事项：

1、所有接口请勿并发调用，高频调用可能会被系统拉黑

2、WCS调用上位系统时若返回值不重要或者仅上报作用时只要调用成功（HTTP响应码为 2XX）即表示调用成功，若上位系统存在异常需要重新调用请不要返回 2XX响应码

3、WCS部分请求若请求失败在一定时间内会重新调用， 若失败次数过多或时间过长则不再调用，请确保存在内部处理方式，不能完全依赖WCS接口

4、系统对于重复的数据会默认返回成功，如重复发送的任务都会返回成功



### 统一约定

接口形式：webapi

数据格式：application/json



### 接口统一返回

| 键名       | 名称     | 数据类型 | 长度 | 是否必填 | 备注                                                         |
| ---------- | -------- | -------- | ---- | -------- | ------------------------------------------------------------ |
| code       | 返回码   | int32    | 4    | 是       | 操作成功返回 200，其他为异常代码<br />操作成功或者操作已经成功均视为成功，需要返回成功代码 |
| message    | 说明信息 | string   | 255  | 是       |                                                              |
| returnData | 返回数据 | object   |      | 否       | 在需要返回数据的时候带出数据                                 |



### 任务交互

#### 1、*WCS向上位系统申请仓储任务

> 客户端：`WCS`
>
> 服务端：`上位系统`
>
> 调用方式：POST
>
> 接口地址：<u>上位系统提供</u>

**使用说明：**WCS在需要申请任务时向上位系统请求，上位系统返回任务数据，只要返回结果为成功则视为成功，若不带出任务需要上位系统后续及时发送（发送接口为：上位系统向WCS发送任务）。

**请求参数：**

| 键        | 键名称   | 数据类型 | 长度 | 是否必填 | 备注                       |
| --------- | -------- | -------- | ---- | -------- | -------------------------- |
| requestId | 请求编号 | string   | 64   | Y        | 同样的请求编号视为同一请求 |
| vehicleNo | 载具编号 | string   | 64   | Y        |                            |
| location  | 位置     | string   | 64   | Y        |                            |
| size      | 尺寸     | int32    |      | N        |                            |
| length    | 长       | int32    |      | N        | 计量单位以现场为准         |
| width     | 宽       | int32    |      | N        | 计量单位以现场为准         |
| height    | 高       | int32    |      | N        | 计量单位以现场为准         |
| weight    | 重量     | int32    |      | N        | 计量单位以现场为准         |

```json
{
  "requestId":"1122333",
  "vehicleNo":"TP0001",
  "location":"R1",
  "size":1,
  "length":200,
  "width":150,
  "height":30,
  "weight":20000
}
```

**响应参数：**（returnData）

| 键          | 键名称       | 数据类型 | 长度 | 是否必填 | 备注                                                         |
| ----------- | ------------ | -------- | ---- | -------- | ------------------------------------------------------------ |
| taskId      | 任务号       | string   | 64   | Y        |                                                              |
| taskGroup   | 任务组       | string   | 64   | N        |                                                              |
| taskType    | 任务类型     | int32    |      | Y        | 枚举类型：<br />0 - 自动；<br />1 - 入库；<br />2 - 出库；<br />3 - 输送搬运；<br />9 - 移库；<br /><span style="color: #f455ee">自动任务请咨询我们后使用</span> |
| vehicleNo   | 载具编号     | string   | 64   | Y        | WCS系统以此处返回的生成任务，不以请求的载具号                |
| origin      | 起点         | string   | 32   | Y        |                                                              |
| destination | 终点         | string   | 32   | Y        |                                                              |
| priority    | 优先级       | int32    |      | N        | 范围：0-9<br />默认优先级（不传时）：5<br />数字越大优先级越高 |
| size        | 尺寸         | int32    |      | N        | 默认：0                                                      |
| weight      | 重量         | int32    |      | N        | 默认：0                                                      |
| sysName     | 上位系统名称 | string   | 32   | N        | 固定值，请联系我们获取，任意传将无法收到任务回告             |

```json
{
  "code":200,
  "message":"SUCCESS",
  "returnData":{
    "taskId":"123441123",
    "taskGroup":null,
    "taskType":0,
    "vehicle":"TP123",
    "origin":"R2",
    "destination":"A1-02-03-1",
    "priority":3,
    "size":1,
    "weight":344,
    "sysName":"WMS"
  }
}
```



#### 2、上位系统向WCS推送仓储任务

> 客户端：`上位系统`
>
> 服务端：`wcs`
>
> 调用方式：POST
>
> 接口地址：/api/pub/task/addStockTask

**使用说明：**上位系统调用此接口向WCS推送任务数据，任务号必须唯一，若任务号在WCS系统中已经存在则WCS会返回成功。

**请求参数：**

| 键          | 键名称       | 数据类型 | 长度 | 是否必填 | 备注                                                         |
| ----------- | ------------ | -------- | ---- | -------- | ------------------------------------------------------------ |
| taskId      | 任务号       | string   | 64   | Y        | 任务唯一识别号                                               |
| taskGroup   | 任务组       | string   | 64   | N        |                                                              |
| taskType    | 任务类型     | int32    |      | Y        | 枚举类型：<br />0 - 自动；<br />1 - 入库；<br />2 - 出库；<br />3 - 输送搬运；<br />9 - 移库；<br /><span style="color: #f455ee">自动任务请咨询我们后使用</span> |
| vehicleNo   | 载具编号     | string   | 64   | Y        | WCS系统以此处返回的生成任务，不以请求的载具号                |
| origin      | 起点         | string   | 32   | Y        |                                                              |
| destination | 终点         | string   | 32   | Y        |                                                              |
| priority    | 优先级       | int32    |      | N        | 范围：0-9<br />默认优先级（不传时）：5<br />数字越大优先级越高 |
| size        | 尺寸         | int32    |      | N        | 默认：0                                                      |
| weight      | 重量         | int32    |      | N        | 默认：0                                                      |
| sysName     | 上位系统名称 | string   | 32   | Y        | 固定值，请联系我们获取，任意传将无法收到任务回告             |

```json
{
    "taskId":"123441123",
    "taskGroup":null,
    "taskType":0,
    "vehicle":"TP123",
    "origin":"R2",
    "destination":"A1-02-03-1",
    "priority":3,
    "size":1,
    "weight":344,
    "sysName":"WMS"
  }
```

**响应参数：**统一响应



#### 3、*WCS上报仓储任务状态

> 客户端：`WCS`
>
> 服务端：`上位系统`
>
> 调用方式：POST
>
> 接口地址：<u>上位系统提供</u>

**使用说明：**WCS在任务的节点上报上位系统任务状态（只有最终任务状态会失败重试，如任务完成，任务取消等）。

**请求参数：**

| 键          | 键名称   | 数据类型 | 长度 | 是否必填 | 备注                                                         |
| ----------- | -------- | -------- | ---- | -------- | ------------------------------------------------------------ |
| taskId      | 任务号   | string   | 64   | Y        | 上位系统下发的任务号                                         |
| taskType    | 任务类型 | int32    |      | Y        | 枚举类型：<br />0 - 自动；<br />1 - 入库；<br />2 - 出库；<br />3 - 输送搬运；<br />9 - 移库; |
| taskStatus  | 任务状态 | int32    |      | Y        | 枚举类型：<br />1 - 任务开始<br />2 - 任务完成<br />3 - 任务异常<br />4 - 任务取消<br />5 - 目的位置有货<br />6 - 起点无货 |
| destination | 任务终点 | string   | 64   | N        |                                                              |
| vehicleNo   | 载具号   | string   | 64   | Y        |                                                              |
| message     | 信息     | string   | 255  | N        |                                                              |

```json
{
  "taskId":"123777888",
  "taskType":1,
  "taskStatus":3,
  "destination":"A1-01-3",
  "vehicle":"TP0002",
  "message":"任务被设备取消"
}
```

**响应参数：**统一响应



#### 4、上位系统查询仓储任务详情

> 客户端：`上位系统`
>
> 服务端：`wcs`
>
> 调用方式：GET
>
> 接口地址：/api/pub/task/queryStockTaskDetail

**使用说明：**上位系统可调用此接口查询仓库任务信息，注意超出仓库保存时长的数据将无法查询

**请求参数：**<u>url参数</u>

| 键     | 键名称 | 数据类型 | 长度 | 是否必填 | 备注                 |
| ------ | ------ | -------- | ---- | -------- | -------------------- |
| taskId | 任务号 | string   | 64   | Y        | 上位系统下发的任务号 |

```url
http://{ip}:{port}?taskId={taskId}
```

**响应参数：**（returnData）

| 键           | 键名称       | 数据类型 | 长度 | 是否必填 | 备注                                                         |
| ------------ | ------------ | -------- | ---- | -------- | ------------------------------------------------------------ |
| taskId       | 任务号       | string   | 64   | Y        | WCS系统任务号                                                |
| taskGroup    | 任务组       | string   | 64   | Y        |                                                              |
| upperTaskId  | 上位任务号   | string   | 64   | Y        | 请求的任务号                                                 |
| taskType     | 任务类型     | int32    |      | Y        | 枚举类型：<br />0 - 自动；<br />1 - 入库；<br />2 - 出库；<br />3 - 输送搬运；<br />9 - 移库; |
| origin       | 起点         | string   | 64   | N        |                                                              |
| destination  | 终点         | string   | 64   | N        |                                                              |
| taskStatus   | 任务状态     | int32    |      | Y        | 枚举类型：<br />0 - 待执行；<br />1 - 排队中；<br />2 - 执行中；<br />3 - 已完成；<br />4 - 已取消；<br />5 - 任务异常；<br />6 - 任务超时； |
| canCancel    | 是否允许取消 | int32    |      | Y        |                                                              |
| priority     | 优先级       | int32    |      | Y        |                                                              |
| vehicleNo    | 载具号       | string   | 64   | Y        |                                                              |
| vehicleSize  | 载具尺寸     | int32    |      | N        |                                                              |
| weight       | 重量         | decimal  |      | N        |                                                              |
| startTime    | 开始时间     | date     |      | Y        |                                                              |
| completeTime | 完成时间     | date     |      | N        | 任务完成时间                                                 |
| endTime      | 结束时间     | date     |      | N        | 任务结束时间，包括完成或者取消                               |
| taskMsg      | 任务信息     | string   | 255  | N        |                                                              |



#### 5、上位系统要求取消仓储任务

> 客户端：`上位系统`
>
> 服务端：`wcs`
>
> 调用方式：DELETE
>
> 接口地址：/api/pub/task/cancelStockTask

**使用说明：**上位系统可以在需要时取消已经下发的任务，WCS系统会综合判定是否允许取消

**请求参数：**<u>url参数</u>

| 键     | 键名称 | 数据类型 | 长度 | 是否必填 | 备注                 |
| ------ | ------ | -------- | ---- | -------- | -------------------- |
| taskId | 任务号 | string   | 64   | Y        | 上位系统下发的任务号 |

```url
http://{ip}:{port}?taskId={taskId}
```

**响应参数：**统一响应



#### 6、上位系统向WCS推送简单输送任务

> 客户端：`上位系统`
>
> 服务端：`wcs`
>
> 调用方式：POST
>
> 接口地址：/api/pub/task/addConveyTask

**使用说明：** 简单输送任务一般表示为箱式线输送，即仅在关键点控制流向的任务，其余由设备自动输送

**请求参数：**

| 键        | 键名称       | 数据类型 | 长度 | 是否必填 | 备注                                                         |
| --------- | ------------ | -------- | ---- | -------- | ------------------------------------------------------------ |
| taskId    | 任务号       | string   | 64   | Y        | 任务唯一识别号                                               |
| taskGroup | 任务组       | string   | 64   | N        |                                                              |
| taskType  | 任务类型     | int32    |      | Y        | 枚举类型：<br />1 - 捡选任务；<br />2 - 复核任务；<br />3 - 发货任务；<br />9 - 补货任务； |
| vehicleNo | 载具编号     | string   | 64   | Y        |                                                              |
| orderId   | 订单号       | string   | 32   | N        |                                                              |
| location  | 终点         | string   | 32   | Y        |                                                              |
| size      | 尺寸         | string   | 32   | N        |                                                              |
| weight    | 重量         | int32    |      | N        | 默认：0                                                      |
| length    | 长           | int32    |      | N        | 默认：0                                                      |
| width     | 宽           | int32    |      | N        | 默认：0                                                      |
| height    | 高           | int32    |      | N        | 默认：0                                                      |
| sysName   | 上位系统名称 | string   | 32   | Y        | 固定值，请联系我们获取，任意传将无法收到任务回告             |

```json
{
  "taskId":"123",
  "taskGroup":"334455",
  "taskType":1,
  "vehicleNo":"T0003",
  "orderId":"009901",
  "location":"A01",
  "size":"-",
  "weight":200,
  "length":100,
  "weight":150,
  "height":120,
  "sysName":"WMS"
}
```

**响应参数：**统一响应



#### 7、*WCS上报简单输送任务状态

> 客户端：`WCS`
>
> 服务端：`上位系统`
>
> 调用方式：POST
>
> 接口地址：<u>上位系统提供</u>

**使用说明：** WCS在简单输送任务关键节点时上报上位系统状态，如任务完成，任务超时，任务取消等

**请求参数：**

| 键             | 键名称   | 数据类型 | 长度 | 是否必填 | 备注                                                         |
| -------------- | -------- | -------- | ---- | -------- | ------------------------------------------------------------ |
| taskId         | 任务号   | string   | 64   | Y        | 上位系统下发的任务号                                         |
| taskType       | 任务类型 | int32    |      | Y        | 枚举类型：<br />1 - 捡选任务；<br />2 - 复核任务；<br />3 - 发货任务；<br />4 - 补货任务; |
| taskStatus     | 任务状态 | int32    |      | Y        | 枚举类型：<br />1 - 箱子到达某一点位<br />2 - 箱子到达目的地<br />3 - 任务异常<br />4 - 任务取消 |
| arriveLocation | 到达位置 | string   | 64   | N        |                                                              |
| vehicleNo      | 载具号   | string   | 64   | Y        |                                                              |
| message        | 信息     | string   | 255  | N        |                                                              |

**响应参数：**统一响应



#### 8、上位系统给WCS推送电子标签任务

> 客户端：`上位系统`
>
> 服务端：`wcs`
>
> 调用方式：POST
>
> 接口地址：/api/pub/task/addEtagTask

**使用说明：**WCS不会合并同货位的任务数量，如需合并捡选请合并后发送给WCS

**请求参数：**

| 键         | 键名称       | 数据类型 | 长度 | 是否必填 | 备注                                                         |
| ---------- | ------------ | -------- | ---- | -------- | ------------------------------------------------------------ |
| taskGroup  | 任务组       | string   | 64   | N        |                                                              |
| taskType   | 任务类型     | int      |      | Y        | 枚举类型：<br />1 - 捡货<br />2 - 上架<br />3 - 盘点<br />4 - 清点<br />5 - 其他 |
| vehicleNo  | 载具号       | string   | 64   | Y        |                                                              |
| lightModel | 点亮类型     | int      |      | N        | 枚举类型：<br />1 - 立即点亮<br />2 - 等待触发<br /><span style="color:#f455ee">根据流程确定，请与我们交流方案，不传或传空视为立即点亮</span> |
| sysName    | 上位系统名称 | string   | 32   | Y        | 固定值，请联系我们获取，否则将无法收到任务回告               |
| taskList   | 任务数据     | list     |      | Y        |                                                              |

taskList：<span style="color:#f455ee">若任务中存在一个有问题，则所有任务都会判定失败</span>

| 键        | 键名称   | 数据类型 | 长度 | 是否必填 | 备注               |
| --------- | -------- | -------- | ---- | -------- | ------------------ |
| taskId    | 任务号   | string   | 64   | Y        | 唯一标识           |
| orderId   | 订单号   | string   | 64   | N        | 备选字段           |
| location  | 点位     | string   | 64   | Y        | 需要点亮的点位     |
| goodsId   | 物料编号 | string   | 64   | N        | 中文标签时可能需要 |
| goodsName | 物料名称 | string   | 64   | N        | 中文标签时可能需要 |
| lightNum  | 点亮数量 | int      |      | Y        | 点亮的数量         |

**请求示例：**

```json
{
  "taskGroup":"2223336678",
  "taskType":1,
  "vehicleNo":"11220099",
  "lightModel":1,
  "sysName":"WMS",
  "taskList":[
    {
      "taskId":"12434543",
      "orderId":"889088",
      "location":"A02-99-12",
      "goodsId":"449802",
      "goodsName":"饮用水",
      "lightNum":13
    }
  ]
}
```

**响应参数：**统一响应



#### 9、*WCS上报电子标签任务完成

> 客户端：`WCS`
>
> 服务端：`上位系统`
>
> 调用方式：POST
>
> 接口地址：<u>上位系统提供</u>

**请求参数：**

| 键            | 键名称     | 数据类型 | 长度 | 是否必填 | 备注             |
| ------------- | ---------- | -------- | ---- | -------- | ---------------- |
| taskId        | 任务号     | string   | 64   | Y        | 上位发来的任务号 |
| confirmNum    | 确认的数量 | int      |      | Y        |                  |
| confirmPerson | 确认人     | string   |      | N        |                  |

**响应参数：**统一响应