SMF接口V2.3

SMF系统接口标准

版本：V2.3

修订记录

版本号	日期	修订内容
V1.0	2019.12.31	修订发布。
V1.1	2020.4.2	添加PN需求单出库功能
V1.2	2020.4.19	添加修改线别及时间接口
V2.1	2021.9.14	简化重构接口
V2.2	2022.3.2	简化重构接口
V2.3	2023.4.10	修改接口流程

文档概述

目的

此文档旨在初次将用户MES/ERP系统和SMF系统连接时，为用户提供技术和接口规格信息。

此规格需以双方约定的通讯协议书为标准制定。为第三方料仓定义规格，并与SMF系统整合使用。因为不同的MES/ERP系统具有不同的功能和特性，所以此规格标准无法处理所有特性的料仓。

范围

此规格书仅限SMF系统支持的云料仓/智能料架产品。

介绍

此规格书基于料盘条形码，可获取物料号、唯一码和数量等信息。

通信说明

API规范

API采用HTTP + JSON。

HTTP API是目前比较成熟的一套互联网应用程序的API设计理念，它采用一种统一的机制，方便不同的前端设备与后端进行通信。

编码格式

编码统一采用UTF-8标准。

接口列表

API编号	API名称	描述
API001	创建需求单	创建PN, RI需求单
API002	关闭需求单	关闭需求单后需求单不可再执行出库,同时会释放掉该需求单所绑定的材料
API003	线外发料	MES/ERP系统进行线外发料时,通知SMF系统,SMF系统在对应需求单发料时,会扣减线外发料的数量
API004	获取实时库存	查询当前SMF系统中的实时库存信息
API005	获取需求单绑定及出库信息	获取单独出库或PN需求单的绑定及出库信息
API006	修改需求单线别及时间	修改需求单线别或建议时间
API007	物料日志信息查询	本接口提供物料出入库日志查询功能
API008	设备状态信息获取	本接口提供设备状态信息查询功能
API009	入库判定接口(可选)	料仓/料架扫完扫码入库前判断,用于MES/ERP对料盘入库进行卡控,同时可更新料盘相关信息
API010	入仓完成通知(可选)	退料放入云仓库位后通知MES/ERP系统
API011	出仓完成通知(可选)	物料从云仓库位取出后通知MES/ERP系统
API012	需求单状态通知(可选)	需求单状态发生变化后通知MES/ERP
API013	获取入库单(可选)	从MES/ERP获取入库单数据

接口流程

工作流程	料仓	MES/ERP
入库	1 扫码后调用5.1入库判定接口 2 分配库位进行入库,入库完成后调用5.2入仓完成通知
出库	3 根据需求单锁定料盘 4 如果打开了自动出库功能,到达建议时间后进行出库, 如果未打开自动出库功能,操作人员手动出库 5 出库后调用5.4出仓完成通知	1 调用6.4获取实时库存 2 调用6.1创建需求单

API详情（MES/ERP提供）

入库判定接口

接口功能

料仓/料架扫完扫码入库前判断,用于MES/ERP对料盘入库进行卡控,同时可更新料盘相关信息

接口地址

由MES/ERP提供

请求方式

POST

接口使用

本接口由MES/ERP系统提供，由SMF端调用。

请求参数

参数名称	类型	描述
reelId	string	料卷ID
fullCode	string	完整的二维码信息

请求内容示例：

{

"reelId": "R006842020081900111",

"fullCode": "LU120819010W;E202008190365;B6H.30060.0T6514692020081904000;R006842020081900111"

}

返回参数

参数名称	类型	是否必须	描述
code	Integer	是	状态。0表示正常，可以入库；其他为异常，不可入库
msg	string	是	提示信息
data			返回数据信息
partNum	String	否	物料编码, 如果为空或不存在,使用条码中解析的物料编码
vendor	String	否	供应商信息, 如果为空或不存在,使用条码中解析的物料编码
qty	Integer	否	物料数量,如果为空或不存在,使用条码中解析的数量
w	Integer	否	料盘大小,如果为空或不存在,使用设备测量尺寸
h	Integer	否	料盘厚度,如果为空或不存在,使用设备测量厚度
produceDate	String	否	生产日期,格式为yyyy-MM-dd HHss
expireDate	String	否	过期时间,格式为 yyyy-MM-dd HHss
batch	String	否	批次信息
mixTime	Integer	否	搅拌时间(锡膏料仓使用)

返回内容示例：

{

"code": 0,

"msg": "ok",

"data": {

"partNum": "6C.33033.151",

"vendor": "88032",

"qty": 10000,

"w": 7,

"h": 8,

"produceDate": "2021-09-14 00:00:00",

"expireDate": "2021-10-28 23:59:59",

"batch": "LU120819010W",

"mixTime": 5

}

}

入仓完成通知

接口功能

退料放入云仓库位后通知MES/ERP系统

接口地址

由MES/ERP系统提供

请求方式

POST

接口使用

本接口由MES/ERP系统提供，由SMF端调用。

请求参数

参数名称	类型	描述
reelId	string	料卷ID, 料盘的唯一码
location	string	库位, 料盘入库的库位位置
source	string	固定值SMF, 用于MES/ERP分辨物料位置
fullCode	string	完整的二维码信息

请求内容示例

{

"reelId": "R04192020052851182",

"location": "4D1410BB0016",

"source": "SMF",

"fullCode": "L160K010415;E20200519 0730;BQT001200234404192020051915000;R04192020052851182"

}

返回参数

参数名称	类型	是否必须	描述
code	Integer	是	状态。0表示正常；其他为异常,异常时此消息会进行重发
msg	string	是	提示信息
data

返回内容：

{

"code": 0,

"msg": "ok",

"data": ""

}

出仓完成通知

接口功能

物料从云仓库位取出后通知MES/ERP系统

接口地址

由MES/ERP系统提供

请求方式

POST

接口使用

本接口由MES/ERP系统提供，由SMF端调用。

请求参数

参数名称	类型	描述
source	string	SMF
reelId	string	料盘唯一码
partNum	string	物料编号
qty	string	数量
boxNo	string	料盘所在料仓
location	string	料盘所在库位信息
hSerial	string	需求单号
so	string	工单号
slotNum	string	需求单中的站位号
feederInfo	string	需求单中的站位信息

示例

请求内容：

{

"source": "SMF",

"reelId": "R04192020052851182",

"partNum": "6H.4R710.20M",

"qty": 5000,

"boxNo": "Box14",

"location": "4D1410BB0016",

"hSerial": "61403",

"so": "2571810",

"slotNum": "6",

"feederInfo": "6-7-3"

}

返回参数

参数名称	类型	是否必须	描述
code	Integer	是	状态。0表示正常；其他为异常,异常时此消息会进行重发
msg	string	是	提示信息
data

返回内容：

{

"code": 0,

"msg": "ok",

"data": ""

}

需求单状态通知

接口功能

需求单状态发生变化后通知MES/ERP

接口地址

由MES/ERP系统提供

请求方式

POST

接口使用

本接口由MES/ERP系统提供，由SMF端调用。

请求参数

参数名称	类型	描述
hSerial	string	需求单编号
status	string	需求单状态信息,Created=已创建; Executed=开始执行;  Completed=已完成; Closed=已关闭
total	Integer	任务料盘数量
out	Integer	已出库料盘数量

示例

{

"hSerial":"61403",

"status":"Executed",

"total": 30,

"out": 30

}

返回参数

参数名称	类型	是否必须	描述
code	Integer	是	状态。0表示正常；其他为异常,异常时此消息会进行重发
msg	string	是	提示信息
data

返回内容：

{

"code": 0,

"msg": "ok",

"data": ""

}

获取入库单

接口功能

从MES/ERP获取入库单数据

接口地址

由MES/ERP系统提供

请求方式

POST

接口使用

本接口由MES/ERP系统提供，由SMF端调用。

请求参数

参数名称	类型	描述
number	string	单号

示例

{

"number":"N2020052851182"

}

返回参数

参数名称	类型	是否必须	描述
code	Integer	是	状态。0表示正常；其他为异常,异常时此消息会进行重发
msg	string	是	提示信息
data			返回数据
number	string	是	入库单号
items	array	是	入库单详情
partNum	string	是	物料编号
qty	int	是	数量

返回内容：

{

"code": 0,

"msg": "ok",

"data": {

"number": "N2020052851182",

"items": [

{

"partNum": "6H.4R710.20M",

"qty": 100000

},

{

"partNum": "6S.53654.32D",

"qty": 130000

}

]

}

}

API详情（SMF提供）

创建需求单

接口功能

创建PN, RI需求单

接口地址

http://IP/smfcore/rest/api/outInfo

请求方式

POST

接口使用

本接口由SMF端提供，由MES/ERP系统调用。

请求参数

参数名称	类型	是否必须	描述
hSerial	string	true	需求单号
type	string	true	动作,可用值为:PN=按物料编号出库,RI=按唯一码出库
line	string	false	线别,AGV运送时使用此值做为目的地
so	string	false	工单号
stme	string	false	建议时间, 格式为yyyy-MM-dd HHss自动出库时会按此字段进行排序,如果值为空或无效,使用需求单的接收时间
outItems		true	需求单详情数据
slotNum	string	false	站位编号, 出库完成时会回传此值
reelId	string	false	料盘唯一码,RI需求单出库时使用
partNum	string	false	料号,PN出库时使用
qty	Integer	false	需求数量
reelCount	Integer	false	需求盘数,需求数量为0时,使用此字段出库reelCount盘partNum的物料
feederInfo	string	false	站位信息,出库完成时会回传此值

返回参数

参数名称	类型	描述
code	string	状态码。0为正常，其他为异常。
msg	string	提示消息
data		返回数据

示例

请求内容：

[

{

"hSerial": "10092",

"type": "PN",

"line": "Line3",

"so": "2441991",

"stme": "2021-09-17 10:23:00",

"outItems": [

{

"partNum": "6C.33033.151",

"qty": 15000,

"slotNum": "14",

"feederInfo": "1-4-16"

},

{

"partNum": "6C.33033.152",

"reelCount": 2,

"slotNum": "15",

"feederInfo": "1-4-17"

}

]

},

{

"hSerial": "10093",

"type": "RI",

"outItems": [

{

"reelId": "R04192020052851182"

},

{

"reelId": "S20052851483"

}

]

}

]

返回内容：

{

"code": 0,

"msg": "ok",

"data": ""

}

修改需求单线别及时间

接口功能

修改需求单线别或建议时间

接口地址

http://IP/smfcore/rest/api/updateOutInfo

请求方式

POST

接口使用

本接口由SMF端提供，由MES/ERP系统调用。

请求参数

参数名称	类型	是否必须	描述
hSerial	string	true	需求单号
line	string	false	线别,如果为空或无效,不进行修改
stme	string	false	建议时间, 格式为yyyy-MM-dd HHss自动出库时会按此字段进行排序,如果值为空或无效,不进行修改

返回参数

参数名称	类型	描述
code	string	状态码。0为正常，其他为异常。
msg	string	提示消息
data	string	返回数据

示例

请求内容：

{

"hSerial": "2107038",

"line": "Line-10",

"stme": "2021-08-11 10:35:00"

}

返回内容：

{

"code": 0,

"msg": "ok",

"data": ""

}

关闭需求单

接口功能

关闭需求单后需求单不可再执行出库,同时会释放掉该需求单所绑定的材料

接口地址

http://IP/smfcore/rest/api/closeOutInfo

请求方式

POST

接口使用

本接口由SMF端提供，由MES/ERP系统调用。

请求参数

参数名称	类型	是否必须	描述
hSerial	string	true	需求单号

返回参数

参数名称	类型	描述
code	string	状态码。0为正常，其他为异常。
msg	string	提示消息
data	string	返回数据

示例

请求内容：

{

"hSerial": "23501"

}

返回内容：

{

"code": 0,

"msg": "ok",

"data": ""

}

线外发料

接口功能

MES/ERP系统进行线外发料时,通知SMF系统,SMF系统在对应需求单发料时,会扣减线外发料的数量

接口地址

http://IP/smfcore/rest/api/outLineSend

请求方式

POST

接口使用

本接口由SMF端提供，由MES/ERP系统调用。

请求参数

参数名称	类型	是否必须	描述
hSerial	string	true	需求单编号
slotNum	string	true	站位编号
reelId	string	true	料盘唯一码
partNum	string	true	料号
qty	Integer	true	发料数量

返回参数

参数名称	类型	描述
code	string	状态码。0为正常，其他为异常。
msg	string	提示消息
data	string	返回数据

示例

请求内容：

{

"hSerial": "2107038",

"slotNum": "10",

"reelid": "R506072020101300178",

"pn": "6H.4R710.20M",

"qty": 2000

}

返回内容：

{

"code": 0,

"msg": "ok",

"data": ""

}

获取实时库存

接口功能

查询当前SMF系统中的实时库存信息

接口地址

http://IP/smf/rest/api/inventory

请求方式

POST

接口使用

本接口由SMF端提供，由MES/ERP系统调用。

请求参数

参数名称	类型	是否必须	描述
partNums	string	false	要查询物料料号列表
reelIds	string	false	要查询的物料唯一码列表
towerIds	string	false	要查询的TowerId列表

注:三个参数都有值时之间是AND关系,如果三个参数都为空,那么取所有的库存信息

返回参数

参数名称	类型	描述
code	string	状态码。0为正常，其他为异常。
msg	string	提示消息
data	string	返回数据
reelId	string	料盘唯一码
partNum	string	料号
qty	int	数量
lot	string	批次信息
checkInTime	string	入库时间,格式为yyyy-MM-dd HHss
expireDate	string	过期日期,格式为yyyy-MM-dd,如果没有过期时间,为空
towerId	string	料盘所有料仓Id
location	string	料盘所在库位
hSerial	string	料盘是否已绑定需求单,如果未绑定为空

示例

请求内容:

{

"reelIds": [

"R04192020052851182",

"R04192020052851183"

]

}

或

{

"partNums": [

"6H.4R710.20M"

],

"towerIds": [

"8003",

"8004"

]

}

返回内容:

{

"code": 0,

"msg": "ok",

"data": [

{

"reelId": "R04192020052851182",

"partNum": "6H.4R710.20M",

"qty": 5000,

"lot": "3258-1",

"checkInTime": "2021-09-22 13:46:50",

"expireDate": "2021-10-22",

"towerId": "8003",

"location": "4D1310BB0016",

"hSerial": "61403"

},

{

"reelId": "R04192020052851183",

"partNum": "6H.4R710.20M",

"qty": 5000,

"lot": "3258-1",

"checkInTime": "2021-09-22 13:48:00",

"expireDate": "2021-10-22",

"towerId": "8004",

"location": "4D1410BB0017",

"hSerial": ""

}

]

}

获取需求单绑定及出库信息

接口功能

获取单独出库或PN需求单的绑定及出库信息

接口地址

http://IP/smfcore/rest/api/hSerialInfo

请求方式

POST

接口使用

本接口由SMF端提供，由MES/ERP系统调用。

请求参数

参数名称	类型	是否必须	描述
hSerialList	string	true	需求单号，如果有多个用分号,分割。

返回参数

参数名称	类型	描述
code	string	状态码。0为正常。其他为异常。
msg	string	提示消息
data	string	返回数据
hSerial	string	需求单号
lockItems	Array	绑定详情
partNum	string	料号
qty	int	需求数量
lockQty	int	绑定数量
lockReels	int	绑定料盘数
outQty	int	出仓数量(已从料仓中取出)
outReels	int	出仓料盘数
sendQty	int	发料数量(放上转运架)
sendReels	int	发料料盘数

示例

请求内容:

{

"hSerialList": [

"211",

"212"

]

}

返回内容:

{

"code":0,

"msg":"ok",

"data":[

{

"hSerial":"211",

"lockItems":[

{

"hSerial":"211",

"partNum":"7H.10528.5F1",

"qty":84150,

"realLockQty":0,

"totalSendQty":0

},

{

"hSerial":"211",

"partNum":"7H.47510.5F1",

"qty":24150,

"realLockQty":0,

"totalSendQty":0

}

]

},

{

"hSerial":"212", 

            "lockItems":[

{

"hSerial":"212",

"partNum":"6C.47234.1D1",

"qty":37950,

"realLockQty":0,

"totalSendQty":0

},

{

"hSerial":"212", 

                    "partNum":"6C.10234.1D1",

"qty":7710, 

                    "realLockQty":0,

"totalSendQty":0

}

]

}

]

}

物料日志信息查询

接口功能

本接口提供物料出入库日志查询功能

接口地址

http://IP/smfcore/rest/api/reelHistory

请求方式

POST

接口使用

本接口由SMF端提供，由MES/ERP系统调用。

请求参数

参数名称	类型	是否必须	描述
reelIdList	array	false	物料唯一标识码,如果为空,返回最近20条的出入日志
num	int	false	返回数据条数,如果为空,默认返回最近20条

返回参数

参数名称	类型	描述
code	string	状态码。0为正常。其他为异常。
msg	string	提示消息
data	string	返回数据
opor	string	操作人
updateTime	string	任务更新时间
posName	string	库位号
qty	int	数量
towerId	string	料仓ID
towerName	string	料仓名称
source	string	指令来源信息
type	int	1=入库 2 为出库
reelId	string	料盘唯一码
partNum	string	物料编号
status	string	任务状态WAIT=等待，EXECUTING=正在执行，PAUSE=已暂停，FINISHED=已完 成，CANCEL=已取消，END=已结束
createTime	string	任务创建时间

示例

请求内容:

{

"reelIdList": [

"R515232020031100130",

"R014212019090800004"

]

}

返回内容:

{

"code": 0,

"msg": "ok",

"data": [

{

"opor": "admin",

"updateTime": "2020-04-07 11:37:02",

"posName": "4D010BB20301",

"qty": 3000,

"towerId": "8001",

"towerName": "BOX 1",

"source": null,

"type": 1,

"reelId": "R515232020031100130",

"partNum": "8C.22R03.A3F",

"status": "FINISHED",

"createTime": "2020-04-07 11:36:42"

},

{

"opor": "",

"updateTime": "2020-04-07 11:37:22",

"posName": "4D010DD20201",

"qty": 3813,

"towerId": "8001",

"boxName": "BOX 1",

"source": null,

"type": 1,

"reelId": "R014212019090800004",

"partNum": "7H.10324.2B1",

"status": "EXECUTING",

"createTime": "2020-04-07 11:37:02"

}

]

}  

设备状态信息获取

接口功能

本接口提供设备状态信息查询功能

接口地址

http://IP/smfcore/rest/api/deviceStatus

请求方式

POST

接口使用

本接口由SMF端提供，由MES/ERP系统调用。

请求参数

参数名称	类型	是否必须	描述
deviceKeyList	array	false	设备标识码,如果为空,返回所有设备的状态信息,

返回参数

参数名称	类型	描述
code	string	状态码。0为正常。其他为异常。
msg	string	提示消息
data	string	返回数据
deviceKey	string	设备标识,由.号分割,第一部分为设备类型,第二部分为设备ID
name	string	设备名称
msgType	int	消息类型, :1=消息2=警告 3=异常
msg	string	消息内容
startTime	string	消息开始时间
updateTime	string	更新时间
deviceData	string	设备的数据信息,详见设备数据信息表

料仓数据信息

towerId	string	料仓ID
barcode	string	正在执行的条码信息
emptySlot		料仓中未使用料格的规格和数量
totalSlot		料仓中料格的规格总数
status	int	料仓状态 -1: 离线
		1: 空闲
		2: 急停
		3: 故障
		4:
		5: 调试中
		6: 入库执行中
		7: 入仓位完成
		8:
		9: 出库执行中
		10: 出仓位完成
		11: 出库完成(放到门口)
		12:
		13: 原点返回中
		14: 入库失败

示例

请求内容:

{

"deviceKeyList ": [

"tower.8001",

"agv.19"

]

}

返回内容:

{

"code": 0,

"msg": "ok",

"data": [

{

"deviceKey": "tower.8001",

"name": "Tower 01",

"msgType": 2,

"msg": "[1066]未识别到有效的条码",

"startTime": "2019-04-12 11:45:19",

"updateTime": "2019-04-12 11:47:10",

"deviceData": {

"towerId": "8001",

"status": 14,

"name": "BOX 1",

"barcode": "",

"doorReelSignal": 0,

"emptySlot": {

"7x8": 800,

"13x8": 70

},

"totalSlot": {

"7x8": 1000,

"13x8": 700

}

}

},

{

"deviceKey": "agv.19",

"name": "19号AGV小车",

"msgType": 1,

"msg": "充电任务[71963]：开始充电任务 ",

"startTime": "2019-04-12 11:40:12",

"updateTime": "2019-04-12 11:46:10",

"deviceData": ""

}

]

}