库存管理接口

库存管理接口用于商户同步库存信息到电商平台，包括库存更新、查询等功能。

# 1. 库存批量更新

POST /merchant/inventory/batch-update

批量更新多个商品的库存数量。

请求参数

参数名 类型 必填 描述
items Array 是 库存更新项列表

items数组中每个对象结构：

字段名 类型 必填 描述
sku_code String 是 商品SKU编码
stock Integer 是 最新库存数量(绝对值)
warehouse_code String 否 仓库编码，不传则为默认仓库

响应参数

字段名 类型 描述
success_count Integer 成功更新的商品数量
fail_count Integer 更新失败的商品数量
fail_details Array 失败详情

请求示例

{
  "items": [
    {
      "sku_code": "SP123456",
      "stock": 88
    },
    {
      "sku_code": "SP789012",
      "stock": 120,
      "warehouse_code": "WH001"
    }
  ]
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "success_count": 2,
    "fail_count": 0,
    "fail_details": []
  },
  "timestamp": 1623123456789
}

# 2. 单个商品库存更新

POST /merchant/inventory/update

更新单个商品的库存数量。

请求参数

参数名 类型 必填 描述
sku_code String 是 商品SKU编码
stock Integer 是 最新库存数量(绝对值)
warehouse_code String 否 仓库编码，不传则为默认仓库

响应参数

字段名 类型 描述
sku_code String 商品SKU编码
stock Integer 更新后的库存数量

请求示例

{
  "sku_code": "SP123456",
  "stock": 100
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "sku_code": "SP123456",
    "stock": 100
  },
  "timestamp": 1623123456789
}

# 3. 库存增减操作

# 4. 库存查询

GET /merchant/inventory/query

查询商品当前库存状态。

请求参数

参数名 类型 必填 描述
sku_code String 是 商品SKU编码
warehouse_code String 否 仓库编码，不传则查询所有仓库

响应参数

字段名 类型 描述
sku_code String 商品SKU编码
total_stock Integer 总库存数量
warehouse_stocks Array 各仓库库存详情

warehouse_stocks数组中每个对象结构：

字段名 类型 描述
warehouse_code String 仓库编码
warehouse_name String 仓库名称
available_stock Integer 可用库存
locked_stock Integer 锁定库存(如已下单未出库)

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "sku_code": "SP123456",
    "total_stock": 86,
    "warehouse_stocks": [
      {
        "warehouse_code": "default",
        "warehouse_name": "默认仓库",
        "available_stock": 80,
        "locked_stock": 6
      },
      {
        "warehouse_code": "WH001",
        "warehouse_name": "北京仓",
        "available_stock": 0,
        "locked_stock": 0
      }
    ]
  },
  "timestamp": 1623123456789
}

# 5. 库存变更通知

POST {merchant_callback_url}/inventory/change-notify

当平台端发生库存变更（如用户下单、取消订单等）时，平台将通过此通知接口向商户系统推送库存变更信息。商户需要提供接收此通知的接口。

请求参数

参数名 类型 必填 描述
sku_code String 是 商品SKU编码
quantity Integer 是 变更数量，正数为增加，负数为减少
warehouse_code String 是 仓库编码
change_type String 是 变更类型：order-订单，cancel-取消，return-退货
order_code String 否 关联订单号
timestamp Long 是 事件发生时间戳

响应参数

字段名 类型 描述
success Boolean 是否处理成功
message String 处理结果说明

请求示例

{
  "sku_code": "SP123456",
  "quantity": -2,
  "warehouse_code": "default",
  "change_type": "order",
  "order_code": "ORD20230601123456",
  "timestamp": 1623123456789
}

响应示例

{
  "success": true,
  "message": "操作成功"
}