icewint/wcs_java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
56340467d6
wcs_java/files/WCS开放式接口文档.md

459 lines
20 KiB
Markdown
Raw Normal View History

公测版，立库方面基本完善
2026-01-22 11:07:07 +08:00
## 设备控制系统（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
优化代码，改进电子标签打印界面
2026-01-27 15:11:34 +08:00
**使用说明：**WCS不会合并同货位的任务数量，如需合并捡选请合并后发送给WCS
公测版，立库方面基本完善
2026-01-22 11:07:07 +08:00
**请求参数：**
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
| ---------- | ------------ | -------- | ---- | -------- | ------------------------------------------------------------ |
| taskGroup | 任务组 | string | 64 | N | |
| taskType | 任务类型 | int | | Y | 枚举类型：<br />1 - 捡货<br />2 - 上架<br />3 - 盘点<br />4 - 清点<br />5 - 其他 |
添加电子标签接收任务的外部接口
2026-01-22 11:42:04 +08:00
| vehicleNo | 载具号 | string | 64 | Y | |
优化代码，改进电子标签打印界面
2026-01-27 15:11:34 +08:00
| lightModel | 点亮类型 | int | | N | 枚举类型：<br />1 - 立即点亮<br />2 - 等待触发<br /><span style="color:#f455ee">根据流程确定，请与我们交流方案，不传或传空视为立即点亮</span> |
公测版，立库方面基本完善
2026-01-22 11:07:07 +08:00
| sysName | 上位系统名称 | string | 32 | Y | 固定值，请联系我们获取，否则将无法收到任务回告 |
| taskList | 任务数据 | list | | Y | |
taskList：<span style="color:#f455ee">若任务中存在一个有问题，则所有任务都会判定失败</span>
优化代码，改进电子标签打印界面
2026-01-27 15:11:34 +08:00
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
| --------- | -------- | -------- | ---- | -------- | ------------------ |
| taskId | 任务号 | string | 64 | Y | 唯一标识 |
| orderId | 订单号 | string | 64 | N | 备选字段 |
| location | 点位 | string | 64 | Y | 需要点亮的点位 |
| goodsId | 物料编号 | string | 64 | N | 中文标签时可能需要 |
| goodsName | 物料名称 | string | 64 | N | 中文标签时可能需要 |
| lightNum | 点亮数量 | int | | Y | 点亮的数量 |
公测版，立库方面基本完善
2026-01-22 11:07:07 +08:00
**请求示例：**
```json
{
"taskGroup":"2223336678",
"taskType":1,
优化代码，改进电子标签打印界面
2026-01-27 15:11:34 +08:00
"vehicleNo":"11220099",
公测版，立库方面基本完善
2026-01-22 11:07:07 +08:00
"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 | |
**响应参数：**统一响应
Reference in New Issue Copy Permalink