分析中 已回复 待规划 {{opt.name}}

分析中 已回复 待规划

电商平台api：1688 阿里巴巴平台商品详情全解析

1688（阿里巴巴中国站）作为国内最大的 B2B 批发平台，其商品详情数据涵盖了从基础信息到供应链属性的完整维度。本文将深入解析 1688 商品详情的全量数据字段，并对比主流电商平台的 API 接口体系，帮助开发者全面掌握 B2B 电商数据采集技术。

一、1688 商品详情数据结构全景图

1688 商品详情不同于淘宝/天猫的 C2C/B2C 模式，其核心特征是批发属性——起订量、阶梯价、代发支持、工厂信息等字段是 1688 独有的数据维度。

┌─────────────────────────────────────────────────────────────┐
│                    1688 商品详情数据结构                       │
├─────────────────────────────────────────────────────────────┤
│  1. 基础信息层                                               │
│     ├── 商品ID (num_iid / productId)                         │
│     ├── 标题 (subject / title)                               │
│     ├── 副标题 / 营销文案                                     │
│     ├── 主图列表 (imageUrls / item_imgs)                     │
│     ├── 商品视频 (video_url)                                  │
│     └── 商品状态 (status: 上架/下架/删除)                      │
├─────────────────────────────────────────────────────────────┤
│  2. 价格体系层（1688 核心）                                   │
│     ├── 参考价 / 划线价 (reference_price)                     │
│     ├── 售价 (price)                                          │
│     ├── 阶梯批发价 (priceRanges)                              │
│     │   └── [{startQuantity: 1, price: 10.0}, ...]           │
│     ├── 代发价 (agent_price / dropship_price)                 │
│     ├── 最小起订量 (moq / minOrderQuantity)                   │
│     └── 计量单位 (unit: 件/套/箱)                             │
├─────────────────────────────────────────────────────────────┤
│  3. SKU 规格层                                               │
│     ├── 规格属性 (specs: 颜色/尺码/材质...)                    │
│     ├── SKU 映射表 (skuMap)                                   │
│     │   └── "红色;M": {skuId, price, stock, specId}          │
│     └── SKU 图片 (sku_images)                                 │
├─────────────────────────────────────────────────────────────┤
│  4. 库存物流层                                               │
│     ├── 总库存 (stock / quantity)                             │
│     ├── 可售数量 (amountOnSale)                               │
│     ├── 发货地 (location / sendGoodsAddress)                  │
│     ├── 运费模板 (freightTemplateID)                          │
│     ├── 重量体积 (weight / volume / packageSize)              │
│     └── 发货时效 (deliveryTime)                               │
├─────────────────────────────────────────────────────────────┤
│  5. 供应商信息层（1688 特色）                                 │
│     ├── 供应商名称 (supplier / sellerNick)                    │
│     ├── 供应商ID (seller_id)                                  │
│     ├── 诚信通等级 (creditLevel / supplier_level)             │
│     ├── 实力商家/超级工厂标识                                  │
│     ├── 经营模式 (manufacturer / trader)                      │
│     ├── 工厂信息 (factoryInfo)                                │
│     └── 近 90 天成交额 / 回头率                                │
├─────────────────────────────────────────────────────────────┤
│  6. 交易服务层                                               │
│     ├── 是否支持混批 (isSupportMix)                           │
│     ├── 是否支持一件代发 (isSupportAgent / dropship)          │
│     ├── 支付方式 (creditPayment / assurance)                  │
│     ├── 服务保障 (7天包退 / 材质保障...)                       │
│     └── 跨境专供标识 (crossBorder)                            │
├─────────────────────────────────────────────────────────────┤
│  7. 商品属性层                                               │
│     ├── 类目属性 (categoryProps)                              │
│     ├── 自定义属性 (attributes)                               │
│     ├── 商品描述 (description / detail)                       │
│     └── 商品参数 (paramList)                                  │
├─────────────────────────────────────────────────────────────┤
│  8. 营销数据层                                               │
│     ├── 30 天销量 (saleCount / sales)                         │
│     ├── 总销量 (totalSales)                                   │
│     ├── 评价数 (evaluateCount)                                │
│     ├── 好评率 (goodRate)                                     │
│     └── 收藏数 (favCount)                                     │
└─────────────────────────────────────────────────────────────┘

二、官方 API 接口详解：alibaba.product.get

2.1 接口基本信息

2.2 请求参数

2.3 核心返回字段全解析

{
  "result": {
    "productId": 619899292404,
    "subject": "2026新款蓝牙耳机无线降噪运动入耳式超长续航",
    "description": "<html>...</html>",
    "imageUrl": "https://cbu01.alicdn.com/img/ibank/xxx.jpg",
    "detailPage": "https://detail.1688.com/offer/619899292404.html",
    "status": "published",
    
    "priceRanges": [
      {"startQuantity": 1, "price": 35.00},
      {"startQuantity": 50, "price": 32.00},
      {"startQuantity": 200, "price": 28.50},
      {"startQuantity": 500, "price": 25.00}
    ],
    
    "saleInfo": {
      "minOrderQuantity": 2,
      "unit": "件",
      "amountOnSale": 5000,
      "priceRanges": [...]
    },
    
    "skuInfo": {
      "skuMap": {
        "黑色;标准版": {
          "skuId": "4862151234567",
          "price": 35.00,
          "stock": 1200
        },
        "白色;顶配版": {
          "skuId": "4862151234568",
          "price": 55.00,
          "stock": 800
        }
      },
      "specs": [
        {
          "specId": "1627207",
          "name": "颜色",
          "values": [
            {"valueId": "28320", "name": "黑色"},
            {"valueId": "28321", "name": "白色"}
          ]
        },
        {
          "specId": "20509",
          "name": "版本",
          "values": [
            {"valueId": "28324", "name": "标准版"},
            {"valueId": "28325", "name": "顶配版"}
          ]
        }
      ]
    },
    
    "shippingInfo": {
      "freightTemplateID": 11754104,
      "unitWeight": 0.15,
      "packageSize": "10x8x5",
      "volume": 400,
      "sendGoodsAddress": {
        "province": "广东",
        "city": "深圳"
      }
    },
    
    "supplier": {
      "supplierId": "b2b-1234567890",
      "companyName": "深圳市xxx电子有限公司",
      "creditLevel": "AAAAA",
      "isFactory": true,
      "mainProducts": ["蓝牙耳机", "音箱"]
    }
  }
}

三、Python 完整实战：商品详情全字段采集

# -*- coding: utf-8 -*-
"""
1688 商品详情全字段采集器
支持官方 API 和第三方聚合 API
"""

import requests
import hashlib
import time
import json
import urllib.parse
from typing import Dict, List, Optional
from dataclasses import dataclass, asdict
from datetime import datetime


@dataclass
class PriceRange:
    """阶梯价格"""
    start_quantity: int
    price: float


@dataclass
class SkuItem:
    """SKU 规格"""
    sku_id: str
    properties: str           # 如"黑色;标准版"
    price: float
    stock: int


@dataclass
class ProductSpec:
    """商品规格定义"""
    spec_id: str
    name: str                 # 如"颜色"、"尺码"
    values: List[Dict]        # [{valueId, name}, ...]


@dataclass
class ShippingInfo:
    """物流信息"""
    freight_template_id: int
    unit_weight: float        # 单位重量(kg)
    package_size: str         # 包装尺寸(cm)
    volume: int               # 体积(cm³)
    province: str
    city: str


@dataclass
class SupplierInfo:
    """供应商信息"""
    supplier_id: str
    company_name: str
    credit_level: str
    is_factory: bool
    main_products: List[str]


@dataclass
class ProductDetail:
    """1688 商品详情完整结构"""
    # 基础信息
    product_id: str
    title: str
    description: str
    main_image: str
    images: List[str]
    detail_url: str
    status: str
    
    # 价格体系
    reference_price: float
    price_ranges: List[PriceRange]
    min_order_quantity: int
    unit: str
    
    # SKU 信息
    skus: List[SkuItem]
    specs: List[ProductSpec]
    
    # 库存物流
    total_stock: int
    amount_on_sale: int
    shipping: ShippingInfo
    
    # 供应商
    supplier: SupplierInfo
    
    # 交易服务
    support_mix: bool
    support_agent: bool          # 一件代发
    support_credit: bool         # 账期支付
    
    # 营销数据
    sales_30d: int
    total_sales: int
    evaluate_count: int
    good_rate: float
    
    # 时间戳
    create_time: str
    update_time: str


class Alibaba1688DetailAPI:
    """
    1688 商品详情 API 客户端
    """
    
    OFFICIAL_URL = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get"
    
    def __init__(self, app_key: str, app_secret: str, access_token: str):
        self.app_key = app_key
        self.app_secret = app_secret
        self.access_token = access_token
        self.session = requests.Session()
        
    def _generate_sign(self, params: dict) -> str:
        """
        生成 MD5 签名
        规则：app_secret + 排序后参数拼接 + app_secret，整体 MD5 大写
        """
        sorted_params = sorted(
            [(k, v) for k, v in params.items() if v is not None and k != 'sign'],
            key=lambda x: x[0]
        )
        param_str = ''.join([f"{k}{urllib.parse.quote_plus(str(v))}" for k, v in sorted_params])
        sign_str = f"{self.app_secret}{param_str}{self.app_secret}"
        return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
    
    def get_product_detail(
        self,
        product_id: str,
        fields: Optional[str] = None
    ) -> Optional[ProductDetail]:
        """
        获取商品详情（全字段）
        
        Args:
            product_id: 1688 商品数字 ID
            fields: 指定返回字段，None 则返回全部
        
        Returns:
            ProductDetail 对象
        """
        # 默认请求全量字段
        if fields is None:
            fields = (
                "productId,subject,description,imageUrl,detailPage,status,"
                "priceRanges,saleInfo,skuInfo,shippingInfo,"
                "supplier,creditInfo,tradeServiceInfo,"
                "createTime,lastUpdateTime"
            )
        
        params = {
            "app_key": self.app_key,
            "method": "com.alibaba.product.alibaba.product.get",
            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
            "v": "2.0",
            "format": "json",
            "access_token": self.access_token,
            "productId": product_id,
            "fields": fields
        }
        
        params["sign"] = self._generate_sign(params)
        
        try:
            response = self.session.post(
                self.OFFICIAL_URL,
                data=params,
                timeout=30
            )
            response.raise_for_status()
            data = response.json()
            
            if data.get("success"):
                return self._parse_product(data.get("result", {}))
            else:
                print(f"API 错误: {data.get('errorMessage', '未知错误')}")
                return None
                
        except requests.exceptions.RequestException as e:
            print(f"请求异常: {e}")
            return None
    
    def _parse_product(self, data: dict) -> ProductDetail:
        """解析 API 响应为结构化对象"""
        
        # 解析价格区间
        price_ranges = []
        for pr in data.get("priceRanges", []):
            price_ranges.append(PriceRange(
                start_quantity=pr.get("startQuantity", 1),
                price=float(pr.get("price", 0))
            ))
        
        # 解析 SKU
        skus = []
        sku_info = data.get("skuInfo", {})
        sku_map = sku_info.get("skuMap", {})
        for props, sku_data in sku_map.items():
            skus.append(SkuItem(
                sku_id=str(sku_data.get("skuId", "")),
                properties=props,
                price=float(sku_data.get("price", 0)),
                stock=int(sku_data.get("stock", 0))
            ))
        
        # 解析规格定义
        specs = []
        for spec in sku_info.get("specs", []):
            specs.append(ProductSpec(
                spec_id=str(spec.get("specId", "")),
                name=spec.get("name", ""),
                values=spec.get("values", [])
            ))
        
        # 解析物流信息
        shipping = data.get("shippingInfo", {})
        address = shipping.get("sendGoodsAddress", {})
        shipping_info = ShippingInfo(
            freight_template_id=shipping.get("freightTemplateID", 0),
            unit_weight=float(shipping.get("unitWeight", 0) or 0),
            package_size=shipping.get("packageSize", ""),
            volume=int(shipping.get("volume", 0) or 0),
            province=address.get("province", ""),
            city=address.get("city", "")
        )
        
        # 解析供应商
        supplier = data.get("supplier", {})
        supplier_info = SupplierInfo(
            supplier_id=supplier.get("supplierId", ""),
            company_name=supplier.get("companyName", ""),
            credit_level=supplier.get("creditLevel", ""),
            is_factory=supplier.get("isFactory", False),
            main_products=supplier.get("mainProducts", [])
        )
        
        # 交易服务
        trade_service = data.get("tradeServiceInfo", {})
        
        return ProductDetail(
            product_id=str(data.get("productId", "")),
            title=data.get("subject", ""),
            description=data.get("description", ""),
            main_image=data.get("imageUrl", ""),
            images=data.get("imageUrls", [data.get("imageUrl", "")]),
            detail_url=data.get("detailPage", ""),
            status=data.get("status", ""),
            
            reference_price=float(data.get("referencePrice", 0) or 0),
            price_ranges=price_ranges,
            min_order_quantity=data.get("saleInfo", {}).get("minOrderQuantity", 1),
            unit=data.get("saleInfo", {}).get("unit", "件"),
            
            skus=skus,
            specs=specs,
            
            total_stock=int(data.get("stock", 0) or 0),
            amount_on_sale=int(data.get("saleInfo", {}).get("amountOnSale", 0) or 0),
            shipping=shipping_info,
            
            supplier=supplier_info,
            
            support_mix=trade_service.get("supportMix", False),
            support_agent=trade_service.get("supportAgent", False),
            support_credit=trade_service.get("supportCredit", False),
            
            sales_30d=int(data.get("saleCount", 0) or 0),
            total_sales=int(data.get("totalSales", 0) or 0),
            evaluate_count=int(data.get("evaluateCount", 0) or 0),
            good_rate=float(data.get("goodRate", 0) or 0),
            
            create_time=data.get("createTime", ""),
            update_time=data.get("lastUpdateTime", "")
        )
    
    def export_to_json(self, product: ProductDetail, filename: str = None):
        """导出商品详情为 JSON 文件"""
        if filename is None:
            filename = f"product_{product.product_id}_{datetime.now().strftime('%Y%m%d')}.json"
        
        with open(filename, 'w', encoding='utf-8') as f:
            json.dump(asdict(product), f, ensure_ascii=False, indent=2)
        
        print(f"已导出: {filename}")
        return filename


# ==================== 使用示例 ====================

if __name__ == "__main__":
    api = Alibaba1688DetailAPI(
        app_key="your_app_key",
        app_secret="your_app_secret",
        access_token="your_access_token"
    )
    
    # 获取商品详情
    product_id = "619899292404"
    detail = api.get_product_detail(product_id)
    
    if detail:
        print("=" * 60)
        print(f"商品详情: {detail.title}")
        print("=" * 60)
        
        # 基础信息
        print(f"\n【基础信息】")
        print(f"商品ID: {detail.product_id}")
        print(f"状态: {detail.status}")
        print(f"链接: {detail.detail_url}")
        
        # 价格体系
        print(f"\n【价格体系】")
        print(f"起订量: {detail.min_order_quantity} {detail.unit}")
        print("阶梯批发价:")
        for pr in detail.price_ranges:
            print(f"  ≥{pr.start_quantity} {detail.unit}: ¥{pr.price}")
        
        # SKU 信息
        print(f"\n【SKU 规格】")
        for spec in detail.specs:
            values = [v["name"] for v in spec.values]
            print(f"  {spec.name}: {', '.join(values)}")
        
        print(f"\nSKU 明细:")
        for sku in detail.skus:
            print(f"  {sku.properties} → ¥{sku.price} (库存:{sku.stock})")
        
        # 物流信息
        print(f"\n【物流信息】")
        print(f"发货地: {detail.shipping.province} {detail.shipping.city}")
        print(f"重量: {detail.shipping.unit_weight} kg")
        print(f"尺寸: {detail.shipping.package_size} cm")
        print(f"体积: {detail.shipping.volume} cm³")
        
        # 供应商
        print(f"\n【供应商信息】")
        print(f"公司: {detail.supplier.company_name}")
        print(f"诚信通: {detail.supplier.credit_level}")
        print(f"工厂店: {'是' if detail.supplier.is_factory else '否'}")
        print(f"主营: {', '.join(detail.supplier.main_products)}")
        
        # 交易服务
        print(f"\n【交易服务】")
        print(f"支持混批: {'是' if detail.support_mix else '否'}")
        print(f"支持代发: {'是' if detail.support_agent else '否'}")
        print(f"支持账期: {'是' if detail.support_credit else '否'}")
        
        # 营销数据
        print(f"\n【营销数据】")
        print(f"30天销量: {detail.sales_30d}")
        print(f"总销量: {detail.total_sales}")
        print(f"评价数: {detail.evaluate_count}")
        print(f"好评率: {detail.good_rate}%")
        
        # 导出 JSON
        api.export_to_json(detail)
        

四、主流电商平台 API 接口对比

4.1 平台接口体系概览

4.2 商品详情字段对比

# 各平台商品详情字段映射对比
PLATFORM_FIELD_MAP = {
    "1688": {
        "商品ID": "productId / num_iid",
        "标题": "subject",
        "售价": "priceRanges[0].price",
        "批发阶梯价": "priceRanges",
        "起订量": "saleInfo.minOrderQuantity",
        "代发价": "tradeServiceInfo.agentPrice",
        "供应商": "supplier.companyName",
        "诚信通等级": "supplier.creditLevel",
        "工厂标识": "supplier.isFactory",
        "发货地": "shippingInfo.sendGoodsAddress",
        "重量": "shippingInfo.unitWeight",
        "SKU价格": "skuInfo.skuMap.*.price",
        "30天销量": "saleCount",
        "支持混批": "tradeServiceInfo.supportMix",
        "支持代发": "tradeServiceInfo.supportAgent",
    },
    
    "taobao": {
        "商品ID": "num_iid",
        "标题": "title",
        "售价": "price",
        "原价": "original_price",
        "优惠券": "coupon_info",
        "店铺名": "nick",
        "店铺等级": "seller_credit_level",
        "发货地": "location",
        "邮费": "post_fee",
        "SKU价格": "skus.*.price",
        "月销量": "sold_quantity",
        "库存": "num",
        "天猫标识": "user_type",
    },
    
    "jd": {
        "商品ID": "skuId",
        "标题": "name",
        "京东价": "jdPrice",
        "PLUS价": "plusPrice",
        "自营标识": "isSelf",
        "店铺名": "shopName",
        "好评率": "goodRate",
        "评论数": "commentCount",
        "配送": "deliveryInfo",
        "产地": "productArea",
    },
    
    "pdd": {
        "商品ID": "goods_id",
        "标题": "goods_name",
        "拼单价": "min_group_price",
        "单买价": "min_normal_price",
        "百亿补贴": "is_billion_subsidy",
        "店铺名": "mall_name",
        "销量": "sales_tip",
        "成团人数": "group_required",
    }
}

4.3 各平台 API 接入差异

五、第三方聚合 API 方案

由于官方 API 存在权限限制和字段分散的问题，实际开发中常使用第三方聚合 API 获取更完整的商品详情数据。

5.1 第三方 API 优势

表格

5.2 第三方 API 调用示例

Python复制

import requests

class ThirdParty1688API:
    """
    第三方 1688 聚合 API 客户端
    示例：使用 AliPrice / VV-Tool 等服务
    """
    
    def __init__(self, api_key: str, base_url: str = "https://api.example.com"):
        self.api_key = api_key
        self.base_url = base_url
        
    def get_item_detail(self, num_iid: str) -> dict:
        """
        获取商品详情（含完整包装信息）
        """
        url = f"{self.base_url}/1688/item_get"
        params = {
            "key": self.api_key,
            "num_iid": num_iid,
            "lang": "zh-CN"
        }
        
        response = requests.get(url, params=params, timeout=30)
        data = response.json()
        
        if data.get("code") == 200:
            item = data.get("item", {})
            return {
                "product_id": item.get("num_iid"),
                "title": item.get("title"),
                "price": item.get("price"),
                "original_price": item.get("original_price"),
                "promotion_price": item.get("promotion_price"),
                
                # 包装信息（第三方 API 特有）
                "weight": item.get("weight"),              # 净重
                "gross_weight": item.get("grossWeight"),   # 毛重
                "packing": item.get("packing"),            # 包装方式
                "packing_size": item.get("packingSize"),   # 单品包装尺寸
                "carton_size": item.get("cartonSize"),     # 外箱尺寸
                "carton_qty": item.get("cartonQty"),       # 装箱数量
                
                # 代发信息
                "agent_price": item.get("agent_price"),
                "agent_fee": item.get("agent_fee"),
                "dropship_support": item.get("is_support_dropship"),
                
                # 供应商
                "supplier": item.get("seller_nick"),
                "supplier_level": item.get("seller_level"),
                "factory_cert": item.get("factory_certification"),
                
                # SKU
                "skus": item.get("skus", []),
                "props_list": item.get("props_list", {}),
                
                # 图片
                "images": item.get("item_imgs", []),
                "desc_images": item.get("desc_imgs", []),
            }
        
        return {"error": data.get("msg", "请求失败")}
        

六、数据应用场景

6.1 选品分析

def analyze_product(product: ProductDetail) -> dict:
    """
    商品选品分析
    """
    # 计算利润率
    if product.price_ranges and product.price_ranges[0].price > 0:
        cost_price = product.price_ranges[0].price
        suggested_retail = cost_price * 2.5  # 建议零售价
        profit_margin = (suggested_retail - cost_price) / suggested_retail
        
        return {
            "product_id": product.product_id,
            "title": product.title,
            "cost_price": cost_price,
            "suggested_retail": suggested_retail,
            "profit_margin": f"{profit_margin*100:.1f}%",
            "moq": product.min_order_quantity,
            "is_dropship": product.support_agent,
            "supplier_level": product.supplier.credit_level,
            "recommendation": "推荐" if profit_margin > 0.5 and product.support_agent else "谨慎"
        }
    
    return {}
    

6.2 物流成本估算

def estimate_shipping_cost(product: ProductDetail, destination: str) -> dict:
    """
    估算物流成本
    """
    shipping = product.shipping
    
    # 解析包装尺寸
    if shipping.package_size:
        dims = [float(x) for x in shipping.package_size.split('x')]
        if len(dims) == 3:
            l, w, h = dims
            volume_weight = (l * w * h) / 5000  # 体积重系数 1:5000
            
            return {
                "actual_weight": shipping.unit_weight,
                "volume_weight": round(volume_weight, 2),
                "chargeable_weight": max(shipping.unit_weight, volume_weight),
                "volume": shipping.volume,
                "destination": destination,
                "estimated_cost": "需调用运费模板 API"
            }
    
    return {}
    

七、关键注意事项

八、总结

表格