摘要：聚美优品主打美妆、护肤类垂直电商，在做美妆竞品分析、ERP 商品同步、选品数据看板时，商品详情接口是核心数据源。本文梳理聚美优品商品详情 API 整体返回结构，重点拆解 SKU 规格、库存、售价、优惠活动相关字段，附带简化 JSON 返回样例，以及开发对接时的常见坑点，适合电商后端、数据采集、跨境铺货开发同学参考。
一、接口基础说明
聚美优品商品详情 API，主要用于根据商品 ID 查询单品完整信息，区别于搜索列表接口，详情接口会返回更全的规格、活动优惠、赠品、品牌、成分、图文详情等深度字段。
- 适用业务场景：美妆竞品价格监控、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：发货仓、发货时效、是否支持包邮。
