第10章：商品库

10.1 创建商品

10.1.1 接口说明

创建商品信息，单次请求创建单个商品。商品创建成功后，系统会返回成功响应。

10.1.2 请求信息

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

10.1.3 请求参数

字段名	类型	必填	说明
sku	String	是	SKU，唯一标识，最大长度128，仅支持大写字母、数字、下划线、横线，长度1-20
commodityName	String	是	品名，最大长度255
upcCode	String	否	UPC Code，11-12位数字
weight	BigDecimal	是	重量，单位是Lbs（磅），必须大于0
dimensionsLength	Integer	是	长度，单位是Inch（英寸），必须大于0
dimensionsWidth	Integer	是	宽度，单位是Inch（英寸），必须大于0
dimensionsHeight	Integer	是	高度，单位是Inch（英寸），必须大于0
declaredValue	BigDecimal	否	申报价值，单位是USD，两位小数，必须大于等于0.01
enableExpiryControl	Integer	否	是否效期控制：1：是；0：否
enableLocationControl	Integer	否	是否需要库位管理：1：是；0：否
enableSerialControl	Integer	否	是否需要序列号管理：1：是；0：否

10.1.4 响应参数

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

10.1.5 请求示例

{
  "sku": "SKU123456",
  "commodityName": "iPhone 15 Case",
  "upcCode": "123456789011",
  "weight": 0.5,
  "dimensionsLength": 6,
  "dimensionsWidth": 3,
  "dimensionsHeight": 1,
  "declaredValue": 29.99,
  "enableExpiryControl": 0,
  "enableLocationControl": 0,
  "enableSerialControl": 0
}

10.1.6 响应示例

成功响应

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

失败响应

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

10.1.7 错误码说明

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

10.1.8 注意事项

1. 单次请求创建单个商品，如需创建多个商品，请多次调用接口

2. SKU 必须唯一，不允许重复

3. SKU 格式要求：仅支持大写字母、数字、下划线、横线，长度1-20

4. 重量单位是磅（Lbs），尺寸单位是英寸（Inch）

5. 申报价值单位是美元（USD），保留两位小数

6. 如需批量创建商品，建议在调用方实现批量调用逻辑，并控制并发数量，避免触发限流

10.2 更新商品

10.2.1 接口说明

按照 SKU 更新商品信息。更新时，需要传递完整的商品信息。

10.2.2 请求信息

接口地址：PUT /onixport/api/wms/product/update
请求方式：PUT
Content-Type：application/json

10.2.3 请求参数

字段名	类型	必填	说明
sku	String	是	SKU，唯一标识，最大长度128，仅支持大写字母、数字、下划线、横线，长度1-20
commodityName	String	是	品名，最大长度255
upcCode	String	否	UPC Code，11-12位数字
weight	BigDecimal	是	重量，单位是Lbs（磅），必须大于0
dimensionsLength	Integer	是	长度，单位是Inch（英寸），必须大于0
dimensionsWidth	Integer	是	宽度，单位是Inch（英寸），必须大于0
dimensionsHeight	Integer	是	高度，单位是Inch（英寸），必须大于0
declaredValue	BigDecimal	否	申报价值，单位是USD，两位小数，必须大于等于0.01
enableExpiryControl	Integer	否	是否效期控制：1：是；0：否
enableLocationControl	Integer	否	是否需要库位管理：1：是；0：否
enableSerialControl	Integer	否	是否需要序列号管理：1：是；0：否

10.2.4 响应参数

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

10.2.5 请求示例

{
  "sku": "SKU123456",
  "commodityName": "iPhone 15 Pro Case",
  "upcCode": "123456789012",
  "weight": 0.6,
  "dimensionsLength": 6.5,
  "dimensionsWidth": 3.2,
  "dimensionsHeight": 1.2,
  "declaredValue": 34.99,
  "enableExpiryControl": 0,
  "enableLocationControl": 0,
  "enableSerialControl": 0
}

10.2.6 响应示例

成功响应

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

失败响应

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

10.2.7 错误码说明

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

10.2.8 注意事项

1. 更新商品时，需要传递完整的商品信息

2. SKU 必须已存在，否则更新失败

3. SKU 格式要求：仅支持大写字母、数字、下划线、横线，长度1-20

4. 重量单位是磅（Lbs），尺寸单位是英寸（Inch）

5. 申报价值单位是美元（USD），保留两位小数

10.3 拉取商品信息

10.3.1 接口说明

根据 SKU 拉取商品信息，支持批量查询，单次请求最多允许查询200个商品。

10.3.2 请求信息

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

10.3.3 请求参数

字段名	类型	必填	说明
skuList	Array	是	SKU列表，单次请求最多支持200个商品信息查询，超过200个则丢弃不会返回对应的商品信息

10.3.4 响应参数

字段名	类型	必填	说明
success	Boolean	是	请求是否成功
errorCode	Integer	否	错误码。当 success=true 时，该字段为 null；当 success=false 时，该字段有值
errorMsg	String	否	错误信息。当 success=true 时，该字段为 null；当 success=false 时，该字段有值
result	Array	否	商品信息列表
result[].sku	String	是	SKU，唯一标识
result[].commodityName	String	是	品名
result[].upcCode	String	否	UPC Code
result[].weight	BigDecimal	是	重量，单位是Lbs（磅）
result[].dimensionsLength	Integer	是	长度，单位是Inch（英寸）
result[].dimensionsWidth	Integer	是	宽度，单位是Inch（英寸）
result[].dimensionsHeight	Integer	是	高度，单位是Inch（英寸）
result[].declaredValue	BigDecimal	否	申报价值，单位是USD，两位小数
result[].enableExpiryControl	Integer	否	是否效期控制：1：是；0：否
result[].enableLocationControl	Integer	否	是否需要库位管理：1：是；0：否
result[].enableSerialControl	Integer	否	是否需要序列号管理：1：是；0：否

10.3.5 请求示例

{
  "skuList": ["SKU123456", "SKU123457"]
}

10.3.6 响应示例

成功响应

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "result": [
    {
      "sku": "SKU123456",
      "commodityName": "iPhone 15 Case",
      "upcCode": "123456789011",
      "weight": 0.5,
      "dimensionsLength": 6,
      "dimensionsWidth": 3,
      "dimensionsHeight": 1,
      "declaredValue": 29.99,
      "enableExpiryControl": 0,
      "enableLocationControl": 0,
      "enableSerialControl": 0
    },
    {
      "sku": "SKU123457",
      "commodityName": "iPhone 15 Pro Case",
      "upcCode": "123456789012",
      "weight": 0.6,
      "dimensionsLength": 6.5,
      "dimensionsWidth": 3.2,
      "dimensionsHeight": 1.2,
      "declaredValue": 34.99,
      "enableExpiryControl": 0,
      "enableLocationControl": 0,
      "enableSerialControl": 0
    }
  ]
}

失败响应

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

10.3.7 错误码说明

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

10.3.8 注意事项

1. 单次请求最多支持200个商品查询，超过限制的商品将被丢弃

2. 如果查询的 SKU 不存在，该 SKU 不会出现在返回结果中

3. 返回结果仅包含成功查询到的商品信息

10.4 字段说明

10.4.1 单位说明

字段	单位	说明
weight	Lbs（磅）	商品重量
dimensionsLength	Inch（英寸）	商品长度
dimensionsWidth	Inch（英寸）	商品宽度
dimensionsHeight	Inch（英寸）	商品高度
declaredValue	USD（美元）	申报价值，保留两位小数

10.4.2 控制字段说明

字段	值	说明
enableExpiryControl	0	否
enableExpiryControl	1	是
enableLocationControl	0	否
enableLocationControl	1	是
enableSerialControl	0	否
enableSerialControl	1	是

10.4.3 SKU 格式要求

仅支持大写字母（A-Z）、数字（0-9）、下划线（_）、横线（-）
长度限制：1-20个字符
必须唯一，不允许重复

10.4.4 UPC Code 格式要求

仅支持数字
长度限制：11-12位数字