首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >一文读懂聚美优品商品详情 API:返回结构、SKU 与优惠字段解读(附 JSON 样例)

一文读懂聚美优品商品详情 API:返回结构、SKU 与优惠字段解读(附 JSON 样例)

原创
作者头像
用户1597063760
发布于 2026-11-03 11:44:43
发布于 2026-11-03 11:44:43
840
举报
文章被收录于专栏:经验经验

摘要:聚美优品主打美妆、护肤类垂直电商,在做美妆竞品分析、ERP 商品同步、选品数据看板时,商品详情接口是核心数据源。本文梳理聚美优品商品详情 API 整体返回结构,重点拆解 SKU 规格、库存、售价、优惠活动相关字段,附带简化 JSON 返回样例,以及开发对接时的常见坑点,适合电商后端、数据采集、跨境铺货开发同学参考。

一、接口基础说明

聚美优品商品详情 API,主要用于根据商品 ID 查询单品完整信息,区别于搜索列表接口,详情接口会返回更全的规格、活动优惠、赠品、品牌、成分、图文详情等深度字段。

  • 适用业务场景:美妆竞品价格监控、PIM 产品库同步、选品指标提取、比价系统、私域商城铺货
  • 调用前提:开放平台应用入驻、授权、签名校验、频率配额控制
  • 核心入参:item_id(聚美商品 ID,必填),部分版本支持指定sku_id直接查询单个规格

二、整体返回结构概览

返回 JSON 大体分为顶层 5 大模块:

  1. item_base:商品基础信息(标题、主图、分类、品牌、产地、保质期、美妆特殊属性)
  2. sku_list:SKU 规格数组(核心模块:规格名称、sku_id、原价、售价、库存、条形码)
  3. promotion_info:优惠活动模块(满减、券、限时价、套装价、赠品信息)
  4. desc_info:详情内容(图文详情、卖点标签、成分说明、使用须知,美妆类目重点)
  5. extra:扩展字段(销量、评价总数、物流发货规则、售后说明)

三、关键字段深度解读

1. item_base 基础信息

字段

说明

api_name

jumei.item_get(Taobaoapi2014)

adress

c0b.cc/R4rbK2

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 返回样例

代码语言:javascript
复制
{
    "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包邮"
        }
    }
}

五、开发对接踩坑实录

  1. SKU 数组为空:部分套装商品主商品不返回 SKU,需要走套装子商品接口获取规格;
  2. 优惠叠加逻辑复杂:优惠券、限时活动互斥或者可叠加,平台规则经常变更,不要硬写死;
  3. 销量口径不一致:区分累计销量、近 30 天销量,做竞品对比时一定要统一口径;
  4. 美妆敏感字段:成分、保质期、质检相关字段,部分应用权限不足会不返回;
  5. 限流配额:高频拉取详情容易触发风控,生产环境建议做增量同步、缓存、异步队列。

六、延伸业务方案

拿到结构化数据之后,可以落地这些场景:

  • 美妆竞品定时比价告警,价格变动推送;
  • 同步到 ERP/PIM 系统,多渠道商品库统一管理;
  • 搭配商品评论 API,构建美妆品类 NLP 语料,挖掘用户痛点做选品;
  • 反向代购、集运系统的商品信息自动录入。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、接口基础说明
  • 二、整体返回结构概览
  • 三、关键字段深度解读
    • 1. item_base 基础信息
    • 2. sku_list 规格字段(重点)
    • 3. promotion_info 优惠字段(重点)
    • 4. extra 扩展指标
  • 四、简化 JSON 返回样例
  • 五、开发对接踩坑实录
  • 六、延伸业务方案
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档