第11章：入库预报

11.1 创建入库预报

11.1.1 接口说明

创建入库预报单，用于提前通知仓库即将入库的货物信息。支持两种预报类型：SKU Base（SKU预报）和序列号预报（SN Base）。SKU预报适用于只有SKU、没有序列号的货物；序列号预报适用于需要使用序列号入库的货物。

重要说明：如果使用相同的仓库编码（warehouseCode）、货柜号（containerNo）和批次号（batchNo）创建入库预报，新的预报明细会被追加到已有的预报单下，而不是创建新的预报单。这意味着可以通过多次调用创建接口，逐步完善同一批次的入库预报明细。

11.1.2 请求信息

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

11.1.3 请求参数

字段名	类型	必填	说明
forecastType	Integer	是	入库预报类型：1：SKU Base（SKU预报）；2：SN Base（序列号预报）
warehouseCode	String	是	收货仓库编码，可以从获取仓库信息接口获取
containerNo	String	是	入库的货柜号，最大长度32
batchNo	String	是	入库的批次号，最大长度32
inboundItems	Array	是	入库的货物明细列表
inboundItems[].sku	String	是	SKU，SKU必须已经存在于商品库中，否则报错
inboundItems[].serialNo	String	否	序列号，当预报类型是序列号（forecastType=2）时，序列号必填。格式要求：首字母必须是大写字母，后续可以是大写字母、数字、下划线、横线，最大长度32
inboundItems[].forecastQty	Integer	否	入库预报数量，当预报类型是SKU（forecastType=1）时，入库数量必填，必须大于等于1

11.1.4 响应参数

字段名	类型	必填	说明
success	Boolean	是	请求是否成功
errorCode	Integer	否	错误码。当 success=true 时，该字段为 null；当 success=false 时，该字段有值
errorMsg	String	否	错误信息。当 success=true 时，该字段为 null；当 success=false 时，该字段有值
result	null	-	无返回数据

11.1.5 请求示例

示例1：SKU Base 预报

{
  "forecastType": 1,
  "warehouseCode": "W1",
  "containerNo": "TEMU7134202",
  "batchNo": "FPL-US-424",
  "inboundItems": [
    {
      "sku": "SKU123456",
      "forecastQty": 100
    },
    {
      "sku": "SKU123457",
      "forecastQty": 50
    }
  ]
}

示例2：序列号预报

{
  "forecastType": 2,
  "warehouseCode": "W1",
  "containerNo": "TEMU7134202",
  "batchNo": "FPL-US-424",
  "inboundItems": [
    {
      "sku": "SKU123456",
      "serialNo": "SN001234567890"
    },
    {
      "sku": "SKU123456",
      "serialNo": "SN001234567891"
    },
    {
      "sku": "SKU123457",
      "serialNo": "SN002345678901"
    }
  ]
}

11.1.6 响应示例

成功响应

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

失败响应

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

11.1.7 错误码说明

错误码	说明	解决方案
1000	无效的参数	检查请求参数是否完整、格式正确

11.1.8 注意事项

1. 预报类型选择：

SKU Base（forecastType=1）：适用于只有SKU、没有序列号的货物。需要填写 forecastQty（入库预报数量），不需要填写 serialNo。
序列号预报（forecastType=2）：适用于需要使用序列号入库的货物。需要填写 serialNo（序列号），不需要填写 forecastQty。

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

3. 序列号格式要求：

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

4. 货柜号和批次号：

货柜号（containerNo）和批次号（batchNo）最大长度均为32个字符
用于标识同一批次的入库货物

5. 预报单合并规则：

如果使用相同的仓库编码（warehouseCode）、货柜号（containerNo）和批次号（batchNo）创建入库预报，新的预报明细会被追加到已有的预报单下，而不是创建新的预报单
这意味着可以通过多次调用创建接口，逐步完善同一批次的入库预报明细

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

11.6 预报类型说明

11.6.1 SKU Base

类型码	类型描述	说明
1	SKU Base	SKU预报，即货物只有SKU，没有序列号

使用场景：

货物不需要序列号管理
只需要记录SKU和数量即可

必填字段：

inboundItems[].sku：SKU
inboundItems[].forecastQty：入库预报数量

不需要字段：

inboundItems[].serialNo：不需要填写

11.6.2 SN Base

类型码	类型描述	说明
2	SN Base	序列号预报，即货物需要使用序列号入库

使用场景：

货物需要序列号管理
每个货物都有唯一的序列号

必填字段：

inboundItems[].sku：SKU
inboundItems[].serialNo：序列号

不需要字段：

inboundItems[].forecastQty：不需要填写

11.7 字段格式说明

11.7.1 序列号格式要求

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

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

正确示例：

SN001234567890
AUSD124254253223
PROD-2024-001

错误示例：

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

11.7.2 货柜号和批次号

货柜号（containerNo）：用于标识运输货物的货柜，最大长度32个字符
批次号（batchNo）：用于标识同一批次的入库货物，最大长度32个字符

这两个字段用于在仓库收货时匹配预报信息。

11.2 查询入库预报序列号明细

11.2.1 接口说明

分页查询入库预报的序列号明细信息。仅返回按照序列号预报的明细，即创建入库预报时 forecastType=2（SN Base）的明细数据。

11.2.2 请求信息

接口地址：POST /onixport/api/wms/inbound/serialNo/detail
请求方式：POST
Content-Type：application/json

11.2.3 请求参数

字段名	类型	必填	说明
warehouseCode	String	是	收货仓库编码，可以从获取仓库信息接口获取
containerNo	String	是	入库的货柜号，最大长度32
batchNo	String	是	入库的批次号，最大长度32
current	Integer	否	当前页号，默认值为1，从1开始

11.2.4 响应参数

字段名	类型	必填	说明
success	Boolean	是	请求是否成功
errorCode	Integer	否	错误码。当 success=true 时，该字段为 null；当 success=false 时，该字段有值（详见错误码说明或错误码索引）
errorMsg	String	否	错误信息。当 success=true 时，该字段为 null；当 success=false 时，该字段有值
result	Array	否	序列号预报明细列表
result[].warehouseCode	String	是	仓库编码
result[].warehouseName	String	是	收货仓库名称
result[].containerNo	String	是	入库的货柜号
result[].batchNo	String	是	入库的批次号
result[].serialNo	String	是	序列号
result[].sku	String	是	SKU
result[].commodityName	String	是	品名
result[].status	Integer	是	入库预报状态：1：未到仓；2：到仓收货中；3：已收货
result[].receivedTime	String	否	入库预报收货时间（仅在货物已到仓之后才有值），格式：MM/dd/yyyy HH:mm:ss
result[].forecastTime	String	是	入库预报创建时间，格式：MM/dd/yyyy HH:mm:ss
pagination	Object	否	分页信息
pagination.current	Integer	是	当前页码
pagination.pageSize	Integer	是	每页条数，默认10
pagination.total	Long	是	数据总条数

11.2.5 请求示例

{
  "warehouseCode": "W1",
  "containerNo": "TEMU7134202",
  "batchNo": "FPL-US-424",
  "current": 1
}

11.2.6 响应示例

成功响应

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "result": [
    {
      "warehouseCode": "W1",
      "warehouseName": "LA Warehouse",
      "containerNo": "TEMU7134202",
      "batchNo": "FPL-US-424",
      "serialNo": "SN001234567890",
      "sku": "SKU123456",
      "commodityName": "iPhone 15 Case",
      "status": 2,
      "receivedTime": "11/07/2025 10:30:00",
      "forecastTime": "11/01/2025 15:30:00"
    },
    {
      "warehouseCode": "W1",
      "warehouseName": "LA Warehouse",
      "containerNo": "TEMU7134202",
      "batchNo": "FPL-US-424",
      "serialNo": "SN001234567891",
      "sku": "SKU123456",
      "commodityName": "iPhone 15 Case",
      "status": 1,
      "receivedTime": null,
      "forecastTime": "11/01/2025 15:30:00"
    }
  ],
  "pagination": {
    "current": 1,
    "pageSize": 10,
    "total": 2
  }
}

失败响应

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

11.2.7 错误码说明

错误码	说明	解决方案
1000	无效的参数	检查请求参数是否完整、格式正确

11.2.8 注意事项

1. 查询范围：仅返回按照序列号预报（forecastType=2）的明细数据，不包含SKU预报（forecastType=1）的数据

2. 分页查询：支持分页查询，默认每页10条，当前页号默认为1

3. 查询条件：必须同时提供 warehouseCode、containerNo、batchNo 三个条件进行查询

4. 状态说明：

status=1：未到仓
status=2：到仓收货中
status=3：已收货

5. 收货时间：receivedTime 字段仅在货物已到仓（status=2 或 status=3）之后才有值，未到仓时为 null

11.3 查询入库预报SKU明细

11.3.1 接口说明

分页查询入库预报的SKU明细信息。返回以SKU预报的明细，以及返回包含的以序列号预报的SKU明细。即：

包含创建入库预报时 forecastType=1（SKU Base）的明细数据
包含创建入库预报时 forecastType=2（SN Base）的明细数据，但会按SKU聚合显示

11.3.2 请求信息

接口地址：POST /onixport/api/wms/inbound/sku/detail
请求方式：POST
Content-Type：application/json

11.3.3 请求参数

字段名	类型	必填	说明
warehouseCode	String	是	收货仓库编码，可以从获取仓库信息接口获取
containerNo	String	是	入库的货柜号，最大长度32
batchNo	String	是	入库的批次号，最大长度32
current	Integer	否	当前页号，默认值为1，从1开始

11.3.4 响应参数

字段名	类型	必填	说明
success	Boolean	是	请求是否成功
errorCode	Integer	否	错误码。当 success=true 时，该字段为 null；当 success=false 时，该字段有值（详见错误码说明或错误码索引）
errorMsg	String	否	错误信息。当 success=true 时，该字段为 null；当 success=false 时，该字段有值
result	Array	否	SKU预报明细列表
result[].warehouseCode	String	是	仓库编码
result[].warehouseName	String	是	收货仓库名称
result[].containerNo	String	是	入库的货柜号
result[].batchNo	String	是	入库的批次号
result[].sku	String	是	SKU
result[].commodityName	String	是	品名
result[].status	Integer	是	入库预报状态：1：未到仓；2：到仓收货中；3：已收货
result[].forecastQty	Integer	是	入库预报数量
result[].receivedQty	Integer	是	已收货数量
result[].receivedTime	String	否	最新的一次收货时间，格式：MM/dd/yyyy HH:mm:ss
result[].forecastTime	String	是	入库预报创建时间，格式：MM/dd/yyyy HH:mm:ss
pagination	Object	否	分页信息
pagination.current	Integer	是	当前页码
pagination.pageSize	Integer	是	每页条数，默认10
pagination.total	Long	是	数据总条数

11.3.5 请求示例

{
  "warehouseCode": "W1",
  "containerNo": "TEMU7134202",
  "batchNo": "FPL-US-424",
  "current": 1
}

11.3.6 响应示例

成功响应

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "result": [
    {
      "warehouseCode": "W1",
      "warehouseName": "LA Warehouse",
      "containerNo": "TEMU7134202",
      "batchNo": "FPL-US-424",
      "sku": "SKU123456",
      "commodityName": "iPhone 15 Case",
      "status": 2,
      "forecastQty": 100,
      "receivedQty": 80,
      "receivedTime": "11/07/2025 10:30:00",
      "forecastTime": "11/01/2025 15:30:00"
    },
    {
      "warehouseCode": "W1",
      "warehouseName": "LA Warehouse",
      "containerNo": "TEMU7134202",
      "batchNo": "FPL-US-424",
      "sku": "SKU123457",
      "commodityName": "iPhone 15 Pro Case",
      "status": 3,
      "forecastQty": 50,
      "receivedQty": 50,
      "receivedTime": "11/07/2025 11:00:00",
      "forecastTime": "11/01/2025 15:30:00"
    }
  ],
  "pagination": {
    "current": 1,
    "pageSize": 10,
    "total": 2
  }
}

失败响应

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

11.3.7 错误码说明

错误码	说明	解决方案
1000	无效的参数	检查请求参数是否完整、格式正确

11.3.8 注意事项

1. 查询范围：

返回以SKU预报（forecastType=1）的明细数据
返回包含的以序列号预报（forecastType=2）的SKU明细，按SKU聚合显示

2. 分页查询：支持分页查询，默认每页10条，当前页号默认为1

3. 查询条件：必须同时提供 warehouseCode、containerNo、batchNo 三个条件进行查询

4. 状态说明：

status=1：未到仓
status=2：到仓收货中
status=3：已收货

5. 数量字段：

forecastQty：入库预报数量，表示预报的总数量
receivedQty：已收货数量，表示实际已收货的数量
对于序列号预报，forecastQty 为序列号数量，receivedQty 为已收货的序列号数量

6. 收货时间：receivedTime 字段为最新的一次收货时间，如果未收货则为 null

11.4 删除预报单

11.4.1 接口说明

删除指定柜号和批次号下的所有入库预报。仅能删除未到仓的入库预报，如果预报单中已有货物到仓，则无法删除。

11.4.2 请求信息

接口地址：DELETE /onixport/api/wms/inbound/delete
请求方式：DELETE
Content-Type：application/json

11.4.3 请求参数

字段名	类型	必填	说明
warehouseCode	String	是	收货仓库编码，可以从获取仓库信息接口获取
containerNo	String	是	入库的货柜号，最大长度32
batchNo	String	是	入库的批次号，最大长度32

11.4.4 响应参数

字段名	类型	必填	说明
success	Boolean	是	请求是否成功
errorCode	Integer	否	错误码。当 success=true 时，该字段为 null；当 success=false 时，该字段有值（详见错误码说明或错误码索引）
errorMsg	String	否	错误信息。当 success=true 时，该字段为 null；当 success=false 时，该字段有值
result	null	-	无返回数据

11.4.5 请求示例

{
  "warehouseCode": "W1",
  "containerNo": "TEMU7134202",
  "batchNo": "FPL-US-424"
}

11.4.6 响应示例

成功响应

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

失败响应

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

11.4.7 错误码说明

错误码	说明	解决方案
1000	无效的参数	检查请求参数是否完整、格式正确
1000	入库预报不存在	检查 warehouseCode、containerNo、batchNo 是否正确
1000	入库预报不支持删除	该预报单中已有货物到仓，无法删除

11.4.8 注意事项

1. 删除条件：必须同时提供 warehouseCode、containerNo、batchNo 三个条件

2. 删除限制：仅能删除未到仓的入库预报，如果预报单中已有货物到仓（status=2 或 status=3），则无法删除

3. 删除范围：删除该柜号和批次号下的所有预报，包括SKU预报和序列号预报

4. 删除操作：删除操作不可恢复，请谨慎操作

11.5 删除序列号预报

11.5.1 接口说明

删除指定柜号和批次号下的序列号预报。仅能删除未到仓的序列号预报，如果序列号预报已到仓，则无法删除。支持批量删除多个序列号预报，删除结果会分别返回成功和失败的序列号列表。

11.5.2 请求信息

接口地址：DELETE /onixport/api/wms/inbound/deleteSerialNo
请求方式：DELETE
Content-Type：application/json

11.5.3 请求参数

字段名	类型	必填	说明
warehouseCode	String	是	收货仓库编码，可以从获取仓库信息接口获取
containerNo	String	是	入库的货柜号，最大长度32
batchNo	String	是	入库的批次号，最大长度32
serialNoList	Array	是	需要删除的序列号列表，至少包含一个序列号

11.5.4 响应参数

字段名	类型	必填	说明
success	Boolean	是	请求是否成功
errorCode	Integer	否	错误码。当 success=true 时，该字段为 null；当 success=false 时，该字段有值（详见错误码说明或错误码索引）
errorMsg	String	否	错误信息。当 success=true 时，该字段为 null；当 success=false 时，该字段有值
result	Object	否	删除结果
result.deletedSuccessList	Array	否	删除成功的序列号列表
result.deletedSuccessList[].serialNo	String	是	序列号
result.deletedSuccessList[].success	Boolean	是	是否删除成功，值为 true
result.deletedSuccessList[].errorCode	Integer	否	错误码，删除成功时为 null
result.deletedSuccessList[].errorMsg	String	否	错误信息，删除成功时为 null
result.deletedFailureList	Array	否	删除失败的序列号列表
result.deletedFailureList[].serialNo	String	是	序列号
result.deletedFailureList[].success	Boolean	是	是否删除成功，值为 false
result.deletedFailureList[].errorCode	Integer	否	错误原因代码，可根据错误码以及错误原因定位问题
result.deletedFailureList[].errorMsg	String	否	错误原因描述，可根据错误码以及错误原因定位问题

11.5.5 请求示例

{
  "warehouseCode": "W1",
  "containerNo": "TEMU7134202",
  "batchNo": "FPL-US-424",
  "serialNoList": [
    "SN001234567890",
    "SN001234567891",
    "SN002345678901"
  ]
}

11.5.6 响应示例

成功响应（部分成功部分失败）

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "result": {
    "deletedSuccessList": [
      {
        "serialNo": "SN001234567890",
        "success": true,
        "errorCode": null,
        "errorMsg": null
      },
      {
        "serialNo": "SN001234567891",
        "success": true,
        "errorCode": null,
        "errorMsg": null
      }
    ],
    "deletedFailureList": [
      {
        "serialNo": "SN002345678901",
        "success": false,
        "errorCode": 1000,
        "errorMsg": "序列号预报不存在或已到仓，无法删除"
      }
    ]
  }
}

全部成功响应

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "result": {
    "deletedSuccessList": [
      {
        "serialNo": "SN001234567890",
        "success": true,
        "errorCode": null,
        "errorMsg": null
      },
      {
        "serialNo": "SN001234567891",
        "success": true,
        "errorCode": null,
        "errorMsg": null
      }
    ],
    "deletedFailureList": []
  }
}

失败响应（请求参数错误）

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

11.5.7 错误码说明

错误码	说明	解决方案
1000	无效的参数	检查请求参数是否完整、格式正确
1000	入库预报不存在	检查 warehouseCode、containerNo、batchNo 是否正确
1000	序列号预报不存在	检查序列号是否正确，该序列号可能不存在于该预报单中
1000	序列号预报不支持删除	该序列号预报已到仓，无法删除

11.5.8 注意事项

1. 删除条件：必须同时提供 warehouseCode、containerNo、batchNo 三个条件

2. 序列号列表：serialNoList 必须至少包含一个序列号，不能为空

3. 删除限制：仅能删除未到仓的序列号预报，如果序列号预报已到仓（status=2 或 status=3），则无法删除

4. 批量删除：支持批量删除多个序列号预报，每个序列号独立处理，互不影响

5. 删除结果：删除结果会分别返回成功和失败的序列号列表，即使部分序列号删除失败，只要有一个序列号删除成功，success 字段返回 true

6. 删除操作：删除操作不可恢复，请谨慎操作