item_get_app 接口实战：手把手拿到 1688 商品「原数据+H5」-优快云博客

关键词：item_get_app、1688、H5 原数据、签名、限流、缓存

一、接口定位

item_get_app 是 1688 开放平台专为「无线 H5 商品详情页」场景提供的私有接口，一次性返回两份数据：

商品原数据（JSON）：标题、价格、SKU、库存、阶梯价、主图、详情图、店铺、类目、属性、运费模板等 80+ 字段；
H5 渲染数据（HTML）：官方最新版详情页骨架，含图文、视频、规格选择器，可直接嵌入 App WebView。

相比老接口 alibaba.item.get，item_get_app 字段更全、图片带宽更高，且自带「已登录」态下的批发价/混批标签，适合需要「所见即所得」的选品/铺货/小程序场景。

二、前置条件

步骤	说明
1. 企业认证	账号必须完成 1688 企业实名
2. 创建应用	控制台新建「无线应用」→ 勾选 item_get_app 权限
3. 签约套餐	免费版 5 次/秒 5000 次/日；选品/ERP 场景建议专业版（50 次/秒 50 万/日）
4. 白名单	填写服务器出口 IP；如用代理网关，需同时把代理 IP 填入

三、核心参数

字段	类型	必须	示例	备注
method	String	是	item_get_app	固定值
app_key	String	是	12345678	控制台查看
timestamp	String	是	2025-12-19 14:23:45	格式 `yyyy-MM-dd HH:mm:ss`
item_id	Long	是	610947572360	商品数字 ID
fields	String	否	*	原数据字段过滤，逗号分隔；传空默认全字段
need_html	Boolean	否	true	是否同时返回 H5 骨架，默认 false
sign	String	是	——	见下方签名算法

四、签名算法（官方 HMAC-SHA1）

除 sign 外所有参数按 Key 升序排序
拼成 key=value&key=value 字符串，value 需 URL encode
首尾拼接 app_secret 作为密钥，做 HMAC-SHA1 加密，再转大写
把结果放到 sign 字段即可

伪代码：

String toSign = "app_key=xxx&fields=xxx&item_id=xxx&method=xxx&need_html=true&timestamp=2025-12-19+14%3A23%3A45";
String sign = HmacSHA1(app_secret + toSign + app_secret).toUpperCase();

五、完整请求示例（Python）

import time, hmac, hashlib, requests, urllib.parse

APP_KEY    = '你的AppKey'
APP_SECRET = '你的AppSecret'
ITEM_ID    = 610947572360

url = 'https://gw.open.1688.com/openapi/param2/1/item_get_app/{}'.format(APP_KEY)

params = {
    "method"    : "item_get_app",
    "app_key"   : APP_KEY,
    "timestamp" : time.strftime("%Y-%m-%d %H:%M:%S"),
    "item_id"   : ITEM_ID,
    "fields"    : "item_id,title,price,sku_list,pics,spec_info,shop_name",
    "need_html" : "true"
}

# 1. 排序+拼串
query = '&'.join([f"{k}={urllib.parse.quote(str(params[k]))}" for k in sorted(params)])
# 2. HMAC-SHA1 签名
sign = hmac.new((APP_SECRET + query + APP_SECRET).encode(),
                digestmod=hashlib.sha1).hexdigest().upper()
params['sign'] = sign

# 3. 发送 GET
resp = requests.get(url, params=params, timeout=10)
data = resp.json()

if 'error_response' in data:
    print('失败:', data['error_response']['msg'])
else:
    item = data['item_get_app_response']['item']
    print('标题:', item['title'])
    print('价格:', item['price'])
    print('H5 骨架长度:', len(item['html']))

返回片段（已脱敏）：

{
  "item_get_app_response": {
    "item": {
      "item_id": 610947572360,
      "title": "2025冬季新款羽绒服女",
      "price": "268.00",
      "sku_list": [ {...} ],
      "pics": [ "https://img.alicdn.com/imgextra/..." ],
      "html": "<!DOCTYPE html><html>...(官方H5骨架)</html>"
    }
  }
}

六、常见踩坑指南

坑点	现象	解决
timestamp 格式错	401 签名无效	必须带 `-` 和 `:`，且 URL 编码后空格变 `+`
参数未升序	403 签名不对	用 `TreeMap` / `sorted()` 保证顺序
need_html=true 却返回空	套餐权限不足	专业版才给 H5 字段，免费版只返回原数据
QPS 超限	429 Too Many Requests	降到 5 次/秒以内，或升级套餐
item_id 不存在	1001 商品不存在	先通过搜索接口确认商品状态，再入库