Appearance

退货单接口文档（reship） ​

基本信息 ​

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

接口方法列表 ​

接口名方法功能描述
wms.reship.status_updatePOST退货单状态更新（支持 FINISH、PARTIN、CLOSE、FAILED、DENY 等状态）
wms.reship.add_completePOST新建与完成退货单
wms.reship.service_refundPOSTWMS退货服务单退款消息（京东云交易订单退款MQ消息）

系统级参数 ​

参数名类型必填名称描述
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.reship.status_update
signstring是签名用于验证请求合法性

签名算法说明 ​

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

接收参数（业务参数） ​

wms.reship.status_update ​

基础字段 ​

参数名类型必填说明
reship_bnstring是退货单号（与 return_order_id 二选一）
return_order_idstring否WMS退货单ID（与 reship_bn 二选一）
statusstring是状态：FINISH（完成）、PARTIN（部分入库）、CLOSE（已关闭）、FAILED（失败）、DENY（拒绝）、ACCEPT（已接单）
io_statusstring否退货状态（当 status 为空时使用）
warehousestring否仓库编码
order_typestring否订单类型
operate_timestring否操作时间，格式：Y-m-d H:i:s，默认当前时间
remarkstring否备注
extend_propsstring/array否扩展属性（JSON字符串或数组），如果 is_sxts 为 1，则走拦截退货单逻辑

物流信息 ​

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

退货明细（item） ​

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

item 数组元素字段：

参数名类型必填说明
product_bnstring是商品货号
normal_numint否良品数量
defective_numint否残次品数量
item_idstring否WMS明细ID
extend_propsstring/array否明细扩展属性
sn_listarray否序列号列表（支持唯一码的商品），格式：{"sn": ["SN001", "SN002"]} 或 {"sn": "SN001"}
batcharray否批次信息数组

batch 数组元素字段：

参数名类型必填说明
batchCodestring否批次号（采购批次）
produceCodestring否生产批次号
productDatestring否生产日期，格式：Y-m-d
expireDatestring否过期日期，格式：Y-m-d
inventoryTypestring否库存类型：ZP（良品）、CC（残次品）
actualQtyint是实际数量

wms.reship.add_complete ​

基础字段 ​

参数名类型必填说明
returnOrderIdstring是WMS退货单ID
return_order_idstring是退货单号
warehouse_codestring否仓库编码
branch_bnstring否仓库编码（与 warehouse_code 二选一）
logistics_codestring否物流公司编码
logistics_namestring否物流公司名称
express_codestring否快递单号
order_confirm_timestring否订单确认时间，格式：Y-m-d H:i:s，默认当前时间
remarkstring否备注

退货明细（items） ​

参数名类型必填说明
itemsstring是退货明细（JSON字符串），数组格式

items 数组元素字段：

参数名类型必填说明
sourceOrderCodestring否源订单号
subSourceOrderCodestring是子订单号（必填）
itemCodestring否商品货号
actualQtyint否实际数量
batchsarray否批次信息对象

batchs.batch 数组元素字段：

参数名类型必填说明
inventoryTypestring否库存类型：ZP（良品）、CC（残次品）
actualQtyint是实际数量

wms.reship.service_refund ​

参数名类型必填说明
reship_bnstring否退货单号

注意：此接口用于京东云交易订单退款MQ消息，消息主题：ct_order_refund

响应参数 ​

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

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

数据示例 ​

请求示例（退货单状态更新） ​

json
{
  "flag": "erpapi",
  "app_id": "ecos.ome",
  "method": "wms.reship.status_update",
  "timestamp": 1700000000,
  "sign": "...",
  "reship_bn": "R20250101001",
  "status": "FINISH",
  "warehouse": "WH001",
  "logi_no": "SF1234567890",
  "logistics": "SF",
  "operate_time": "2025-01-01 10:00:00",
  "item": "[{\"product_bn\":\"SKU001\",\"normal_num\":2,\"defective_num\":0,\"sn_list\":{\"sn\":[\"SN001\",\"SN002\"]},\"batch\":[{\"batchCode\":\"BATCH001\",\"produceCode\":\"PROD001\",\"productDate\":\"2024-01-01\",\"expireDate\":\"2025-01-01\",\"inventoryType\":\"ZP\",\"actualQty\":2}]}]"
}

响应示例 ​

响应成功 ​

退货单状态更新成功（wms.reship.status_update）：

json
{
    "rsp": "succ",
    "msg": "退货单状态更新成功",
    "data": {
        "reship_bn": "R20250101001"
    }
}

响应失败 ​

退货单状态更新失败（退货单号必填）：

json
{
    "rsp": "fail",
    "msg": "退货单号必填"
}

退货单状态更新失败（缺少参数）：

json
{
    "rsp": "fail",
    "msg": "缺少参数"
}

业务描述 ​

状态说明 ​

  • FINISH：完成，退货单已完成
  • PARTIN：部分入库，支持部分入库场景
  • CLOSE：已关闭，退货单已关闭
  • FAILED：失败，退货单处理失败
  • DENY：拒绝，退货单被拒绝
  • ACCEPT：已接单，退货单已接单

状态映射 ​

WMS 状态到 OMS 状态的映射关系：

WMS状态OMS状态
FINISHFINISH
PARTINPARTIN
CLOSE, FAILED, DENYCLOSE
其他原状态

拦截退货单 ​

如果 extend_props 中的 is_sxts 为 1，则走拦截退货单逻辑（lanjieReship），此时需要传递以下参数：

  • reship_bn：退货单号
  • logistics_code：物流公司编码
  • logistics_name：物流公司名称
  • express_code：快递单号
  • warehouse：仓库编码
  • branch_bn：仓库编码（用于查找OMS仓库）
  • remark：备注
  • order_confirm_time：订单确认时间
  • item：退货明细，需要包含 subSourceOrderCode（子订单号）和 extendProps（扩展属性，包含 tradeReturnId）

明细处理 ​

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

新建与完成退货单 ​

add_complete 接口用于新建与完成退货单，需要传递：

  • return_order_id：退货单号
  • items：退货明细数组，每个明细必须包含 subSourceOrderCode（子订单号）
  • 系统会根据 subSourceOrderCode 关联订单明细

幂等性 ​

  • 相同 reship_bn 或 return_order_id 重复推送时，如果状态不同，系统会更新状态
  • 如果状态相同，系统会进行幂等处理

错误码定义 ​

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