第14章：退货预报

14.1 创建退货预报

14.1.1 接口说明

创建退货预报单，用于提前通知仓库即将退货的货物信息。退货预报需要关联原始出库订单，支持序列号退货和SKU退货两种方式。

14.1.2 请求信息

• 接口地址：POST /onixport/api/wms/returned/create
• 请求方式：POST
• Content-Type：application/json

14.1.3 请求参数

14.1.4 响应参数

14.1.5 请求示例

示例1：带序列号的退货预报

{
  "warehouseCode": "W1",
  "originalOrderNo": "VIBE-2342421",
  "serialNo": "ASHU14141411",
  "sku": "SKU131313",
  "originalTrackingNo": "8781131313",
  "returnTrackingNo": "8781131314",
  "returnReason": [101, 201],
  "returnOtherReason": "产品有质量问题，客户要求退货"
}

示例2：不带序列号的退货预报

{
  "warehouseCode": "W1",
  "originalOrderNo": "VIBE-2342421",
  "sku": "SKU131313",
  "originalTrackingNo": "8781131313",
  "returnTrackingNo": "8781131314",
  "returnReason": [301]
}

14.1.6 响应示例

成功响应

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "result": {
    "orderNo": "RUT242424"
  }
}

失败响应

{
  "success": false,
  "errorCode": 1000,
  "errorMsg": "无效的参数",
  "result": null
}

14.1.7 错误码说明

14.1.8 注意事项

1. 序列号要求：

• 如果商品需要序列号管理（enableSerialControl=1），则退货预报时必须填写 serialNo
• 如果商品不需要序列号管理，则不需要填写 serialNo

2. 原始订单号：

• 必须关联已存在的出库订单
• 格式要求：仅支持字母、数字、下划线（_）、横线（-）
• 最大长度32个字符

3. SKU要求：SKU必须已经存在于商品库中，否则创建失败。创建商品请参考商品库API文档。

4. 序列号格式要求：

• 首字母必须是大写字母（A-Z）
• 后续字符可以是：大写字母（A-Z）、数字（0-9）、下划线（_）、横线（-）
• 最大长度32个字符

5. 仓库编码：可以从获取仓库信息接口获取可用的仓库编码。

6. 退货原因：可以选择多个退货原因编码，详见退货原因说明。

14.2 更新退货预报

14.2.1 接口说明

更新已创建的退货预报单信息。可以更新退货跟踪号、退货原因等信息。

重要说明：

• 未到仓状态（status=1）：可以更新所有字段
• 已到仓状态（status=2）：只能更新以下字段：
• originalOrderNo：原始出库订单号
• returnTrackingNo：退货跟踪号
• originalTrackingNo：原始跟踪号
• returnReason：退货原因编码
• returnOtherReason：退货的其他原因
• 已到仓状态下，以下字段不允许更新：
• warehouseCode：退货仓库编码
• serialNo：序列号
• sku：SKU

14.2.2 请求信息

• 接口地址：PUT /onixport/api/wms/returned/update/{orderNo}
• 请求方式：PUT
• Content-Type：application/json

14.2.3 路径参数

14.2.4 请求参数

字段更新限制说明：

• 未到仓状态（status=1）：可以更新所有字段
• 已到仓状态（status=2）：只能更新以下字段：
• originalOrderNo、originalTrackingNo、returnTrackingNo、returnReason、returnOtherReason
• 不允许更新：warehouseCode、serialNo、sku

14.2.5 响应参数

14.2.6 请求示例

示例1：未到仓状态更新（可更新所有字段）

PUT /onixport/api/wms/returned/update/RTU13424424

{
  "warehouseCode": "W1",
  "originalOrderNo": "VIBE-2342421",
  "serialNo": "ASHU14141411",
  "sku": "SKU131313",
  "originalTrackingNo": "8781131313",
  "returnTrackingNo": "8781131315",
  "returnReason": [101],
  "returnOtherReason": "更新退货跟踪号"
}

示例2：已到仓状态更新（只能更新特定字段）

PUT /onixport/api/wms/returned/update/RTU13424424

{
  "originalOrderNo": "VIBE-2342421",
  "originalTrackingNo": "8781131313",
  "returnTrackingNo": "8781131315",
  "returnReason": [101, 201],
  "returnOtherReason": "更新退货原因和跟踪号"
}

注意：已到仓状态下，请求体中不应包含 warehouseCode、serialNo、sku 字段，即使包含也会被忽略或返回错误。

14.2.7 响应示例

成功响应

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "result": null
}

失败响应

示例1：退货预报单不存在

{
  "success": false,
  "errorCode": 1002,
  "errorMsg": "退货预报单不存在",
  "result": null
}

示例2：已到仓状态不允许更新该字段

{
  "success": false,
  "errorCode": 1003,
  "errorMsg": "已到仓状态不允许更新该字段",
  "result": null
}

14.2.8 错误码说明

14.2.9 注意事项

1. 订单号：路径参数中的 orderNo 必须是已存在的退货预报单号。

2. 更新限制 - 已到仓状态：

• 当退货预报单状态为"已到仓"（status=2）时，只能更新以下字段：
• originalOrderNo：原始出库订单号
• returnTrackingNo：退货跟踪号
• originalTrackingNo：原始跟踪号
• returnReason：退货原因编码
• returnOtherReason：退货的其他原因
• 已到仓状态下，以下字段不允许更新：
• warehouseCode：退货仓库编码
• serialNo：序列号
• sku：SKU
• 如果尝试更新不允许的字段，系统将返回错误

3. 更新限制 - 未到仓状态：

• 当退货预报单状态为"未到仓"（status=1）时，可以更新所有字段

4. 返回值说明：更新接口成功时，result 字段为 null，不返回订单号信息。订单号通过路径参数 orderNo 传入，无需从响应中获取。

5. 其他注意事项：参考创建退货预报的注意事项。

14.3 拉取退货预报信息

14.3.1 接口说明

批量查询退货预报信息。可以根据IWIN退货预报订单号查询退货预报的详细信息，包括退货状态、收货信息等。

14.3.2 请求信息

• 接口地址：POST /onixport/api/wms/returned/info
• 请求方式：POST
• Content-Type：application/json

14.3.3 请求参数

14.3.4 响应参数

14.3.5 请求示例

{
  "orderNoList": ["RUT5435353121", "RTU13424424"]
}

14.3.6 响应示例

成功响应

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "result": [
    {
      "orderNo": "RUT5435353121",
      "warehouseCode": "W1",
      "warehouseName": "LA Warehouse",
      "originalOrderNo": "VIBE-242424311",
      "serialNo": "AUS124242413412",
      "sku": "SKU12432424",
      "commodityName": "SKU1242424",
      "originalTrackingNo": "8942413412",
      "returnTrackingNo": "8942413413",
      "returnReasonCodeList": [101, 201],
      "returnReason": "产品破损/有瑕疵/功能异常, 发错货/数量不对",
      "returnOtherReason": null,
      "status": 2,
      "statusDesc": "已到仓",
      "receivedUserName": "OP",
      "receivedTime": "2025-11-20 10:30:00",
      "qcResult": []
    },
    {
      "orderNo": "RTU13424424",
      "warehouseCode": "W1",
      "warehouseName": "LA Warehouse",
      "originalOrderNo": "VIBE-2342421",
      "serialNo": "ASHU14141411",
      "sku": "SKU131313",
      "commodityName": "SKU131313",
      "originalTrackingNo": "8781131313",
      "returnTrackingNo": "8781131314",
      "returnReasonCodeList": [301],
      "returnReason": "临时取消需求",
      "returnOtherReason": null,
      "status": 1,
      "statusDesc": "未到仓",
      "receivedUserName": null,
      "receivedTime": null,
      "qcResult": null
    }
  ]
}

失败响应

{
  "success": false,
  "errorCode": 1000,
  "errorMsg": "无效的参数",
  "result": null
}

14.3.7 错误码说明

14.3.8 注意事项

1. 批量查询限制：单次请求最多支持100个订单号查询，超过100个则丢弃不会返回对应的订单信息。

2. 查询条件：如果不传递 orderNoList，将返回所有退货预报信息（如果系统支持）。

3. 状态说明：

• status=1：未到仓，退货货物尚未到达仓库
• status=2：已到仓，退货货物已到达仓库并完成收货

4. 收货时间：receivedTime 为仓库本地时间，格式为 yyyy-MM-dd HH:mm:ss。

5. 质检结果：qcResult 字段包含质检结果信息，格式为数组。

14.4 退货原因说明

14.4.1 退货原因编码

退货原因编码用于标识退货的具体原因，支持选择多个原因。以下是所有可用的退货原因编码：

14.4.2 使用说明

1. 多选支持：returnReason 字段支持传入数组，可以选择多个退货原因编码，例如：[101, 201]。

2. 其他原因：如果选择编码 501（其他），建议在 returnOtherReason 字段中填写具体的退货原因说明。

3. 必填说明：returnReason 字段为可选字段，但建议填写以便于仓库处理退货。

14.5 字段格式说明

14.5.1 序列号格式要求

序列号必须符合以下格式：

• 首字符：必须是大写字母（A-Z）
• 后续字符：可以是大写字母（A-Z）、数字（0-9）、下划线（_）、横线（-）
• 长度限制：最大32个字符

正确示例：

• ASHU14141411
• AUS124242413412
• SN001234567890

错误示例：

• ashu14141411（首字母必须大写）
• 1234567890（首字符必须是字母）
• SN 001234567890（不能包含空格）

14.5.2 订单号格式要求

• 原始订单号（originalOrderNo）：
• 格式：仅支持字母、数字、下划线（_）、横线（-）
• 最大长度32个字符
• 必须关联已存在的出库订单

• 退货预报订单号（orderNo）：
• 由系统自动生成
• 格式：RUT + 数字（如：RUT242424、RTU13424424）
• 唯一标识

14.5.3 跟踪号格式要求

• 原始跟踪号（originalTrackingNo）：出库时的跟踪号，最大长度32个字符
• 退货跟踪号（returnTrackingNo）：退货回仓库时的跟踪号，最大长度32个字符

14.6 业务流程图

14.6.1 退货预报流程

1. 客户发起退货
   ↓
2. 创建退货预报（调用创建接口）
   ↓
3. 系统返回退货预报单号（orderNo）
   ↓
4. 客户发货回仓库
   ↓
5. 仓库收货（状态更新为"已到仓"）
   ↓
6. 查询退货预报信息（调用查询接口）
   ↓
7. 查看收货状态和质检结果

14.6.2 状态流转

• 未到仓（status=1） → 已到仓（status=2）
• 当仓库完成收货操作后，状态自动更新为"已到仓"

14.7 常见问题

14.7.1 退货预报创建失败

问题：创建退货预报时返回错误码 1001（SKU不存在）

解决方案：

1. 确保SKU已存在于商品库中

2. 检查SKU格式是否正确

3. 如果SKU不存在，请先调用创建商品接口创建商品

14.7.2 序列号格式错误

问题：创建退货预报时提示序列号格式错误

解决方案：

1. 检查序列号首字符是否为大写字母

2. 检查序列号是否包含不允许的字符（如空格、特殊符号）

3. 检查序列号长度是否超过32个字符

14.7.3 原始订单号不存在

问题：创建退货预报时提示原始订单号不存在

解决方案：

1. 检查原始订单号是否正确

2. 确保该订单号对应的出库订单已存在

3. 检查订单号格式是否符合要求