商品管理接口
商品管理接口用于商户同步商品信息到电商平台，包括商品基础信息、价格、库存、图片等数据。
# 1. 商品列表同步
POST
/merchant/product/batch-sync
将商户系统中的商品信息批量同步到平台。
请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| products | Array | 是 | 商品信息列表 |
products数组中每个商品对象结构：
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| sku_code | String | 是 | 商品SKU编码，唯一标识 |
| name | String | 是 | 商品名称 |
| image | String | 是 | 主图URL |
| images | Array | 是 | 商品图片URL数组 |
| category_id | Integer | 是 | 分类ID |
| price | Decimal | 是 | 售价 |
| original_price | Decimal | 否 | 原价 |
| stock | Integer | 是 | 库存数量 |
| unit | String | 是 | 单位 |
| weight | Decimal | 否 | 重量(kg) |
| volume | Decimal | 否 | 体积(m³) |
| status | Integer | 是 | 状态：1-上架，0-下架 |
| description | String | 否 | 商品描述，支持HTML |
| attributes | Object | 否 | 商品属性，键值对格式 |
| specifications | Array | 否 | 规格信息 |
specifications数组中每个规格对象结构：
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| spec_id | String | 是 | 规格ID |
| spec_name | String | 是 | 规格名称 |
| spec_values | Array | 是 | 规格值列表 |
响应参数
| 字段名 | 类型 | 描述 |
|---|---|---|
| success_count | Integer | 成功同步的商品数量 |
| fail_count | Integer | 同步失败的商品数量 |
| fail_details | Array | 失败详情 |
请求示例
{
"products": [
{
"sku_code": "SP123456",
"name": "有机草莓",
"image": "https://example.com/images/strawberry.jpg",
"images": [
"https://example.com/images/strawberry_1.jpg",
"https://example.com/images/strawberry_2.jpg"
],
"category_id": 15,
"price": 29.90,
"original_price": 39.90,
"stock": 100,
"unit": "盒",
"weight": 0.25,
"status": 1,
"description": "新鲜有机草莓，500g/盒
",
"attributes": {
"产地": "云南",
"保质期": "7天",
"储存方式": "冷藏"
},
"specifications": [
{
"spec_id": "size",
"spec_name": "规格",
"spec_values": ["小盒(250g)", "标准(500g)", "大盒(1kg)"]
},
{
"spec_id": "package",
"spec_name": "包装",
"spec_values": ["简装", "礼盒装"]
}
]
}
]
}响应示例
{
"code": 200,
"message": "success",
"data": {
"success_count": 1,
"fail_count": 0,
"fail_details": []
},
"timestamp": 1623123456789
}# 2. 单个商品创建/更新
POST
/merchant/product/sync
创建或更新单个商品信息。如果商品SKU已存在则更新，不存在则创建。
请求参数
同批量同步接口中的单个商品对象。
响应参数
| 字段名 | 类型 | 描述 |
|---|---|---|
| product_id | String | 平台商品ID |
| sku_code | String | 商品SKU编码 |
请求示例
{
"sku_code": "SP123456",
"name": "有机草莓",
"image": "https://example.com/images/strawberry.jpg",
"images": [
"https://example.com/images/strawberry_1.jpg",
"https://example.com/images/strawberry_2.jpg"
],
"category_id": 15,
"price": 29.90,
"original_price": 39.90,
"stock": 100,
"unit": "盒",
"weight": 0.25,
"status": 1,
"description": "新鲜有机草莓，500g/盒
",
"attributes": {
"产地": "云南",
"保质期": "7天",
"储存方式": "冷藏"
},
"specifications": [
{
"spec_id": "size",
"spec_name": "规格",
"spec_values": ["小盒(250g)", "标准(500g)", "大盒(1kg)"]
},
{
"spec_id": "package",
"spec_name": "包装",
"spec_values": ["简装", "礼盒装"]
}
]
}响应示例
{
"code": 200,
"message": "success",
"data": {
"product_id": "12345",
"sku_code": "SP123456"
},
"timestamp": 1623123456789
}# 3. 商品上下架
POST
/merchant/product/status
更新商品上下架状态。
请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| sku_code | String | 是 | 商品SKU编码 |
| status | Integer | 是 | 状态：1-上架，0-下架 |
响应参数
| 字段名 | 类型 | 描述 |
|---|---|---|
| sku_code | String | 商品SKU编码 |
| status | Integer | 更新后的状态 |
请求示例
{
"sku_code": "SP123456",
"status": 1
}响应示例
{
"code": 200,
"message": "success",
"data": {
"sku_code": "SP123456",
"status": 1
},
"timestamp": 1623123456789
}# 4. 商品删除
POST
/merchant/product/delete
从平台删除商品。
请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| sku_code | String | 是 | 商品SKU编码 |
响应参数
| 字段名 | 类型 | 描述 |
|---|---|---|
| sku_code | String | 已删除的商品SKU编码 |
请求示例
{
"sku_code": "SP123456"
}响应示例
{
"code": 200,
"message": "success",
"data": {
"sku_code": "SP123456"
},
"timestamp": 1623123456789
}# 5. 获取商品分类
GET
/merchant/product/categories
获取平台商品分类列表，用于商品创建时选择正确的分类。
请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| parent_id | Integer | 否 | 父分类ID，不传则获取一级分类 |
响应参数
返回分类列表数组，每个分类对象结构：
| 字段名 | 类型 | 描述 |
|---|---|---|
| category_id | Integer | 分类ID |
| name | String | 分类名称 |
| parent_id | Integer | 父分类ID |
| level | Integer | 分类层级 |
| sort | Integer | 排序值 |
| has_children | Boolean | 是否有子分类 |
响应示例
{
"code": 200,
"message": "success",
"data": [
{
"category_id": 10,
"name": "生鲜水果",
"parent_id": 0,
"level": 1,
"sort": 1,
"has_children": true
},
{
"category_id": 20,
"name": "蔬菜豆制品",
"parent_id": 0,
"level": 1,
"sort": 2,
"has_children": true
}
],
"timestamp": 1623123456789
}