1688商品详情API返回的JSON数据结构复杂且信息丰富，通常包含以下核心字段和层级：

一、顶层结构

json{  "request_id": "唯一请求标识符",  "code": 200, // 状态码，200表示成功  "message": "success", // 状态描述  "data": { // 实际商品数据    "product": { ... } // 商品详情核心对象  }}

• request_id：用于追踪和调试请求的唯一标识。

• code/message：请求状态，200表示成功，其他值需参考错误码文档。

• data：包含商品详情的主体对象。

二、商品核心信息（product对象）

json"product": {  "product_id": "610947572360", // 商品唯一标识  "title": "2024新款夏季女装连衣裙", // 商品标题  "price": "45.00", // 当前售价  "original_price": "60.00", // 原价（如有）  "stock": "1000", // 库存数量  "main_image_url": "https://img.1688.com/1.jpg", // 商品主图  "description": "<div>商品详细描述...</div>", // HTML格式描述  "category": { // 商品分类    "id": "123456",    "name": "连衣裙"  },  "brand": "某品牌", // 品牌名称  "status": "onShelf", // 商品状态（上架/下架）  "create_time": "2023-01-01 10:00:00", // 创建时间  "update_time": "2025-11-03 15:30:00" // 更新时间}

三、关键扩展字段

1. 价格与库存

• priceRange：价格区间（多SKU时适用）

  json"priceRange": {  "minPrice": "45.00",  "maxPrice": "55.00",  "currency": "CNY"}

• skuList：SKU列表（含规格、价格、库存）

  json"skuList": [  {    "skuId": "1001",    "specs": "S码", // 规格描述    "price": "45.00",    "inventory": 300,    "attributes": { "颜色": "白色" } // 规格属性  }]

2. 图片与视频

• images：商品图片列表（主图+详情图）

  json"images": [  {"url": "https://img.1688.com/1.jpg", "position": 1},  {"url": "https://img.1688.com/2.jpg", "position": 2}]

• video：商品视频链接（如有）

3. 卖家与物流信息

• sellerInfo：卖家信息

  json"sellerInfo": {  "shopId": "shop123",  "shopName": "杭州XX服饰有限公司",  "contact": {"phone": "138****1234"}}

• freightInfo：运费信息

  json"freightInfo": {  "freightTemplateId": "template123",  "isFree": false, // 是否包邮  "freightCalculType": "template" // 运费计算方式}

4. 商品属性与促销

• attributes：商品属性列表

  json"attributes": [  {"name": "材质", "value": "棉质"},  {"name": "产地", "value": "中国"}]

• promotionInfo：促销信息

  json"promotionInfo": {  "type": "discount", // 促销类型（满减/折扣等）  "description": "满100减20"}

四、数据清洗与处理建议

1. 字段提取：

• 使用点号表示法提取深层字段（如data.product.skuList[0].price）。

• 对数组类型字段（如images）按索引或属性排序。

2. 类型转换：

• 价格字段：字符串转浮点数（如float(data["price"].replace("¥", ""))）。

• 库存字段：字符串转整数（如int(data["stock"])）。

3. 缺失值处理：

• 文本字段缺失时填充"未知"。

• 数值字段缺失时填充0或中位数。

4. 多语言与编码：

• 确保解析时指定encoding='utf-8'，避免中文乱码。

五、示例代码（Python）

pythonimport json# 模拟API返回的JSON数据response_data = {  "code": 200,  "message": "success",  "data": {    "product": {      "product_id": "610947572360",      "title": "2024新款夏季女装连衣裙",      "price": "45.00",      "stock": "1000",      "skuList": [        {"skuId": "1001", "specs": "S码", "price": "45.00", "inventory": 300}      ]    }  }}# 提取并清洗数据def clean_product_data(data):    product = data["data"]["product"]    cleaned = {        "product_id": product["product_id"],        "title": product["title"],        "price": float(product["price"]),        "stock": int(product["stock"]),        "skus": []    }    for sku in product.get("skuList", []):        cleaned["skus"].append({            "sku_id": sku["skuId"],            "specs": sku["specs"],            "price": float(sku["price"]),            "stock": int(sku["inventory"])        })    return cleaned# 输出结果cleaned_product = clean_product_data(response_data)print(json.dumps(cleaned_product, indent=2, ensure_ascii=False))

六、注意事项

1. API版本：不同版本的API可能返回不同字段，需参考最新文档。

2. 调用频率：1688 API有调用限制，需合理控制频率或使用缓存。

3. 错误处理：检查code和message字段，处理异常情况（如商品不存在、权限不足）。

4. 数据更新：重要数据（如价格、库存）需定期同步，避免使用过期数据。