入库单接口文档（stockin）

基本信息

• 接口地址：/index.php/api
• 请求方法：POST
• 接口类型：接收方接口（第三方 WMS 平台推送 → OMS 接收）
• 路由参数：method = wms.stockin.{action}

接口方法列表

接口名	方法	功能描述
wms.stockin.status_update	POST	入库单状态更新（支持 FINISH、PARTIN 状态）

系统级参数

参数名	类型	必填	名称	描述
flag	string	是	接入标识	固定值 erpapi
app_id	string	是	应用ID	如 ecos.ome
certi_id	string	是	证书ID	系统证书编号
from_node_id	string	是	来源节点	推送方节点ID
node_id	string	是	目标节点	店铺节点ID（OMS节点）
node_type	string	是	节点类型	如 ecos.ome
timestamp	int	是	时间戳	10位时间戳
method	string	是	接口方法名	形如 wms.stockin.status_update
sign	string	是	签名	用于验证请求合法性

签名算法说明

• 生成公式：sign = strtoupper(md5(strtoupper(md5(assemble($params))). $token))
• 要点：
  • 参与签名的参数集合不包含 sign 本身；常以键名排序后按约定拼装
  • 首次 md5 后转大写，与 token 拼接后再 md5，最终再转大写
  • 保持编码一致、去除多余空白

接收参数（业务参数）

基础字段

参数名	类型	必填	说明
stockin_bn	string	是	入库单号（与 entry_order_id 二选一）
entry_order_id	string	否	WMS入库单ID（与 stockin_bn 二选一）
status	string	是	状态：FINISH（完成）、PARTIN（部分入库）
io_status	string	否	入库状态（当 status 为空时使用）
warehouse	string	否	仓库编码
type	string	否	入库类型：CGRK（采购入库）等
operate_time	string	否	操作时间，格式：Y-m-d H:i:s，默认当前时间
remark	string	否	备注
extendProps	string/array	否	扩展属性（JSON字符串或数组）

入库明细（item）

参数名	类型	必填	说明
item	string	否	入库明细（JSON字符串），数组格式

item 数组元素字段：

参数名	类型	必填	说明
product_bn	string	是	商品货号
normal_num	int	否	良品数量
defective_num	int	否	残次品数量
tid	string	否	订单号
oid	string	否	子订单号
item_id	string	否	WMS明细ID
orderLineNo	string	否	订单行号
extendProps	array	否	明细扩展属性
sn_list	array	否	序列号列表（支持唯一码的商品）
batch	array	否	批次信息数组

batch 数组元素字段：

参数名	类型	必填	说明
batchCode	string	否	批次号（采购批次）
produceCode	string	否	生产批次号
productDate	string	否	生产日期，格式：Y-m-d
expireDate	string	否	过期日期，格式：Y-m-d
inventoryType	string	否	库存类型：ZP（良品）、CC（残次品）
actualQty	int	是	实际数量

注意：

• item 参数需要 JSON 编码后传递
• 相同 product_bn 的明细会自动合并数量（良品和残次品分别合并）
• 批次信息支持多维数组格式
• 如果 normal_num 和 defective_num 都为空，则根据 inventoryType 判断

响应参数

响应格式统一为 JSON，包含以下字段：

字段名	类型	必填	说明
rsp	string	是	响应状态：succ（成功）或 fail（失败）
msg	string	否	响应消息（成功时包含操作描述，失败时包含错误信息）
data	object	否	响应数据（成功时可能包含入库单号等信息）

数据示例

请求示例（入库单状态更新）

{
  "flag": "erpapi",
  "app_id": "ecos.ome",
  "method": "wms.stockin.status_update",
  "timestamp": 1700000000,
  "sign": "...",
  "stockin_bn": "I20250101001",
  "status": "FINISH",
  "warehouse": "WH001",
  "type": "CGRK",
  "operate_time": "2025-01-01 10:00:00",
  "item": "[{\"product_bn\":\"SKU001\",\"normal_num\":10,\"defective_num\":0,\"batch\":[{\"batchCode\":\"BATCH001\",\"produceCode\":\"PROD001\",\"productDate\":\"2024-01-01\",\"expireDate\":\"2025-01-01\",\"inventoryType\":\"ZP\",\"actualQty\":10}]}]"
}

响应示例

响应成功

入库单状态更新成功（wms.stockin.status_update）：

{
    "rsp": "succ",
    "msg": "入库单状态更新成功",
    "data": {
        "stockin_bn": "I20250101001"
    }
}

响应失败

入库单状态更新失败（入库单号必填）：

{
    "rsp": "fail",
    "msg": "入库单号必填"
}

入库单状态更新失败（参数不符合规范）：

{
    "rsp": "fail",
    "msg": "参数不符合规范"
}

业务描述

入库类型判断

系统会根据入库单号前缀或 type 参数自动判断入库类型：

单号前缀	入库类型	说明
I	PURCHASE	采购入库
T	ALLCOATE	调拨入库
D	DEFECTIVE	残损入库
DC	WAREHOUSE	转仓入库（需安装warehouse模块）
O 或其他	OTHER	其他入库

特殊处理：

• 如果 type 参数为 CGRK，则入库类型为 PURCHASE（采购入库）
• 如果入库单号在采购单（PO）中存在，则入库类型为 PURCHASE
• 如果入库单号在ASN中存在，则入库类型为 OTHER

状态说明

• FINISH：完成，入库单已完成
• PARTIN：部分入库，支持部分入库场景，相同单号可以多次推送，系统会合并明细

明细处理

1. 数量合并：相同 product_bn 的明细会自动合并，良品数量和残次品数量分别累加
2. 批次信息：支持批次管理的商品需要传递批次信息，系统会记录批次号、生产日期、过期日期等
3. 库存类型：通过 inventoryType 字段区分良品（ZP）和残次品（CC）
4. 唯一码：支持唯一码的商品需要传递序列号列表

幂等性

• 相同 stockin_bn 或 entry_order_id 重复推送时，如果状态为 PARTIN，系统会合并明细并更新状态
• 如果状态不是 PARTIN，系统会进行幂等处理

博世官旗特殊处理

• 节点ID为 1483180733（生产环境）或 1236120430（测试环境）时，会将 remark 作为 arrival_no（到货单号）处理

错误码定义

• E_PARAM：参数缺失或格式不正确（如：入库单号必填、参数不符合规范等）
• E_STATE：业务状态不允许
• E_DUPLICATE：重复提交
• E_INTERNAL：内部处理异常