找商网 item_search_shop 接口（官方标准命名 zhaoshang.item_search_shop）是面向工业品、机械设备、原材料、五金工具等 B2B 批发场景的企业商品批量检索接口，通过企业店铺唯一标识 seller_id 可获取指定公司的全量商品列表，支持按品类、价格区间、库存状态、上架时间等维度筛选分页数据。该接口采用 HTTPS+AppKey/Secret+Timestamp+Sign 签名认证 机制，支持 JSON/XML 双格式返回，具备企业商品全覆盖、筛选维度贴合 B 端采购、数据与企业供应能力联动的特点，是构建供应商商品台账、企业店铺聚合页、竞品分析系统的核心工具。本攻略提供从接口认知、权限准备、实操对接、调试排错到生产级优化的全链路标准化指导。
一、接口核心认知：功能与适配场景
- 接口定位与核心价值
核心功能：输入seller_id、品类编码、价格区间、库存状态、上架时间等筛选条件，返回指定企业的分页商品列表；支持按价格、销量、产能、上架时间等维度排序，单页最大返回 50 条数据；可联动 seller_info 接口获取企业资质、item_get 接口获取商品详情，形成 “企业洞察 - 商品检索 - 详情分析” 的 B2B 采购完整链路。
找商网数据特性
企业商品全量覆盖：支持获取企业在售、预售、定制款等全状态商品，区别于仅展示热销商品的通用搜索接口，适配供应商全品类商品梳理需求；
供应能力属性联动：返回商品的最小起订量、月产能、交货周期等供应数据，直接关联企业生产能力，辅助采购方评估供货稳定性；
工业品属性适配：商品列表字段包含材质、执行标准等工业品专属属性，无需额外接口调用即可获取核心采购决策信息；
数据实时性强：商品上架、价格调整、库存更新等动态数据5 分钟内同步，保障企业商品列表的时效性。
典型应用场景
供应商商品台账系统：批量采集合作企业的商品数据，建立动态商品台账，跟踪商品价格、库存与供应能力变化；
企业店铺聚合页：嵌入自有采购平台，展示指定供应商的全品类商品，支持按品类、价格筛选，提升采购对接效率；
竞品分析工具：获取竞品企业的商品结构、价格带分布、热销品类，辅助自身产品定价与选品决策；
采购需求匹配系统：基于企业商品列表，匹配采购方的品类、规格需求，智能推荐优质供应商商品。 - 核心参数与返回字段
（1）请求参数（GET/POST 提交，需签名认证）
参数类型 参数名称 类型 是否必填 说明 应用示例
公共参数 app_key string 是 应用唯一标识（开放平台获取） zs2026appkey123abc
app_secret string 是 应用秘钥（签名核心，需保密） zs2026secret456def
method string 是 接口名称，固定为zhaoshang.item_search_shop zhaoshang.item_search_shop
format string 否 响应格式，默认 JSON json/xml
timestamp string 是 秒级时间戳，与服务器时差≤5 分钟 1735689600
v string 是 接口版本，固定为1.0 1.0
业务参数 seller_id string 是 企业店铺唯一 ID ZSS20260301001
cate_id string 否 企业内部分类编码 301002（机床配件类）
price_min float 否 最低批发价（元 / 单位） 500
price_max float 否 最高批发价（元 / 单位） 10000
stock_status int 否 库存状态（0 = 不限，1 = 现货，2 = 预售，3 = 缺货） 1
sort_type string 否 排序方式，默认publish_time_desc price_asc/capacity_desc/sales_desc
page_num int 否 页码，默认 1 2
page_size int 否 单页条数，默认 20，最大 50 50
注意事项
seller_id 可通过 seller_info 接口或找商网企业店铺主页 URL 提取，格式为ZSS+日期+序号；
timestamp 需调用找商网 zhaoshang.time.get 接口同步，避免时间误差导致签名失败；
签名生成需包含所有非空参数（排除app_secret），参数名按 ASCII 升序排序，参数缺失或排序错误会直接触发认证失败。
（2）返回核心字段（按业务分类）
字段分类 核心字段 说明
商品基础标识 item_id、item_name、brand、spec、item_img item_id为调用item_get接口的唯一凭证
价格与供应信息 price_wholesale、step_price、min_order、month_capacity、delivery_cycle step_price：阶梯报价（JSON 格式）；month_capacity：月产能
库存与状态信息 stock、stock_status、on_sale、publish_time stock_status：1 = 现货 / 2 = 预售 / 3 = 缺货；on_sale：是否在售
企业分类信息 shop_cate_name、cate_sort shop_cate_name：企业内部分类名称；cate_sort：分类排序优先级
分页信息 total、page_num、page_size、has_next total：企业符合条件的商品总数；has_next：是否有下一页
提示：该接口不返回企业详情信息，如需获取企业名称、信用等级、联系方式等数据，需联动调用 seller_info 接口。 - 接口限制与注意事项
权限类型 日调用上限 调用频率 适用场景
个人测试权限 50 次 / 天 1 次 / 秒 功能调试、单个企业商品查询
企业基础权限 500 次 / 天 3 次 / 秒 中小型采购商、经销商供应商选品
企业高级权限 5000 次 / 天 10 次 / 秒 大型供应链平台、生产企业采购系统
数据缓存规则：企业商品列表数据缓存15 分钟，短时间内重复调用同一seller_id+ 筛选条件会返回缓存数据；
企业权限限制：部分品牌厂家的商品数据仅对授权合作方开放，无权限时返回 403 错误；
调用频率限制：超出频率上限会触发临时封禁 10 分钟，多次超限会导致权限降级；
合规要求：数据仅可用于企业内部采购决策或自有平台展示，严禁转售、篡改或用于恶意竞品分析，违反协议会被永久封禁账号。
二、对接前准备：权限与环境搭建 - 获取接口权限（官方唯一合规路径）
找商网 item_search_shop 接口权限需通过找商网开放平台申请，步骤如下：
注册开发者账号：选择个人开发者或企业开发者，填写基本信息并完成实名认证；
提交资质审核：
企业用户：上传营业执照、工业品采购备案证明（如有）、法人身份证；
个人用户：上传身份证，填写应用用途（如 “个人供应商商品检索工具”）；
创建应用：填写应用名称、服务器 IP 白名单、数据用途说明，提交审核（1-2 个工作日完成）；
获取密钥：审核通过后，在 “应用管理 - 密钥管理” 中获取app_key和app_secret；
申请接口权限：在 “权限管理” 中选择zhaoshang.item_search_shop接口，提交申请，基础权限即时开通，高级权限需额外提交《数据合规使用承诺书》。
风险提示：严禁通过爬虫、抓包等非官方方式获取企业商品数据，违反协议会承担相应法律责任。 - 技术环境准备
（1）支持语言与协议
协议：HTTPS（强制），HTTP 请求会被直接拦截并返回 403 错误；
开发语言：Python、Java、PHP、Go 等主流语言均可，推荐 Python（代码简洁，适配异步并发与数据解析）。
（2）必备工具与依赖
工具类型 推荐工具 用途
调试工具 找商网开放平台调试工具 在线输入参数、生成签名、测试接口响应
Postman 模拟 GET/POST 请求，保存不同企业的测试用例
开发依赖（Python） requests 发送 HTTPS 请求
hashlib 生成 MD5 签名
jsonpath-ng 快速解析 JSON 格式的商品列表数据
pandas 整理商品数据并导出 Excel
辅助工具 Redis 缓存企业商品列表，减少重复调用
logging 记录接口调用日志，便于问题排查
三、实操步骤：接口对接全流程（Python 示例）
步骤 1：理解签名认证规则（核心，必掌握）
找商网 item_search_shop 接口采用 MD5 签名认证 机制，签名逻辑与item_get接口一致，核心步骤如下：
收集所有非空请求参数（含公共参数和业务参数，排除app_secret）；
按参数名ASCII 升序排序（如app_key排在cate_id之前）；
拼接参数为 key1value1key2value2... 的字符串格式（无分隔符，参数值需与传入一致）；
将 app_secret 拼接在字符串末尾，生成签名原串（格式：拼接参数串 + app_secret）；
对原串进行 MD5 加密，转为小写字符串，即为签名 sign；
将 sign 添加到请求参数中，发送 HTTPS GET 请求。
关键提醒：找商网接口签名为无分隔符拼接 + MD5 小写，与部分平台的key=value&拼接格式不同，需重点核对代码逻辑。
步骤 2：完整代码实现（含签名生成 + 调用 + 数据标准化）
（1）依赖安装
bash
运行
pip install requests hashlib jsonpath-ng pandas
（2）Python 代码实现
import requests
import hashlib
import time
import logging
import pandas as pd
from typing import Optional, Dict, List
日志配置：记录调用日志，便于问题排查与审计
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
handlers=[logging.FileHandler("zhaoshang_item_search_shop.log"), logging.StreamHandler()]
)
配置信息（替换为你的开放平台密钥）
CONFIG = {
"app_key": "你的app_key",
"app_secret": "你的app_secret",
"api_url": "https://openapi.zhaoshang.com/router/rest",
"format": "json",
"version": "1.0"
}
def generate_sign(params: Dict[str, str], app_secret: str) -> str:
"""生成找商网接口签名（MD5加密，小写）"""
# 1. 按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接为 key1value1key2value2 格式（无分隔符）
param_str = "".join([f"{k}{v}" for k, v in sorted_params])
# 3. 拼接app_secret并MD5加密，转小写
sign_str = param_str + app_secret
sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().lower()
return sign
def standardize_shop_product(raw_product: Dict) -> Dict:
"""标准化企业商品数据，统一输出格式"""
# 处理库存状态
stock_status = raw_product.get("stock_status", 0)
stock_status_desc = {
1: "现货",
2: "预售",
3: "缺货",
0: "不限"
}.get(stock_status, "未知")
# 处理价格与供应信息
price_wholesale = raw_product.get("price_wholesale", 0.0)
step_price = raw_product.get("step_price", {})
step_price_desc = "; ".join([f"{k}件：{v}元/件" for k, v in step_price.items()]) if step_price else "无阶梯报价"
min_order = raw_product.get("min_order", 0)
month_capacity = raw_product.get("month_capacity", 0)
delivery_cycle = raw_product.get("delivery_cycle", "协商确定")
# 处理商品状态
on_sale = raw_product.get("on_sale", False)
sale_status_desc = "在售" if on_sale else "下架"
return {
"商品ID": raw_product.get("item_id", ""),
"商品名称": raw_product.get("item_name", ""),
"品牌": raw_product.get("brand", "无品牌"),
"型号规格": raw_product.get("spec", "暂无"),
"批发价(元/单位)": price_wholesale,
"阶梯报价": step_price_desc,
"最小起订量": min_order,
"月产能": month_capacity,
"交货周期": delivery_cycle,
"库存数量": raw_product.get("stock", 0),
"库存状态": stock_status_desc,
"企业内部分类": raw_product.get("shop_cate_name", "暂无"),
"商品状态": sale_status_desc,
"上架时间": raw_product.get("publish_time", "暂无"),
"数据更新时间": raw_product.get("update_time", "暂无"),
"请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
}
def zhaoshang_item_search_shop(
seller_id: str,
cate_id: Optional[str] = None,
price_min: Optional[float] = None,
price_max: Optional[float] = None,
stock_status: int = 0,
sort_type: str = "publish_time_desc",
page_num: int = 1,
page_size: int = 20
) -> Dict:
"""调用找商网item_search_shop接口获取企业商品列表"""
# 1. 校验必填参数
if not seller_id:
return {"success": False, "error_msg": "seller_id不能为空", "data": [], "pagination": {}}
if not CONFIG["app_key"] or not CONFIG["app_secret"]:
return {"success": False, "error_msg": "app_key或app_secret未配置", "data": [], "pagination": {}}
# 2. 构建公共参数
params = {
"app_key": CONFIG["app_key"],
"method": "zhaoshang.item_search_shop",
"format": CONFIG["format"],
"v": CONFIG["version"],
"timestamp": str(int(time.time())),
"seller_id": seller_id,
"stock_status": str(stock_status),
"sort_type": sort_type,
"page_num": str(page_num),
"page_size": str(min(page_size, 50)) # 限制最大条数为50
}
# 3. 添加工业务参数
if cate_id:
params["cate_id"] = cate_id
if price_min is not None:
params["price_min"] = str(price_min)
if price_max is not None:
params["price_max"] = str(price_max)
# 4. 生成签名
sign = generate_sign(params, CONFIG["app_secret"])
params["sign"] = sign
try:
# 5. 发送HTTPS请求
response = requests.get(
url=CONFIG["api_url"],
params=params,
timeout=15,
verify=True # 生产环境必须开启证书验证
)
response.raise_for_status() # 抛出HTTP状态码异常
result = response.json()
# 6. 解析响应结果
if result.get("code") != 200:
error_msg = f"[{result.get('code', '未知错误')}] {result.get('msg', '无错误信息')}"
logging.error(f"获取企业商品失败（企业ID：{seller_id}）：{error_msg}")
return {"success": False, "error_msg": error_msg, "data": [], "pagination": {}}
raw_products = result.get("data", {}).get("product_list", [])
pagination = {
"total": result.get("data", {}).get("total", 0),
"page_num": page_num,
"page_size": page_size,
"has_next": result.get("data", {}).get("has_next", False)
}
if not raw_products:
logging.warning(f"企业无匹配商品（企业ID：{seller_id}）")
return {"success": True, "error_msg": "", "data": [], "pagination": pagination}
# 7. 标准化数据
standard_products = [standardize_shop_product(product) for product in raw_products]
return {
"success": True,
"error_msg": "",
"data": standard_products,
"pagination": pagination
}
except requests.exceptions.RequestException as e:
logging.error(f"网络请求异常（企业ID：{seller_id}）：{str(e)}")
return {"success": False, "error_msg": f"网络异常：{str(e)}", "data": [], "pagination": {}}
except Exception as e:
logging.error(f"数据解析异常（企业ID：{seller_id}）：{str(e)}")
return {"success": False, "error_msg": f"解析异常：{str(e)}", "data": [], "pagination": {}}
调用示例
if name == "main":
# 示例：获取指定企业的机床配件类现货商品，价格500-10000元，按月产能排序
target_seller_id = "ZSS20260301001"
cate_id = "301002"
price_min = 500.0
price_max = 10000.0
stock_status = 1 # 仅现货
sort_type = "capacity_desc" # 月产能优先
result = zhaoshang_item_search_shop(
seller_id=target_seller_id,
cate_id=cate_id,
price_min=price_min,
price_max=price_max,
stock_status=stock_status,
sort_type=sort_type,
page_size=20
)
if result["success"]:
print(f"获取成功！企业 {target_seller_id} 共找到 {result['pagination']['total']} 件商品")
print("=== 前5件商品信息 ===")
for product in result["data"][:5]:
print(f"{product['商品ID']} | {product['商品名称']} | {product['批发价(元/单位)']} | {product['库存状态']} | {product['月产能']}")
# 保存为Excel
df = pd.DataFrame(result["data"])
df.to_excel(f"找商网企业商品列表_{target_seller_id}.xlsx", index=False)
# 翻页示例
if result["pagination"]["has_next"]:
next_page_result = zhaoshang_item_search_shop(
seller_id=target_seller_id,
cate_id=cate_id,
price_min=price_min,
price_max=price_max,
stock_status=stock_status,
sort_type=sort_type,
page_num=2,
page_size=20
)
print(f"下一页获取到 {len(next_page_result['data'])} 件商品")
else:
print(f"获取失败：{result['error_msg']}")
四、调试与问题排查：快速解决对接异常
- 优先用官方工具调试（排除签名与参数问题）
登录找商网开放平台调试工具，选择 zhaoshang.item_search_shop 接口；
输入seller_id、cate_id、price_min等参数，点击 “生成签名” 并发送请求；
若官方工具调用成功 → 问题出在代码的签名生成逻辑或参数拼接错误（如参数未按 ASCII 升序排序、数值参数未转字符串）；
若官方工具调用失败 → 问题出在权限配置或参数有效性（如seller_id错误、IP 未加入白名单、无企业数据访问权限）。 - 高频问题排查表
问题现象 常见原因 解决方案
签名验证失败（401） 1. app_key/app_secret 错误或过期； - 参数未按 ASCII 升序排序；
- 签名原串拼接错误（有分隔符）；
- timestamp 与服务器时差 > 5 分钟 1. 核对开放平台密钥信息，过期则重新申请；
- 严格按参数名 ASCII 升序排序所有非空参数；
- 修正签名逻辑，采用无分隔符的 keyvalue 拼接格式；
- 调用 zhaoshang.time.get 接口同步服务器时间
权限不足（403） 1. 未申请 item_search_shop 接口权限； - 服务器 IP 不在白名单；
- 调用频率超限；
- 企业为品牌厂家且无授权 1. 在开放平台 “权限管理” 中申请接口；
- 添加服务器公网 IP 到应用白名单；
- 降低调用频率，控制并发数≤权限上限；
- 联系企业或平台申请授权访问
参数错误（400） 1. seller_id 为空或格式非法； - price_min > price_max；
- cate_id 非企业内有效分类编码；
- page_size 超过 50 1. 确保传入有效的 seller_id，格式为ZSS+日期+序号；
- 校验价格区间，确保下限≤上限；
- 通过企业店铺主页获取有效分类编码；
- 将 page_size 限制在 50 以内
无商品数据返回（200 但 data 为空） 1. 企业无符合筛选条件的商品； - 企业已下架所有商品或被封禁；
- stock_status 设置为 1 但企业无现货 1. 放宽筛选条件（如 stock_status 设为 0、扩大价格区间）；
- 验证 seller_id 对应的企业是否正常运营；
- 更换 stock_status 参数值重新测试
响应超时（504） 1. 网络波动或服务器负载高； - page_size 设置过大（如 50）且企业商品数量多；
- 高峰期调用（工作日 9:00-12:00/14:00-18:00） 1. 添加重试机制，设置超时时间为 15 秒；
- 减小 page_size（如改为 20），分批次获取数据；
- 避开高峰期调用，调度到凌晨低峰期
五、进阶优化：生产级稳定性提升 - 性能与配额优化
多企业查询并发优化：批量获取多个企业商品列表时，采用 异步并发框架（如 Python 的aiohttp），并发数严格控制在权限允许的频率上限内（如企业基础权限 3 次 / 秒）；为不同企业的请求设置独立队列，避免单企业请求阻塞整体流程。
分层缓存策略：用 Redis 构建二级缓存体系，降低接口调用频率：
一级缓存：缓存企业 + 筛选条件的商品列表，key 为 zhaoshang_shopsearch企业ID分类ID价格区间_库存状态，缓存时间 15 分钟；
二级缓存：缓存单个商品详情（复用item_get接口的缓存），key 为 zhaoshangitem商品ID，缓存时间 30 分钟；
缓存主动失效：当监测到企业有商品上新或价格调整时，主动删除对应企业的一级缓存。
请求参数预处理：前端筛选组件增加参数合法性校验，例如限制price_min≥0、page_num≥1；对高频筛选条件（如现货、月产能≥1000）做预设选项，减少无效请求。 - 数据质量优化
数据清洗与去重：
按item_id去重，避免同一商品因筛选条件不同重复出现在列表中；
过滤异常数据（如价格≤0、最小起订量≤0 且状态为现货的商品）；
统一字段格式（如价格保留 2 位小数，交货周期统一为 “X 个工作日” 格式）；
缺失值填充（如无品牌的商品填充为 “无品牌”，无月产能的填充为 “未知”）。
多维度数据增强：联动item_get接口补充商品技术参数、交易保障等信息，联动seller_info接口补充企业名称、信用等级等信息，提升数据的完整性和可用性。 - 合规与安全优化
密钥与权限管理：
生产环境禁止硬编码密钥，将app_key和app_secret存入配置中心（如 Nacos、Apollo），应用启动时通过加密通道拉取；
为不同环境（测试 / 生产）配置不同的开发者账号，避免测试环境密钥泄露影响生产；
定期轮换app_secret（建议每 3 个月一次），并同步更新配置中心的密钥信息。
熔断与降级机制：
引入熔断器（如pybreaker），当接口连续失败次数≥5 次时，触发熔断，暂停调用 5 分钟；熔断期间返回缓存数据或友好提示；
对非核心业务（如企业商品推荐）设置降级策略，当接口调用压力过大时，关闭该功能，优先保障核心的商品检索功能。
日志与审计：记录每次调用的seller_id、筛选条件、响应状态、耗时、返回数据量等信息，日志保留至少 30 天；定期审计日志，排查异常调用行为。
六、扩展场景：接口联动与功能升级
企业商品全景分析系统：联动 seller_info 获取企业资质 → item_search_shop 获取全量商品 → item_get 获取商品详情 → 分析企业的商品结构、价格带分布、供应能力，生成企业供应能力评估报告；
供应商动态监控系统：定时调用 item_search_shop 接口，监控合作企业的商品上新、价格调整、库存变化，当出现价格下跌或库存预警时，触发采购提醒；
多企业比价系统：同时获取多个同类企业的商品列表，按商品名称、规格进行匹配，生成同款商品的跨企业价格、供应能力对比表，辅助采购决策；
供应商准入评估系统：结合企业商品的品类覆盖度、价格竞争力、供应稳定性数据，构建供应商准入评分模型，自动化完成供应商准入审核。
