1688 商品详情 API 接口系列是阿里巴巴 1688 开放平台（1688 Open Platform）提供的核心 B2B 电商数据接口集合，聚焦 1688 平台商品全维度信息的标准化获取，支持 JSON 格式统一返回。该系列接口深度适配 B2B 批发场景特性，覆盖基础信息、规格库存、批发规则、详情描述、商家资质等核心维度，是打通 1688 生态数据与第三方 B2B 应用（如分销管理、供应链采购、竞品分析工具）的关键技术支撑。
一、接口系列核心构成（按功能分类）
1688 商品详情相关 API 按业务场景可分为 5 大类，核心接口需完成企业 / 个人开发者资质认证与权限申请，具体如下：
1. 基础信息接口（核心入口）
- 代表接口：
alibaba.product.get（商品基础信息查询） - 核心功能：获取商品 ID、标题、批发价区间、起订量、销量、主图、类目、店铺类型等核心字段，是所有详情相关接口的基础依赖。
- 权限要求：个人开发者需实名认证，企业开发者需企业认证，接口默认开放基础权限（部分敏感字段如商家手机号需额外申请）。
2. 规格与库存接口
- 代表接口：
alibaba.product.spec.get（商品规格查询）、alibaba.product.inventory.get（库存查询） - 核心功能：获取商品规格组（颜色、尺寸、材质等）、SKU 组合信息、实时库存、规格对应批发价、最小起订量（MOQ）等，适配多规格批发场景。
- 适用场景：SKU 批量采购、库存预警、规格价格对比。
3. 批发规则接口
- 代表接口：
alibaba.product.price.get（批发价格查询） - 核心功能：返回商品阶梯批发价（如 1-10 件单价、10-50 件单价、50 件以上单价）、混批规则、邮费政策、开票信息等 B2B 核心规则。
4. 详情描述接口
- 代表接口：
alibaba.product.desc.get（商品详情描述查询） - 核心功能：返回商品详情页 HTML 内容、纯文本描述、详情图列表、参数规格表（如材质成分、技术参数）、产品认证信息（如 CE、RoHS）等。
5. 商家与资质接口
- 代表接口：
alibaba.seller.get（商家基础信息查询） - 核心功能：返回商品所属商家名称、店铺 ID、经营年限、诚信通等级、营业执照信息、供应能力（如年营业额、产能）等，支撑商家资质核验。
二、核心调用规范
1. 通用请求参数（所有接口必填）
| 参数名 | 类型 | 说明 |
app_key |
String | 应用唯一标识，1688 开放平台创建应用后获取 |
method |
String | 接口名称（如alibaba.product.get） |
sign |
String | 签名，按 “参数 ASCII 排序 + AppSecret 拼接 + HMAC-SHA1 加密 + Base64 编码” 生成 |
timestamp |
String | 时间戳（格式：yyyy-MM-dd HH:mm:ss），与 1688 服务器时差≤10 分钟 |
v |
String | 接口版本号，固定为2.0 |
format |
String | 响应格式，默认json，可选xml |
access_token |
String | 授权令牌，商家信息、敏感库存等接口需通过授权码模式获取 |
2. 调用限制
- 频率限制：个人开发者默认 60 次 / 分钟，企业开发者默认 300 次 / 分钟，超额返回错误码
429（请求过于频繁）。 - 沙箱环境：支持沙箱调试，测试商品 ID 需使用 1688 提供的沙箱专用 ID，避免正式环境数据污染。
- 数据时效性：库存、价格数据实时更新，销量、商家资质数据更新延迟≤30 分钟。
- B2B 特性限制：部分批发规则字段（如混批政策）仅对企业认证开发者开放，个人开发者可能返回字段缺失。
三、JSON 数据返回参考（核心接口示例）
1. alibaba.product.get（商品基础信息）返回示例
{ "alibaba_product_get_response": { "result": { "product_id": "698765432109", // 商品ID（1688唯一标识） "title": "2024新款无纺布购物袋 定制logo 环保手提袋 批发定做", // 商品标题 "category_name": "包装、印刷用品/纸类包装/购物袋", // 商品类目 "main_image": "https://img14.360buyimg.com/n1/jfs/t1/198888/33/28888/123456/647890abcdef1234/abcdef1234567890.jpg", // 主图URL "image_list": [ // 多图列表 "https://img14.360buyimg.com/n1/jfs/t1/198888/33/28888/123456/647890abcdef1234/abcdef1234567890.jpg", "https://img15.360buyimg.com/n1/jfs/t1/197777/22/29999/123457/647890abcdef1235/abcdef1234567891.jpg" ], "price_range": "1.20-0.80", // 批发价区间（低起订量-高起订量单价） "min_order_quantity": 10, // 最小起订量（MOQ） "sales_count": 12560, // 30天销量（B2B场景按订单数统计） "shop_name": "XX包装制品厂", // 店铺名称 "shop_type": "manufacturer", // 店铺类型（manufacturer=工厂，trader=贸易商） "shop_id": "12345678", // 店铺ID "trust_pass_level": "6年诚信通", // 诚信通等级 "publish_time": "2024-03-15 10:00:00", // 上架时间 "update_time": "2024-06-20 14:30:00", // 最近更新时间 "is_customizable": true, // 是否支持定制 "custom_service": "支持logo印刷、尺寸定制" // 定制服务说明 }, "request_id": "req1234567890abcdef" // 请求ID（用于问题排查） } }
2. alibaba.product.spec.get（SKU 规格与库存）返回示例
{ "alibaba_product_spec_get_response": { "result": { "product_id": "698765432109", "spec_groups": [ // 规格组 { "group_id": "1001", "group_name": "尺寸", "specs": [ {"spec_id": "2001", "spec_name": "25*35cm"}, {"spec_id": "2002", "spec_name": "30*40cm"} ] }, { "group_id": "1002", "group_name": "颜色", "specs": [ {"spec_id": "3001", "spec_name": "红色"}, {"spec_id": "3002", "spec_name": "蓝色"} ] } ], "sku_list": [ // SKU详情（B2B规格+批发价组合） { "sku_id": "88881111", "spec_ids": "2001,3001", // 规格ID组合（25*35cm+红色） "spec_names": "25*35cm,红色", // 规格名称组合 "price_levels": [ // 阶梯批发价 {"quantity": 10, "price": 1.20}, // 10-49件：1.20元/件 {"quantity": 50, "price": 1.00}, // 50-99件：1.00元/件 {"quantity": 100, "price": 0.80} // 100件以上：0.80元/件 ], "stock": 5680, // 实时库存 "sales_count": 3286 // SKU 30天销量 }, { "sku_id": "88881112", "spec_ids": "2002,3002", // 30*40cm+蓝色 "spec_names": "30*40cm,蓝色", "price_levels": [ {"quantity": 10, "price": 1.80}, {"quantity": 50, "price": 1.50}, {"quantity": 100, "price": 1.20} ], "stock": 3250, "sales_count": 2156 } ], "total_stock": 8930 // 商品总库存 }, "request_id": "req9876543210fedcba" } }
3. alibaba.product.price.get（批发规则）返回示例
{ "alibaba_product_price_get_response": { "result": { "product_id": "698765432109", "price_policy": { "base_price_range": "1.20-0.80", // 基础批发价区间 "mix_batch_rule": "支持混批，单款最低10件，总金额≥200元", // 混批规则 "freight_policy": "满500元免运费，不足500元运费15元（默认发中通快递）", // 运费规则 "invoice_support": true, // 是否支持开票 "invoice_type": "增值税普通发票、增值税专用发票" // 发票类型 }, "sku_price_list": [ // 各SKU批发价汇总 { "sku_id": "88881111", "sku_name": "25*35cm,红色", "min_price": 0.80, // 最低批发价（最大起订量） "max_price": 1.20 // 最高批发价（最小起订量） }, { "sku_id": "88881112", "sku_name": "30*40cm,蓝色", "min_price": 1.20, "max_price": 1.80 } ] }, "request_id": "reqabcdef1234567890" } }
4. alibaba.product.desc.get（商品详情描述）返回示例
{ "alibaba_product_desc_get_response": { "result": { "product_id": "698765432109", "desc_html": "<div class=\"detail-content\">...</div>", // 详情页HTML内容 "desc_text": "【材质】无纺布（克重80g） 【工艺】热压成型 【定制说明】logo可丝印/烫金...", // 纯文本描述 "desc_images": [ // 详情图列表 "https://img16.360buyimg.com/n1/jfs/t1/196666/44/30000/123458/647890abcdef1236/abcdef1234567892.jpg", "https://img17.360buyimg.com/n1/jfs/t1/195555/55/30111/123459/647890abcdef1237/abcdef1234567893.jpg" ], "param_table": [ // 商品参数表（B2B核心参数） {"name": "品牌", "value": "XX"}, {"name": "材质", "value": "80g无纺布"}, {"name": "尺寸", "value": "25*35cm、30*40cm（支持定制）"}, {"name": "印刷工艺", "value": "丝印、烫金、热转印"}, {"name": "起订量", "value": 10件"}, {"name": "交货期", "value": "现货48小时内发货，定制7-10天"} ], "certifications": [ // 产品认证（B2B出口场景常用） {"cert_name": "CE认证", "cert_url": "https://img18.360buyimg.com/n1/jfs/t1/194444/66/30222/123460/647890abcdef1238/abcdef1234567894.jpg"}, {"cert_name": "RoHS认证", "cert_url": "https://img19.360buyimg.com/n1/jfs/t1/193333/77/30333/123461/647890abcdef1239/abcdef1234567895.jpg"} ] }, "request_id": "reqfedcba9876543210" } }
5. alibaba.seller.get（商家基础信息）返回示例
{ "alibaba_seller_get_response": { "result": { "shop_id": "12345678", "shop_name": "XX包装制品厂", "seller_id": "87654321", // 卖家ID "shop_type": "manufacturer", // 店铺类型（工厂） "trust_pass_level": "6年诚信通", "business_years": 8, // 经营年限 "supply_capacity": { // 供应能力（B2B核心） "annual_turnover": "500-1000万元", // 年营业额 "monthly_output": "100万件", // 月产量 "delivery_time": "现货48小时，定制7-10天" // 交货期 }, "qualifications": [ // 商家资质 {"qualification_name": "营业执照", "qualification_url": "https://img20.360buyimg.com/n1/jfs/t1/192222/88/30444/123462/647890abcdef1240/abcdef1234567896.jpg"}, {"qualification_name": "生产许可证", "qualification_url": "https://img21.360buyimg.com/n1/jfs/t1/191111/99/30555/123463/647890abcdef1241/abcdef1234567897.jpg"} ], "contact_info": { // 联系信息（脱敏处理） "contact_person": "李经理", "phone": "138****1234", // 手机号脱敏 "address": "浙江省温州市XX工业区XX路XX号" } }, "request_id": "req1122334455aabbcc" } }
四、数据解析关键要点
- B2B 特性字段处理：
- 批发价区间（
price_range）需结合price_levels阶梯价解析，避免直接取单一价格导致误差； - 起订量（
min_order_quantity）分商品级和 SKU 级，需优先以 SKU 级起订量为准； - 混批规则（
mix_batch_rule）为文本描述，需通过正则提取核心条件（如 “单款最低 10 件”“总金额≥200 元”）。
- HTML 清洗：详情描述（
desc_html）含 1688 自定义标签（如alibaba-detail），需用BeautifulSoup等工具提取纯文本或结构化参数表，重点保留 B2B 核心信息（材质、工艺、定制规则、交货期）。 - 敏感信息处理：商家联系信息（如手机号）已脱敏，禁止通过接口获取完整隐私信息，合规使用数据。
- 错误处理：常见错误返回格式示例（如商品不存在）：
{ "error_response": { "code": 20001, "msg": "商品不存在", "sub_code": "isv.product-not-found", "sub_msg": "该商品已下架、删除或未通过平台审核", "request_id": "reqabc123def456" } }
- 字段适配：销量字段（
sales_count）在 B2B 场景按 “订单数” 统计（非件数），需结合起订量估算实际销量规模；库存字段（stock）为实时库存，支持预售商品的 “预售库存” 标注。
五、典型应用场景
- B2B 采购工具开发：整合商品基础信息、阶梯批发价、库存数据，实现 “批量比价、一键下单” 功能。
- 分销管理系统：同步供应商商品规格、定制规则、交货期，支撑分销商快速上架与订单对接。
- 供应商资质核验：通过商家信息接口提取诚信通等级、营业执照、供应能力数据，筛选优质供应商。
- B2B 市场分析：采集特定类目商品的批发价分布、起订量区间、商家类型占比，洞察行业供应链趋势。
如需进一步获取1688 商品详情 API 核心字段映射表或错误码排查手册，可随时告知，将为你补充整理。
