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 接口基本信息
| 属性 | 说明 |
|---|---|
| 接口地址 | https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get |
| 请求方式 | POST / GET |
| 数据格式 | application/x-www-form-urlencoded |
| 返回格式 | JSON |
| 接口版本 | 2.0（2026 年主推，1.0 已不返回核心字段） |
2.2 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
app_key | String | 是 | 应用唯一标识 |
method | String | 是 | 固定值 com.alibaba.product.alibaba.product.get |
timestamp | String | 是 | 时间戳（yyyy-MM-dd HH:mm:ss） |
v | String | 是 | API 版本：2.0 |
format | String | 是 | 返回格式：json |
sign | String | 是 | MD5 签名 |
access_token | String | 是 | OAuth2.0 授权令牌 |
productId | Long | 是 | 1688 商品数字 ID |
fields | String | 否 | 指定返回字段，逗号分隔 |
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 平台接口体系概览
表格
| 平台 | 核心详情接口 | 特色字段 | 认证要求 |
|---|---|---|---|
| 1688 | alibaba.product.get | 阶梯价、起订量、代发价、工厂信息 | 企业认证 |
| 淘宝/天猫 | taobao.item.get | 优惠券、天猫积分、物流模板 | 个人/企业 |
| 京东 | jd.item.get | 京东价、PLUS 价、自营标识 | 企业认证 |
| 拼多多 | pdd.goods.detail.get | 拼单价、百亿补贴、成团价 | 企业认证 |
| 抖音电商 | douyin.product.detail | 直播价、达人佣金、短视频挂车 | 企业认证 |
| 亚马逊 | GetMatchingProduct | ASIN、BuyBox、FBA 费用 | 开发者账号 |
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 接入差异
| 维度 | 1688 | 淘宝/天猫 | 京东 | 拼多多 |
|---|---|---|---|---|
| 开发者类型 | 企业为主 | 个人/企业 | 企业 | 企业 |
| 审核周期 | 1-2 工作日 | 即时 | 3-5 工作日 | 1-3 工作日 |
| 免费额度 | 50 次/分钟 | 100 次/分钟 | 有限 | 有限 |
| 签名算法 | MD5 | MD5/HMAC | HMAC-SHA256 | MD5 |
| 数据更新延迟 | ~2 分钟 | ~1 分钟 | ~5 分钟 | ~3 分钟 |
| 特色能力 | 批发价/工厂直供 | 淘客佣金/直播 | 自营物流 | 社交电商裂变 |
五、第三方聚合 API 方案
由于官方 API 存在权限限制和字段分散的问题，实际开发中常使用第三方聚合 API 获取更完整的商品详情数据。
5.1 第三方 API 优势
| 优势 | 说明 |
|---|---|
| 字段完整 | 整合包装信息、代发价、工厂资质等分散字段 |
| 无需企业认证 | 个人开发者即可使用 |
| 多平台统一 | 一套接口对接淘宝、1688、拼多多等多个平台 |
| 额外数据 | 提供物流分析、利润计算等增值字段 |
5.2 第三方 API 调用示例
六、数据应用场景
6.1 选品分析
Python
复制
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 物流成本估算
Python
复制
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 {}
七、关键注意事项
| 注意事项 | 说明 |
|---|---|
| 企业认证 | 1688 官方 API 主要面向企业，个人权限受限 |
| 版本选择 | 2026 年使用 2.0 版本，1.0 不返回核心字段 |
| IP 白名单 | 必须在开放平台配置请求服务器 IP |
| 字段分散 | 包装信息等字段分布在多个子结构中，需完整解析 |
| 数据更新 | 商品信息实时变动，建议缓存 5-10 分钟 |
| 合规使用 | 仅用于自有业务分析，不得转售或恶意爬取 |
八、总结
| 能力维度 | 1688 特色 | 主流电商共性 |
|---|---|---|
| 价格体系 | 阶梯批发价、代发价、起订量 | 单件售价、促销价 |
| 供应链 | 工厂信息、诚信通、实力商家 | 店铺等级、自营标识 |
| 交易模式 | 混批、账期、跨境专供 | 零售、优惠券、积分 |
| 物流 | 重量体积、运费模板、发货地 | 快递、自提、次日达 |
1688 的商品详情 API 是 B2B 电商数据的核心入口，掌握其全字段结构和解析方法，对于构建选品系统、供应链管理平台、跨境采购工具等业务场景至关重要。通过官方 API 与第三方聚合 API 的灵活组合，可以最大化数据获取的完整性和开发效率。
600
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
