商城

概念说明

SPU（Standard Product Unit）：标准产品单位，从产品视角描述产品特性。例如 iPhone 14 就是一个 SPU。
SKU（Stock Keeping Unit）：库存单位，从库存视角管理库存。例如 iPhone 14 白色 16G 就是一个 SKU。
一个商品（SPU）可以包含多个 SKU（不同颜色、内存等规格组合）。

获取商品分类列表

获取商品的一级或二级分类列表。

URL：/app-api/product/category/getParentCategoryList
Method：POST
需要登录：是
需要鉴权：是

请求参数

参数	类型	约束	说明
isParent	Boolean	-	`true`-只获取父分类（一级），`false`-获取父分类和子分类（二级）

使用说明

用户点击某一分类进入分类列表时，需展示二级分类。
用户点击分类上的「更多」时，需展示二级分类。

请求示例

{
    "isParent": true
}

响应示例

仅父分类：

{
    "code": 0,
    "data": [
        {
            "id": 15,
            "parentId": 0,
            "name": "童装童鞋",
            "picUrl": "https://example.com/image.jpg",
            "sort": 1,
            "status": 0,
            "subCategoryRespList": null
        }
    ],
    "msg": "成功"
}

父子分类：

{
    "code": 0,
    "data": [
        {
            "id": 15,
            "parentId": 0,
            "name": "童装童鞋",
            "picUrl": "https://example.com/image.jpg",
            "sort": 1,
            "status": 0,
            "subCategoryRespList": [
                {
                    "id": 16,
                    "parentId": 15,
                    "name": "童装",
                    "picUrl": "https://example.com/sub.jpg",
                    "sort": 1,
                    "status": 0,
                    "subCategoryRespList": null
                }
            ]
        }
    ],
    "msg": "成功"
}

响应说明

参数	类型	说明
id	Long	数据编号
parentId	Long	父分类编号
name	String	分类名称
picUrl	String	图片地址
status	Long	状态，`0`-开启，`1`-禁用
sort	Long	排序
subCategoryRespList	List	子分类列表，结构同外层

获取商品 SPU 分页

获取商品列表，支持分类、品牌、热门、新品等筛选条件。

URL：/app-api/product/spu/page
Method：POST
需要登录：是
需要鉴权：是

请求参数

参数	类型	约束	说明
pageNo	Number	必传	页码
pageSize	Number	必传	每页条数
categoryId	Number	-	分类编号
ids	Array	-	商品 SPU 编号数组
categoryIds	Array	-	分类编号数组
brandId	Long	-	品牌编号，`0` 返回所有品牌
isHot	Boolean	-	热门推荐，`true`-是，`false`-否
isNew	Boolean	-	新品推荐，`true`-是，`false`-否
keyword	String	-	关键字搜索商品名称
sortField	String	-	排序字段，`price`-价格，`salesCount`-销量，`createTime`-最新
sortAsc	Boolean	-	排序方式，`true`-升序，`false`-降序

请求示例

{
    "categoryId": 100,
    "pageNo": 1,
    "pageSize": 10
}

响应示例

{
    "code": 0,
    "data": {
        "list": [
            {
                "id": 634,
                "name": "HUAWEI Mate 60 Pro",
                "introduction": "卫星通话，超可靠玄武架构",
                "categoryId": 48,
                "picUrl": "https://example.com/product.jpg",
                "sliderPicUrls": [
                    "https://example.com/slide1.jpg",
                    "https://example.com/slide2.jpg"
                ],
                "specType": true,
                "price": 699900,
                "marketPrice": 699900,
                "stock": 977,
                "salesCount": 6,
                "isHot": null,
                "isNew": null,
                "branId": null
            }
        ],
        "total": 6
    },
    "msg": "成功"
}

响应说明

参数	类型	说明
id	Long	商品 SPU ID
name	String	商品 SPU 名称
introduction	String	商品简介
categoryId	Number	分类编号
picUrl	String	商品封面
sliderPicUrls	Array	商品轮播图
specType	Boolean	规格类型，`false`-单规格，`true`-多规格
price	Number	商品价格，单位：分
marketPrice	Number	市场价（划线价），单位：分
vipPrice	Number	VIP 价格，单位：分
stock	Number	库存
salesCount	Number	商品销量
isHot	Boolean	热门推荐，`null` 默认 `false`
isNew	Boolean	新品推荐，`null` 默认 `false`
branId	Number	品牌编号
total	Long	分页总数量

获取商品 SPU 明细

获取单个商品的详细信息，包含 SKU 列表。

URL：/app-api/product/spu/getSpuDetail
Method：POST
需要鉴权：是

请求参数

参数	类型	约束	说明
id	Long	必传	商品编号

请求示例

{
    "id": 640
}

响应示例

{
    "code": 0,
    "data": {
        "id": 639,
        "name": "商品名称",
        "introduction": "商品简介",
        "description": "<p>商品详情</p>",
        "categoryId": 19,
        "picUrl": "https://example.com/cover.jpg",
        "sliderPicUrls": ["https://example.com/slide.jpg"],
        "specType": false,
        "price": 100,
        "marketPrice": 200,
        "stock": 4,
        "skus": [
            {
                "id": 29,
                "properties": [
                    {
                        "propertyId": 0,
                        "propertyName": "默认",
                        "valueId": 0,
                        "valueName": "默认"
                    }
                ],
                "price": 100,
                "marketPrice": 200,
                "vipPrice": null,
                "picUrl": "",
                "stock": 4,
                "weight": 5,
                "volume": 6
            }
        ],
        "salesCount": 0,
        "isHot": true,
        "isNew": true,
        "descriptionOne": "平台官方直营",
        "descriptionTwo": "平台提供售后",
        "descriptionThree": "支持七天无理由退换货",
        "liveProductBaseInfo": {
            "id": 12,
            "liveId": 120,
            "spuId": 639,
            "status": 0,
            "sort": 1,
            "explainStatus": 1,
            "createTime": 1734082373000
        }
    },
    "msg": "成功"
}

响应说明

商品基本信息：

参数	类型	说明
id	Long	商品数据编号
name	String	商品名称
introduction	String	商品简介
description	String	商品详情信息
categoryId	Number	分类编号
picUrl	String	商品封面
sliderPicUrls	Array	商品轮播图
specType	Boolean	规格类型，`false`-单规格，`true`-多规格
price	Number	商品价格（SKU 单价最低值），单位：分
marketPrice	Number	市场价（划线价），单位：分
stock	Number	库存
salesCount	Number	商品销量
isHot	Boolean	热门推荐
isNew	Boolean	新品推荐
descriptionOne	String	商品保障说明一
descriptionTwo	String	商品保障说明二
descriptionThree	String	商品保障说明三

SKU 字段（skus）：

参数	类型	说明
id	Long	商品 SKU 编号
properties	Array	属性数组（propertyId/propertyName/valueId/valueName）
price	Number	销售价格，单位：分
marketPrice	Number	市场价格，单位：分
vipPrice	Number	VIP 价格，单位：分
picUrl	String	图片地址
stock	Number	库存
weight	Number	商品重量
volume	Number	商品体积

获取品牌分页

分页获取商品品牌列表。

URL：/app-api/product/brand/page
Method：POST
需要登录：是
需要鉴权：是

请求参数

参数	类型	约束	说明
pageNo	Number	必传	页码
pageSize	Number	必传	每页条数
name	String	-	品牌名称，模糊搜索

请求示例

{
    "name": "索尼",
    "pageNo": 1,
    "pageSize": 10
}

响应示例

{
    "code": 0,
    "data": {
        "list": [
            {
                "id": 3,
                "name": "索尼",
                "picUrl": "https://example.com/brand.png",
                "sort": 2,
                "description": "<p>品牌介绍</p>",
                "status": 0,
                "createTime": 1693463998000
            }
        ],
        "total": 1
    },
    "msg": "成功"
}

响应说明

参数	类型	说明
id	Long	品牌 ID
name	String	品牌名称
picUrl	String	品牌封面
sort	Integer	排序
description	String	品牌介绍
status	Integer	状态，`0`-启用
createTime	Long	创建时间
total	Long	分页总数量

获取品牌列表

获取品牌列表（不分页）。

URL：/app-api/product/brand/list
Method：POST
需要登录：是
需要鉴权：是

请求参数

参数	类型	约束	说明
name	String	-	品牌名称，模糊搜索

请求示例

{
    "name": "索尼"
}

响应示例

{
    "code": 0,
    "data": [
        {
            "id": 2,
            "name": "华为",
            "picUrl": "https://example.com/huawei.png",
            "sort": 0,
            "description": "遥遥领先",
            "status": 0,
            "createTime": 1693463160000
        },
        {
            "id": 3,
            "name": "索尼",
            "picUrl": "https://example.com/sony.png",
            "sort": 2,
            "description": "品牌介绍",
            "status": 0,
            "createTime": 1693463998000
        }
    ],
    "msg": "成功"
}

响应说明

响应字段同「获取品牌分页」。

说明

品牌分页及品牌列表接口均已返回品牌完整信息，单个品牌详情可直接从列表中获取。

获取直播间商品列表

获取直播间已挂载的商品列表。

后台接口：/admin-api/product/spu/getLiveSpuList
APP 接口：/app-api/product/spu/getLiveSpuList
Method：POST
需要登录：是
需要鉴权：是

请求参数

参数	类型	约束	说明
liveId	Number	必传	直播间编号
explainStatus	Number	-	当前讲解状态
status	Number	-	状态，`0`-获取上架状态的商品列表

请求示例

{
    "liveId": 120,
    "explainStatus": 1,
    "status": 0
}

响应示例

{
    "code": 0,
    "data": [
        {
            "id": 639,
            "name": "商品名称",
            "introduction": "商品简介",
            "categoryId": 19,
            "picUrl": "https://example.com/product.jpg",
            "sliderPicUrls": ["https://example.com/slide.jpg"],
            "specType": false,
            "price": 100,
            "marketPrice": 200,
            "stock": 4,
            "salesCount": 0,
            "isHot": true,
            "isNew": true,
            "branId": null,
            "liveProductBaseInfoRespApiVO": {
                "id": 12,
                "liveId": 120,
                "spuId": 639,
                "status": 0,
                "sort": 1,
                "explainStatus": 1,
                "createTime": 1734082373000
            }
        }
    ],
    "msg": "成功"
}

响应说明

商品字段同「获取商品 SPU 分页」。

挂载信息（liveProductBaseInfoRespApiVO）：

参数	类型	说明
id	Long	挂载编号
liveId	Long	直播间编号
spuId	Long	商品 SPU 编号
status	Long	上架状态，`1`-上架，`0`-下架
sort	Long	排序
explainStatus	Long	是否当前讲解，`0`-否，`1`-是
createTime	Long	创建时间
updateTime	Long	更新时间，可按此字段排序

获取直播间当前讲解商品明细

获取直播间当前正在讲解的商品 SPU 详细信息。

后台接口：/admin-api/product/spu/getLiveSpuDetail
APP 接口：/app-api/product/spu/getLiveSpuDetail
Method：POST
需要鉴权：是

请求参数

参数	类型	约束	说明
liveId	Number	必传	直播间编号
explainStatus	Number	必传	当前讲解状态，`0`-否，`1`-是
status	Number	-	上架状态，`0`-获取上架商品

请求示例

{
    "liveId": 120,
    "explainStatus": 1,
    "status": 0
}

响应示例

{
    "code": 0,
    "data": {
        "id": 639,
        "name": "商品名称",
        "introduction": "商品简介",
        "description": "<p>商品详情</p>",
        "categoryId": 19,
        "picUrl": "https://example.com/cover.jpg",
        "sliderPicUrls": ["https://example.com/slide.jpg"],
        "specType": false,
        "price": 100,
        "marketPrice": 200,
        "stock": 4,
        "skus": [
            {
                "id": 29,
                "properties": [
                    {
                        "propertyId": 0,
                        "propertyName": "默认",
                        "valueId": 0,
                        "valueName": "默认"
                    }
                ],
                "price": 100,
                "marketPrice": 200,
                "stock": 4,
                "weight": 5,
                "volume": 6
            }
        ],
        "salesCount": 0,
        "isHot": true,
        "isNew": true,
        "descriptionOne": "平台官方直营",
        "descriptionTwo": "平台提供售后",
        "descriptionThree": "支持七天无理由退换货",
        "liveProductBaseInfo": {
            "id": 12,
            "liveId": 120,
            "spuId": 639,
            "status": 0,
            "sort": 1,
            "explainStatus": 1,
            "createTime": 1734082373000
        }
    },
    "msg": "成功"
}

响应说明

响应字段同「获取商品 SPU 明细」，额外包含挂载信息（liveProductBaseInfo）。

错误码说明

错误码	说明
1008005000	商品 SPU ID 不能为空
1008005001	商品 SPU 不存在
1008005002	商品 SPU 不处于上架状态

以上三种状态码代表当前直播没有正在讲解的商品。

获取商品评价分页

URL：/app-api/product/comment/getCommentPage
Method：POST
需要鉴权：否

请求参数

参数	类型	约束	说明
spuId	Long	必传	商品 SPU 编号
goodComment	Boolean	可选	是否仅显示好评
pageNo	Long	可选	页码，默认 1
pageSize	Long	可选	每页条数，默认 10

请求示例

{ "spuId": 639, "pageNo": 1, "pageSize": 10 }

响应示例

{
    "code": 0,
    "data": {
        "list": [
            {
                "userId": 1024,
                "userNickname": "用户A",
                "userAvatar": "http://...",
                "id": 100,
                "anonymous": false,
                "orderId": 200,
                "orderItemId": 300,
                "replyStatus": true,
                "replyContent": "感谢您的好评！",
                "replyTime": 1734082373000,
                "createTime": 1734082000000,
                "spuId": 639,
                "spuName": "商品名称",
                "skuId": 700,
                "scores": 5,
                "descriptionScores": 5,
                "benefitScores": 5,
                "content": "非常好用，推荐购买！",
                "picUrls": ["http://..."],
                "skuPicUrl": "http://..."
            }
        ],
        "total": 1
    },
    "msg": "成功"
}

响应说明

参数	类型	说明
userId	Long	评价用户编号
userNickname	String	评价用户昵称
userAvatar	String	评价用户头像
id	Long	评价编号
anonymous	Boolean	是否匿名
orderId	Long	订单编号
orderItemId	Long	订单项编号
replyStatus	Boolean	商家是否回复
replyContent	String	商家回复内容
replyTime	Long	商家回复时间
createTime	Long	评价时间
spuId	Long	商品 SPU 编号
spuName	String	商品名称
skuId	Long	商品 SKU 编号
scores	Long	综合评分
descriptionScores	Long	描述评分
benefitScores	Long	性价比评分
content	String	评价内容
picUrls	String[]	评价图片列表
skuPicUrl	String	SKU 图片地址

爆款活动分页

URL：/app-api/promotion/discount-activity/getDiscountActivityPage
Method：POST
需要鉴权：否

请求参数

参数	类型	约束	说明
pageNo	Long	可选	页码，默认 1
pageSize	Long	可选	每页条数，默认 10

请求示例

{ "pageNo": 1, "pageSize": 10 }

响应示例

{
    "code": 0,
    "data": {
        "products": [
            {
                "spuId": 639,
                "spuName": "商品名称",
                "picUrl": "http://...",
                "skuId": 700,
                "discountType": 2,
                "discountPercent": 80,
                "discountPrice": 0,
                "price": 10000,
                "salePrice": 8000
            }
        ],
        "remark": "活动说明"
    },
    "msg": "成功"
}

响应说明

参数	类型	说明
products	Array	活动商品列表
spuId	Long	商品 SPU 编号
spuName	String	商品名称
picUrl	String	商品封面图
skuId	Long	商品 SKU 编号
discountType	Long	优惠类型，`2`-折扣，`4`-满减
discountPercent	Long	折扣百分比（80 表示 8 折）
discountPrice	Long	优惠金额，单位：分
price	Long	原价，单位：分
salePrice	Long	折后价，单位：分
remark	String	活动说明

爆款活动详情

URL：/app-api/promotion/discount-activity/getDiscountActivity
Method：GET
需要鉴权：否

请求参数

无请求参数。

请求示例

GET /app-api/promotion/discount-activity/getDiscountActivity

响应示例

{
    "code": 0,
    "data": {
        "products": [
            {
                "spuId": 639,
                "spuName": "商品名称",
                "picUrl": "http://...",
                "skuId": 700,
                "discountType": 2,
                "discountPercent": 80,
                "discountPrice": 0,
                "price": 10000,
                "salePrice": 8000
            }
        ],
        "remark": "活动说明",
        "imgUrl": "http://..."
    },
    "msg": "成功"
}

响应说明

参数	类型	说明
products	Array	活动商品列表，字段同「爆款活动分页」
remark	String	活动说明
imgUrl	String	活动海报地址

获取商品分类列表​

请求参数​

请求示例​

响应示例​

响应说明​

获取商品 SPU 分页​

请求参数​

请求示例​

响应示例​

响应说明​

获取商品 SPU 明细​

请求参数​

请求示例​

响应示例​

响应说明​

获取品牌分页​

请求参数​

请求示例​

响应示例​

响应说明​

获取品牌列表​

请求参数​

请求示例​

响应示例​

响应说明​

获取直播间商品列表​

请求参数​

请求示例​

响应示例​

响应说明​

获取直播间当前讲解商品明细​

请求参数​

请求示例​

响应示例​

响应说明​

获取商品评价分页​

请求参数​

请求示例​

响应示例​

响应说明​

爆款活动分页​

请求参数​

请求示例​

响应示例​

响应说明​

爆款活动详情​

请求参数​

请求示例​

响应示例​

响应说明​

获取商品分类列表

请求参数

请求示例

响应示例

响应说明

获取商品 SPU 分页

请求参数

请求示例

响应示例

响应说明

获取商品 SPU 明细

请求参数

请求示例

响应示例

响应说明

获取品牌分页

请求参数

请求示例

响应示例

响应说明

获取品牌列表

请求参数

请求示例

响应示例

响应说明

获取直播间商品列表

请求参数

请求示例

响应示例

响应说明

获取直播间当前讲解商品明细

请求参数

请求示例

响应示例

响应说明

获取商品评价分页

请求参数

请求示例

响应示例

响应说明

爆款活动分页

请求参数

请求示例

响应示例

响应说明

爆款活动详情

请求参数

请求示例

响应示例

响应说明