Appearance

出库单接口文档（stockout） ​

基本信息 ​

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

接口方法列表 ​

接口名方法功能描述
wms.stockout.status_updatePOST出库单状态更新（支持 FINISH、PARTIN 状态）

系统级参数 ​

参数名类型必填名称描述
flagstring是接入标识固定值 erpapi
app_idstring是应用ID如 ecos.ome
certi_idstring是证书ID系统证书编号
from_node_idstring是来源节点推送方节点ID
node_idstring是目标节点店铺节点ID（OMS节点）
node_typestring是节点类型如 ecos.ome
timestampint是时间戳10位时间戳
methodstring是接口方法名形如 wms.stockout.status_update
signstring是签名用于验证请求合法性

签名算法说明 ​

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

接收参数（业务参数） ​

基础字段 ​

参数名类型必填说明
stockout_bnstring是出库单号（与 delivery_order_id 二选一）
delivery_order_idstring否WMS出库单ID（与 stockout_bn 二选一）
statusstring是状态：FINISH（完成）、PARTIN（部分出库）
io_statusstring否出库状态（当 status 为空时使用）
warehousestring否仓库编码
typestring否出库类型：CGTH（采购退货）、JITCK（JIT出库）等
operate_timestring否操作时间，格式：Y-m-d H:i:s，默认当前时间
remarkstring否备注
extendPropsstring/array否扩展属性（JSON字符串或数组）

物流信息 ​

参数名类型必填说明
logi_nostring否运单号
out_delivery_bnstring否外部发货单号
logisticsstring否物流公司编码

包裹信息 ​

参数名类型必填说明
packagesstring否包裹信息（JSON字符串），包含包裹编码、物流编码、快递单号、明细等

packages 格式：

json
{
  "package": [
    {
      "packageCode": "PKG001",
      "logisticsCode": "SF",
      "expressCode": "SF1234567890",
      "weight": "1.5",
      "items": {
        "item": [
          {
            "itemCode": "SKU001",
            "itemId": "ITEM001",
            "quantity": 2
          }
        ]
      }
    }
  ]
}

出库明细（item） ​

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

item 数组元素字段：

参数名类型必填说明
product_bnstring是商品货号（系统会自动过滤空格和全角空格）
numint否数量（与 normal_num 二选一）
normal_numint否良品数量（与 num 二选一）
defective_numint否残次品数量
item_idstring否WMS明细ID
sn_listarray否序列号列表（支持唯一码的商品）
batcharray否批次信息数组

batch 数组元素字段（支持嵌套格式）：

参数名类型必填说明
batcharray否批次数组（如果存在，则从 batch.batch 中提取）
batchCodestring否批次号（采购批次）
produceCodestring否生产批次号
productDatestring否生产日期，格式：Y-m-d
expireDatestring否过期日期，格式：Y-m-d
actualQtyint是实际数量

注意：

  • item 参数需要 JSON 编码后传递
  • 相同 product_bn 的明细会自动合并数量
  • 批次信息支持嵌套格式：{"batch": {"batch": [...]}}
  • 如果主单无运单号，会从包裹信息中提取

响应参数 ​

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

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

数据示例 ​

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

json
{
  "flag": "erpapi",
  "app_id": "ecos.ome",
  "method": "wms.stockout.status_update",
  "timestamp": 1700000000,
  "sign": "...",
  "stockout_bn": "H20250101001",
  "status": "FINISH",
  "warehouse": "WH001",
  "type": "CGTH",
  "logi_no": "SF1234567890",
  "operate_time": "2025-01-01 10:00:00",
  "item": "[{\"product_bn\":\"SKU001\",\"num\":5,\"batch\":{\"batch\":[{\"batchCode\":\"BATCH001\",\"produceCode\":\"PROD001\",\"productDate\":\"2024-01-01\",\"expireDate\":\"2025-01-01\",\"actualQty\":5}]}}]"
}

响应示例 ​

响应成功 ​

出库单状态更新成功（wms.stockout.status_update）：

json
{
    "rsp": "succ",
    "msg": "出库单状态更新成功",
    "data": {
        "stockout_bn": "H20250101001"
    }
}

响应失败 ​

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

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

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

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

业务描述 ​

出库类型判断 ​

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

单号前缀出库类型说明
HPURCHASE_RETURN采购退货
RALLCOATE调拨出库
BDEFECTIVE残损出库
U 或其他OTHER其他出库

特殊处理：

  • 如果 type 参数为 CGTH，则出库类型为 PURCHASE_RETURN（采购退货）
  • 如果 type 参数为 JITCK，则出库类型为 VOPSTOCKOUT（JIT出库）

状态说明 ​

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

明细处理 ​

  1. 数量合并：相同 product_bn 的明细会自动合并数量
  2. 批次信息：支持批次管理的商品需要传递批次信息，支持嵌套格式
  3. 唯一码：支持唯一码的商品需要传递序列号列表
  4. 货号过滤：系统会自动过滤 product_bn 中的空格和全角空格

包裹信息处理 ​

  • 如果主单无运单号，系统会从包裹信息中提取第一个包裹的运单号和物流公司编码
  • 包裹重量会自动累加到主单重量（乘以 1000 转换为克）
  • 包裹明细会转换为出库明细格式

幂等性 ​

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

错误码定义 ​

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