电商平台api：1688 阿里巴巴平台商品详情全解析
1688（阿里巴巴中国站）作为国内最大的 B2B 批发平台，其商品详情数据涵盖了从基础信息到供应链属性的完整维度。本文将深入解析 1688 商品详情的全量数据字段，并对比主流电商平台的 API 接口体系，帮助开发者全面掌握 B2B 电商数据采集技术。
一、1688 商品详情数据结构全景图
plain
┌─────────────────────────────────────────────────────────────┐
│ 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 请求参数
表格
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
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 核心返回字段全解析
JSON
{
"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 完整实战：商品详情全字段采集，获取账号测试
Python
# -*- coding: utf-8 -*-"""
1688 商品详情全字段采集器
支持官方 API 和第三方聚合 API
"""import requestsimport hashlibimport timeimport jsonimport urllib.parsefrom typing import Dict, List, Optionalfrom dataclasses import dataclass, asdictfrom datetime import datetime@dataclassclass PriceRange:
"""阶梯价格"""
start_quantity: int
price: float@dataclassclass SkuItem:
"""SKU 规格"""
sku_id: str
properties: str # 如"黑色;标准版"
price: float
stock: int@dataclassclass ProductSpec:
"""商品规格定义"""
spec_id: str
name: str # 如"颜色"、"尺码"
values: List[Dict] # [{valueId, name}, ...]@dataclassclass ShippingInfo:
"""物流信息"""
freight_template_id: int
unit_weight: float # 单位重量(kg)
package_size: str # 包装尺寸(cm)
volume: int # 体积(cm³)
province: str
city: str@dataclassclass SupplierInfo:
"""供应商信息"""
supplier_id: str
company_name: str
credit_level: str
is_factory: bool
main_products: List[str]@dataclassclass 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: strclass 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 商品详情字段对比
Python
# 各平台商品详情字段映射对比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 方案
5.1 第三方 API 优势
表格
| 优势 | 说明 |
|---|---|
| 字段完整 | 整合包装信息、代发价、工厂资质等分散字段 |
| 无需企业认证 | 个人开发者即可使用 |
| 多平台统一 | 一套接口对接淘宝、1688、拼多多等多个平台 |
| 额外数据 | 提供物流分析、利润计算等增值字段 |
5.2 第三方 API 调用示例
Python
import requestsclass 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 选品分析
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 特色 | 主流电商共性 |
|---|---|---|
| 价格体系 | 阶梯批发价、代发价、起订量 | 单件售价、促销价 |
| 供应链 | 工厂信息、诚信通、实力商家 | 店铺等级、自营标识 |
| 交易模式 | 混批、账期、跨境专供 | 零售、优惠券、积分 |
| 物流 | 重量体积、运费模板、发货地 | 快递、自提、次日达 |
1688 的商品详情 API 是 B2B 电商数据的核心入口，掌握其全字段结构和解析方法，对于构建选品系统、供应链管理平台、跨境采购工具等业务场景至关重要。通过官方 API 与第三方聚合 API 的灵活组合，可以最大化数据获取的完整性和开发效率。
