20 KiB
设备控制系统（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，其他为异常代码 操作成功或者操作已经成功均视为成功，需要返回成功代码 |
| message | 说明信息 | string | 255 | 是 | |
| returnData | 返回数据 | object | 否 | 在需要返回数据的时候带出数据 |
任务交互
1、*WCS向上位系统申请仓储任务
客户端：
WCS服务端：
上位系统调用方式：POST
接口地址：上位系统提供
**使用说明：**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 | 计量单位以现场为准 |
{
"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 | 枚举类型： 0 - 自动； 1 - 入库； 2 - 出库； 3 - 输送搬运； 9 - 移库； 自动任务请咨询我们后使用 |
|
| vehicleNo | 载具编号 | string | 64 | Y | WCS系统以此处返回的生成任务，不以请求的载具号 |
| origin | 起点 | string | 32 | Y | |
| destination | 终点 | string | 32 | Y | |
| priority | 优先级 | int32 | N | 范围：0-9 默认优先级（不传时）：5 数字越大优先级越高 |
|
| size | 尺寸 | int32 | N | 默认：0 | |
| weight | 重量 | int32 | N | 默认：0 | |
| sysName | 上位系统名称 | string | 32 | N | 固定值，请联系我们获取，任意传将无法收到任务回告 |
{
"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 | 枚举类型： 0 - 自动； 1 - 入库； 2 - 出库； 3 - 输送搬运； 9 - 移库； 自动任务请咨询我们后使用 |
|
| vehicleNo | 载具编号 | string | 64 | Y | WCS系统以此处返回的生成任务，不以请求的载具号 |
| origin | 起点 | string | 32 | Y | |
| destination | 终点 | string | 32 | Y | |
| priority | 优先级 | int32 | N | 范围：0-9 默认优先级（不传时）：5 数字越大优先级越高 |
|
| size | 尺寸 | int32 | N | 默认：0 | |
| weight | 重量 | int32 | N | 默认：0 | |
| sysName | 上位系统名称 | string | 32 | Y | 固定值，请联系我们获取，任意传将无法收到任务回告 |
{
"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
接口地址：上位系统提供
**使用说明：**WCS在任务的节点上报上位系统任务状态（只有最终任务状态会失败重试，如任务完成，任务取消等）。
请求参数：
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskId | 任务号 | string | 64 | Y | 上位系统下发的任务号 |
| taskType | 任务类型 | int32 | Y | 枚举类型： 0 - 自动； 1 - 入库； 2 - 出库； 3 - 输送搬运； 9 - 移库; |
|
| taskStatus | 任务状态 | int32 | Y | 枚举类型： 1 - 任务开始 2 - 任务完成 3 - 任务异常 4 - 任务取消 5 - 目的位置有货 6 - 起点无货 |
|
| destination | 任务终点 | string | 64 | N | |
| vehicleNo | 载具号 | string | 64 | Y | |
| message | 信息 | string | 255 | N |
{
"taskId":"123777888",
"taskType":1,
"taskStatus":3,
"destination":"A1-01-3",
"vehicle":"TP0002",
"message":"任务被设备取消"
}
**响应参数：**统一响应
4、上位系统查询仓储任务详情
客户端：
上位系统服务端：
wcs调用方式：GET
接口地址：/api/pub/task/queryStockTaskDetail
**使用说明：**上位系统可调用此接口查询仓库任务信息，注意超出仓库保存时长的数据将无法查询
请求参数：url参数
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskId | 任务号 | string | 64 | Y | 上位系统下发的任务号 |
http://{ip}:{port}?taskId={taskId}
响应参数：（returnData）
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskId | 任务号 | string | 64 | Y | WCS系统任务号 |
| taskGroup | 任务组 | string | 64 | Y | |
| upperTaskId | 上位任务号 | string | 64 | Y | 请求的任务号 |
| taskType | 任务类型 | int32 | Y | 枚举类型： 0 - 自动； 1 - 入库； 2 - 出库； 3 - 输送搬运； 9 - 移库; |
|
| origin | 起点 | string | 64 | N | |
| destination | 终点 | string | 64 | N | |
| taskStatus | 任务状态 | int32 | Y | 枚举类型： 0 - 待执行； 1 - 排队中； 2 - 执行中； 3 - 已完成； 4 - 已取消； 5 - 任务异常； 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系统会综合判定是否允许取消
请求参数：url参数
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskId | 任务号 | string | 64 | Y | 上位系统下发的任务号 |
http://{ip}:{port}?taskId={taskId}
**响应参数：**统一响应
6、上位系统向WCS推送简单输送任务
客户端：
上位系统服务端：
wcs调用方式：POST
接口地址：/api/pub/task/addConveyTask
使用说明： 简单输送任务一般表示为箱式线输送，即仅在关键点控制流向的任务，其余由设备自动输送
请求参数：
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskId | 任务号 | string | 64 | Y | 任务唯一识别号 |
| taskGroup | 任务组 | string | 64 | N | |
| taskType | 任务类型 | int32 | Y | 枚举类型： 1 - 捡选任务； 2 - 复核任务； 3 - 发货任务； 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 | 固定值，请联系我们获取，任意传将无法收到任务回告 |
{
"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
接口地址：上位系统提供
使用说明： WCS在简单输送任务关键节点时上报上位系统状态，如任务完成，任务超时，任务取消等
请求参数：
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskId | 任务号 | string | 64 | Y | 上位系统下发的任务号 |
| taskType | 任务类型 | int32 | Y | 枚举类型： 1 - 捡选任务； 2 - 复核任务； 3 - 发货任务； 4 - 补货任务; |
|
| taskStatus | 任务状态 | int32 | Y | 枚举类型： 1 - 箱子到达某一点位 2 - 箱子到达目的地 3 - 任务异常 4 - 任务取消 |
|
| arriveLocation | 到达位置 | string | 64 | N | |
| vehicleNo | 载具号 | string | 64 | Y | |
| message | 信息 | string | 255 | N |
**响应参数：**统一响应
8、上位系统给WCS推送电子标签任务
客户端：
上位系统服务端：
wcs调用方式：POST
接口地址：/api/pub/task/addEtagTask
请求参数：
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskGroup | 任务组 | string | 64 | N | |
| taskType | 任务类型 | int | Y | 枚举类型： 1 - 捡货 2 - 上架 3 - 盘点 4 - 清点 5 - 其他 |
|
| vehicleNo | 载具号 | string | 64 | Y | |
| lightModel | 点亮类型 | int | Y | 枚举类型： 1 - 立即点亮 2 - 等待触发 根据流程确定，请与我们交流方案 |
|
| sysName | 上位系统名称 | string | 32 | Y | 固定值，请联系我们获取，否则将无法收到任务回告 |
| taskList | 任务数据 | list | Y |
taskList：若任务中存在一个有问题，则所有任务都会判定失败
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskId | 任务号 | string | 64 | Y | 唯一标识 |
| orderId | 订单号 | string | 64 | N | |
| location | 点位 | string | 64 | Y | |
| goodsId | 物料编号 | string | 64 | N | |
| goodsName | 物料名称 | string | 64 | N | |
| lightNum | 点亮数量 | int | Y |
请求示例：
{
"taskGroup":"2223336678",
"taskType":1,
"lightModel":1,
"sysName":"WMS",
"taskList":[
{
"taskId":"12434543",
"orderId":"889088",
"location":"A02-99-12",
"goodsId":"449802",
"goodsName":"饮用水",
"lightNum":13
}
]
}
**响应参数：**统一响应
9、*WCS上报电子标签任务完成
客户端：
WCS服务端：
上位系统调用方式：POST
接口地址：上位系统提供
请求参数：
| 键 | 键名称 | 数据类型 | 长度 | 是否必填 | 备注 |
|---|---|---|---|---|---|
| taskId | 任务号 | string | 64 | Y | 上位发来的任务号 |
| confirmNum | 确认的数量 | int | Y | ||
| confirmPerson | 确认人 | string | N |
**响应参数：**统一响应