alibaba的商品详情接口（alibaba.item.get）是B2B供应链系统对接的核心，其返回的数据结构与C端平台有显著差异，更侧重于批发属性、供应商信息和批量采购数据。
🎯 接口核心定位与特性
alibaba.item.get 是1688开放平台官方提供的“单商品详情”接口，可一次性获取商品标题、价格、SKU、主图、详情图、属性、店铺名等全量字段。
与C端电商平台相比，它有以下几个B2B专属特性：
批发属性突出：包含起批量（MOQ）、阶梯价格（Step Price） 、混批规则等批发相关字段。
多规格支持：支持复杂的商品规格组合和对应的价格库存设置。
定制化能力：包含是否支持加工定制、定制周期等生产相关信息。
📋 接入前置准备
在编写代码前，需要完成以下准备工作：
| 准备项 | 具体要求 |
|---|---|
| 账号认证 | 注册1688开放平台账号，完成企业实名认证（个人开发者权限有限） |
| 创建应用 | 创建“自用型”或“第三方”应用，审核通过后获得 AppKey 和 AppSecret |
| 申请权限 | 在“API列表”中申请 alibaba.item.get 权限（审核约1-3个工作日） |
| 非授权商品权限 | 如访问非自有商品，需额外申请“非授权商品”权限，否则只能获取公开字段 |
| IP白名单 | 服务器出口配置HTTPS，准备固定IP白名单 |
⚙️ 核心参数说明
系统必传参数
| 参数名 | 类型 | 说明与踩坑经验 |
|---|---|---|
| app_key | String | 开放平台申请的APP_KEY，务必存在环境变量中，别硬编码 |
| method | String | 固定填 alibaba.item.get（注意不是 1688.item.get） |
| timestamp | String | 格式 yyyy-MM-dd HH:mm:ss，与1688服务器时间差不能超3分钟 |
| sign | String | 签名串，1688使用HMAC-SHA1或MD5签名，与淘宝的签名规则不同 |
| format | String | 固定 json，1688不支持XML |
| v | String | 版本号，固定 2.0 |
🔐 签名机制（关键避坑点）
1688的签名机制与淘宝不同，很多开发者直接套用淘宝的MD5逻辑会导致 sign error。
请求网关： http://o0b.cn/WSMpp3 （HTTPS，支持 GET/POST）
请求方式：GET / POST
💻 Python完整调用代码
以下代码封装了完整的签名生成与请求逻辑
# coding:utf-8
"""
Compatible for python2.x and python3.x
requirement: pip install requests
"""
from __future__ import print_function
import requests
# 请求示例 url 默认请求参数已经做URL编码
# 封装好API demo url=o0b.cn/ibrad +v: TaoxiJd-api
url = "https://api-gw.cn/1688/item_get/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&num_iid=610947572360"
headers = {
"Accept-Encoding": "gzip",
"Connection": "close"
}
if __name__ == "__main__":
r = requests.get(url, headers=headers)
json_obj = r.json()
print(json_obj)📊 核心返回字段解析
接口返回的数据结构复杂但完整，以下是核心模块的字段说明：
商品基础信息
| 字段路径 | 类型 | 说明 |
|---|---|---|
| item_id | Long | 商品唯一ID |
| title | String | 商品标题 |
| subject | String | 商品副标题（厂家直销、支持定制等） |
| price | String | 单价（元） |
| price_unit | String | 计价单位（件、个、箱等） |
| quantity | Integer | 总库存 |
| pic_url | String | 主图URL |
| detail_url | String | 商品详情页URL |
| category_id | Integer | 类目ID |
批发交易字段（B2B核心）
| 字段路径 | 类型 | 说明 |
|---|---|---|
| min_buy_quantity | Integer | 起订量（MOQ） |
| step_price | Array | 阶梯价格列表，包含 quantity 和 price |
| trade_props | Array | 交易属性（货源类别、是否支持OEM等） |
SKU与规格信息
| 字段路径 | 类型 | 说明 |
|---|---|---|
| sku_infos.sku_info | Array | SKU列表 |
| sku_infos.sku_info[].sku_id | String | SKU ID |
| sku_infos.sku_info[].price | String | SKU单价 |
| sku_infos.sku_info[].quantity | Integer | SKU库存 |
| sku_infos.sku_info[].spec_json | String | 规格JSON（如 {"颜色":"白色","尺码":"M"}） |
⚠️ 常见错误与限流处理
常见错误
| 错误码 | 含义 | 解决方案 |
|---|---|---|
| 400 | 参数错误（缺失/格式非法） | 校验请求参数，按文档规范传参 |
| 429 | 调用频率超限 | 执行限流降级策略（等待/重试/熔断） |
| ISP_FLOW_CONTROL_LIMIT | 触发限流 | 降低请求频率，使用队列+缓存策略 |
💎 总结
1688商品详情API是B2B供应链对接的关键工具。对接时需重点关注签名机制（与淘宝不同） 、B2B专属字段（阶梯价、MOQ） 以及限流策略。建议优先使用 alibaba.item.get 接口，并通过 fields 参数按需获取字段，在合规前提下构建稳定的供应链数据同步系统。
