459 lines
20 KiB
Markdown
459 lines
20 KiB
Markdown
## 设备控制系统（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 | |
|
||
|
||
**响应参数：**统一响应
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|