wcs_java/WCS开放式接口文档.md at 568ff5b26155a301b1caba5e7a895eb4bc6031ee

icewint/wcs_java

Fork 0

icewint 568ff5b261 公测版，立库方面基本完善

2026-01-22 11:07:07 +08:00

20 KiB

Raw Blame History

设备控制系统（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 - 其他
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

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

20 KiB Raw Blame History Unescape Escape

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

注意事项：

统一约定

接口统一返回

任务交互

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

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

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

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

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

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

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

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

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

20 KiB

Raw Blame History