摘要：聚美优品主打美妆、护肤类垂直电商，在做美妆竞品分析、ERP 商品同步、选品数据看板时，商品详情接口是核心数据源。本文梳理聚美优品商品详情 API 整体返回结构，重点拆解 SKU 规格、库存、售价、优惠活动相关字段，附带简化 JSON 返回样例，以及开发对接时的常见坑点，适合电商后端、数据采集、跨境铺货开发同学参考。
一、接口基础说明
聚美优品商品详情 API，主要用于根据商品 ID 查询单品完整信息，区别于搜索列表接口，详情接口会返回更全的规格、活动优惠、赠品、品牌、成分、图文详情等深度字段。 接口名称：jumei.item_get(Taobaoapi2014前往体验)
- 适用业务场景：美妆竞品价格监控、PIM 产品库同步、选品指标提取、比价系统、私域商城铺货
- 调用前提：开放平台应用入驻、授权、签名校验、频率配额控制
- 核心入参：
item_id（聚美商品 ID，必填），部分版本支持指定sku_id直接查询单个规格
二、整体返回结构概览
返回 JSON 大体分为顶层 5 大模块：
item_base：商品基础信息（标题、主图、分类、品牌、产地、保质期、美妆特殊属性）sku_list：SKU 规格数组（核心模块：规格名称、sku_id、原价、售价、库存、条形码）promotion_info：优惠活动模块（满减、券、限时价、套装价、赠品信息）desc_info：详情内容（图文详情、卖点标签、成分说明、使用须知，美妆类目重点）extra：扩展字段（销量、评价总数、物流发货规则、售后说明）
三、关键字段深度解读
1. item_base 基础信息
| 字段 | 说明 |
|---|---|
| item_id | 商品唯一 ID，接口主键 |
| title | 商品标题，美妆类常包含规格、版本、香型 |
| brand_name | 品牌名称，竞品分析高频字段 |
| category | 类目路径：一级 / 二级 / 三级类目（护肤 / 彩妆 / 香水等） |
| main_images | 主图数组，多图 |
| shelf_status | 上下架状态：1 上架，0 下架 |
| shelf_time | 上架时间 |
| expire_notice | 保质期提示，美妆类目特有字段 |
2. sku_list 规格字段（重点）
数组，一个商品多个 SKU（色号、容量、版本），是同步 ERP、库存监控核心：
| 字段 | 说明 |
|---|---|
| sku_id | 规格唯一编码，下单、库存查询凭证 |
| spec_name | 规格名称，如「50ml 清爽型」「自然色」 |
| market_price | 划线原价（专柜价 / 指导价） |
| sale_price | 基础售价，未叠加券后 |
| stock_num | 当前可售库存 |
| bar_code | 商品条码，用于外部库匹配 |
| weight | 重量，集运、跨境物流核算运费使用 |
3. promotion_info 优惠字段（重点）
美妆平台活动多，券、限时秒杀、套装、满减都在这里：
| 字段 | 说明 |
|---|---|
| promotion_type | 活动类型：coupon 优惠券 /flash_sale 限时秒杀 /bundle 套装 |
| discount_price | 活动价，参与活动后的单品价 |
| coupon_list | 可用优惠券数组：券面额、门槛、有效期 |
| gift_info | 赠品列表：赠品名称、赠品数量（美妆非常常见） |
| valid_start / valid_end | 活动起止时间，用于判断优惠是否生效 |
开发注意：券后价不能直接取单一字段，需要业务层根据优惠门槛、用户身份叠加计算，接口只返回优惠规则，不会直接给出最终券后实付价。
4. extra 扩展指标
- sale_count：累计销量（统计口径注意：部分接口是近 30 天销量，不是总销量）
- comment_count：评价总数，可联动评论接口做 NLP 舆情分析
- delivery_rule：发货仓、发货时效、是否支持包邮
四、简化 JSON 返回样例
{
"code": 200,
"msg": "success",
"data": {
"item_base": {
"item_id": "JM12345678",
"title": "保湿修护精华液30ml 补水滋润护肤",
"brand_name": "XX护肤",
"category": ["护肤", "精华", "保湿精华"],
"main_images": ["https://xxx.jpg"],
"shelf_status": 1,
"expire_notice": "保质期3年"
},
"sku_list": [
{
"sku_id": "SKU987001",
"spec_name": "30ml 标准版",
"market_price": 299,
"sale_price": 199,
"stock_num": 236,
"weight": 0.12
}
],
"promotion_info": {
"promotion_type": "coupon",
"discount_price": 179,
"coupon_list": [
{
"coupon_amount": 20,
"threshold": 199,
"start_time": "2026-10-01 00:00:00",
"end_time": "2026-11-30 23:59:59"
}
],
"gift_info": [{"gift_name": "小样5ml","gift_num":1}]
},
"desc_info": {
"selling_point": "深层补水、敏感肌可用",
"detail_html": "<p>产品详情图文...</p>"
},
"extra": {
"sale_count": 12580,
"comment_count": 3692,
"delivery_rule": "48小时内发货，满99包邮"
}
}
}
五、开发对接踩坑实录
- SKU 数组为空：部分套装商品主商品不返回 SKU，需要走套装子商品接口获取规格；
- 优惠叠加逻辑复杂：优惠券、限时活动互斥或者可叠加，平台规则经常变更，不要硬写死；
- 销量口径不一致：区分累计销量、近 30 天销量，做竞品对比时一定要统一口径；
- 美妆敏感字段：成分、保质期、质检相关字段，部分应用权限不足会不返回；
- 限流配额：高频拉取详情容易触发风控，生产环境建议做增量同步、缓存、异步队列。
六、延伸业务方案
拿到结构化数据之后，可以落地这些场景：
- 美妆竞品定时比价告警，价格变动推送；
- 同步到 ERP/PIM 系统，多渠道商品库统一管理；
- 搭配商品评论 API，构建美妆品类 NLP 语料，挖掘用户痛点做选品；
- 反向代购、集运系统的商品信息自动录入。
