实战解析：京东关键词搜索 item_search_pro —— 按关键字搜索商品
一、接口定位
item_search_pro 并不是京东官方文档里出现的接口名，而是第三方服务商对「京东关键词搜索商品」能力的封装代号。它本质上调用的是京东联盟开放平台里的jd.union.open.goods.search（联盟版）或routerjson下的item_search（自营版）。
理解这一点后，后面的“实战”就三件事：
拿到合法调用身份（App-Key / Secret / Access-Token）
按业务场景拼参数、算签名
对 JSON 结果做字段裁剪与落库
二、账号与权限
注册「京东联盟」或「京东开放平台」→ 创建应用 → 审核通过后会拿到
App-Key、App-Secret；联盟版还需要备案推广位，才能回传佣金字段。沙箱测试：联盟后台提供在线调试窗，先勾选“仅看返回字段”，把必填参数跑通后再上代码。
配额：免费账号默认 5000 次/天，QPS≈10；申请「数据洞察」权限可扩容到 5W 次/天。
三、签名算法（以联盟版为例）
京东采用“参数名 ASCII 升序 + 首尾拼接 Secret 再 MD5”的签名方式，伪代码如下：
sign_str = app_secret for k, v in sorted(params.items()): if v == '' or v is None: continue sign_str += f'{k}{v}' sign_str += app_secret sign = md5(sign_str.encode()).hexdigest().upper()易踩坑点：
必须过滤空值；
时间戳格式是 “2026-01-04 12:34:56”，不要带毫秒；
param_json里的业务参数整体当作一个 value，不参与二次排序。
四、最小可运行 Python 示例
场景：搜“笔记本电脑”，价格 3000–8000 元，按销量倒序，取第 1 页 20 条。
import time, json, hashlib, requests class JdProSearch: def __init__(self, key, secret): self.key, self.secret, self.url = key, secret, \ "https://api.jd.com/routerjson" def sign(self, p): s = self.secret for k, v in sorted(p.items()): if v != '' and v is not None: s += f"{k}{v}" return hashlib.md5((s + self.secret).encode()).hexdigest().upper() def search(self, keyword, page=1, size=20, sort='sale_desc', price_min=None, price_max=None): biz = {"keyword": keyword, "pageIndex": page, "pageSize": size} if price_min: biz["priceMin"] = price_min if price_max: biz["priceMax"] = price_max if sort: biz["sortName"] = sort params = { "method": "jd.union.open.goods.search", "app_key": self.key, "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"), "format": "json", "v": "1.0", "param_json": json.dumps(biz, ensure_ascii=False) } params["sign"] = self.sign(params) rsp = requests.post(self.url, data=params, timeout=15).json() if "error_response" in rsp: raise RuntimeError(rsp["error_response"]["zh_desc"]) data = json.loads(rsp["jd_union_open_goods_search_response"]["result"]) return data["data"]["goodsList"], data["totalCount"] # 调用 api = JdProSearch("你的AppKey", "你的AppSecret") goods, total = api.search("笔记本电脑", price_min=3000, price_max=8000) print("共", total, "件商品，本页返回", len(goods)) for g in goods[:3]: print(g["skuId"], g["skuName"], "¥", g["price"])返回字段中skuId、price、promotionPrice、shopName、mainImageUrl最常用；如要拿券后价，再加couponInfo字段即可。
五、高级检索技巧
关键词组合：空格代表“且”，
+代表“或”，-代表排除；例如笔记本 +游戏本 -二手能过滤掉二手商品。类目锁定：先通过
category.search接口把三级类目 ID 取回来，再拼到categoryId参数，可把搜索范围缩小 70 % 以上。价格/佣金双重筛选：选品库场景常用
price_min、price_max、commissionShare同时过滤，快速找到“低价高佣”商品。排序权重：
sale_desc走量爆款；price_asc找低价货源；hot_desc结合京东“热度”算法，适合发现潜力新品。
翻页限制：京东只返回前 50 页（约 1000 条），深度分页会被截断；需要全量数据时，按“价格段 + 销量段”多次拆分即可。
六、反爬与容错
联盟接口本身对 IP 不做强校验，但返回包含有
trace_id，频繁 4xx 错误会被降权。建议：单 IP QPS≤10，失败重试 3 次后休眠 5 s；出现
40005 sign verify fail多数为时间戳偏差，校准时钟即可。数据落地前，对
price、promotionPrice做浮点两位截断；skuName做 128 位截断并过滤 emoji，可节省 30 % 存储。
七、典型业务落地
比价系统：每 30 min 拉一次 Top 5000 SKU，按
skuId更新价格、促销、券额，写入 Redis 供前端实时查询。选品后台：运营输入关键词 → 接口返回列表 → 勾选后加入“本地商品池”，同时记录佣金率与历史价，辅助决策。
**社群返利机器人：监听用户发来的关键词 → 实时搜索 → 返回二合一推广链接 + 券信息，整个过程 < 1.5 s。
八、常见错误码速查
| 代码 | 含义 | 处理办法 |
|---|---|---|
| 40005 | 签名错误 | 检查空值、时区、MD5 大小写 |
| 40006 | 应用不存在 | AppKey 写错或未上线 |
| 40010 | 无权限 | 未申请联盟“商品搜索”包 |
| 50001 | 关键词为空 | 前端过滤即可 |
九、小结
item_search_pro 本质就是京东官方关键词搜索能力的代理封装。真正的门槛只有两步：
把签名算对；
把业务参数拼细（类目、价格、排序、优惠券）。
跑通上述最小代码后，再结合自己的 SKU 池、价格策略与缓存机制，就能在比价、选品、返利、数据分析等场景中快速上线。祝你“搜”得开心，单量长虹！