核心内容摘要
17.c-开启视界新篇章，官网在线免费观看，精彩触手可及
搜了网 item_search_shop 接口官方标准命名 soule.item_search_shop是面向多品类 B2B/B2C 混合交易场景的店铺商品批量检索接口通过店铺唯一标识 shop_id 可获取指定店铺的全量商品列表支持按品类、价格区间、库存状态、上架时间等维度筛选分页数据。
该接口采用 HTTPSAppKeySecretSign 签名认证 机制支持 JSON/XML 双格式返回具备店铺商品全覆盖、筛选维度灵活、数据与店铺运营状态联动的特点是构建商家店铺商品聚合页、供应商商品台账、店铺选品分析系统的核心工具。
本攻略提供从接口认知、权限准备、实操对接、调试排错到生产级优化的全链路标准化指导。
接口核心认知功能与适配场景
接口定位与
核心价值核心功能输入shop_id、品类编码、价格区间、库存状态、上架时间等筛选条件返回指定店铺的分页商品列表支持按价格、销量、上架时间、库存深度等维度排序单页最大返回 50 条数据可联动 seller_detail 接口获取店铺资质、item_get 接口获取商品详情形成 “店铺洞察 - 商品检索 - 详情分析” 的完整链路。
搜了网数据特性店铺商品全量覆盖支持获取店铺在售、预售、定制款等全状态商品区别于仅展示热销商品的通用搜索接口运营属性联动返回商品的店铺分类、推荐优先级、促销标签等运营数据适配店铺商品页的精细化展示需求多品类适配兼容同时支持工业品、农产品、日用百货等品类的商品数据结构无需单独开发适配逻辑数据实时性强商品上架、价格调整、库存更新等动态数据5 分钟内同步保障店铺商品列表的时效性。
典型应用场景商家店铺聚合页嵌入自有平台展示指定店铺的全品类商品支持按品类、价格筛选提升用户采购效率供应商商品台账系统批量采集合作店铺的商品数据建立商品台账跟踪商品价格与库存变化店铺选品分析工具分析竞品店铺的商品结构、价格带分布、热销商品辅助自身选品与定价决策采购需求匹配系统基于店铺商品列表匹配企业采购需求推荐符合条件的供应商商品。
核心参数与返回字段1请求参数GET/POST 提交需签名认证参数类型参数名称类型是否必填说明应用示例公共参数app_keystring是应用唯一标识开放平台获取soule_appkey_2026_abc123app_secretstring是应用秘钥签名核心需保密soule_secret_2026_def456methodstring是接口名称固定为soule.item_search_shopsoule.item_search_shopformatstring否响应格式默认 JSONjson/xmltimestampstring是秒级时间戳与服务器时差≤5 分钟1735689600vstring是接口版本固定为
2.
0
0业务参数shop_idstring是店铺唯一 IDSLSHOP20260201001cate_idstring否店铺内部分类编码203005阀门类price_minfloat否最低价格元 / 单位100price_maxfloat否最高价格元 / 单位5000stock_statusint否库存状态0 不限1 现货2 预售3 缺货1sort_typestring否排序方式默认publish_time_descprice_asc/sales_desc/stock_descpage_numint否页码默认 12page_sizeint否单页条数默认 20最大 5050
注意事项shop_id 可通过 seller_detail 接口或搜了网店铺主页 URL 提取格式为SLSHOP日期序号timestamp 需调用搜了网 soule.time.get 接口同步避免时间误差导致签名失败签名生成需包含所有非空参数排除app_secret且参数名按 ASCII 升序排序参数缺失或排序错误会直接触发认证失败。
2返回核心字段按业务分类字段分类核心字段说明商品基础标识item_id、item_title、brand、spec、item_imgitem_id为调用item_get接口的唯一凭证价格与库存信息price_retail、price_wholesale、step_price、stock、stock_statusstep_price阶梯报价JSON 格式stock_status1 现货 / 2 预售 / 3 缺货店铺运营属性shop_cate_name、recommend_level、promotion_tagrecommend_level店铺推荐优先级
级promotion_tag促销 / 新品 / 爆款商品状态信息on_sale、publish_time、update_timeon_sale是否在售true/falseupdate_time数据最后更新时间分页信息total、page_num、page_size、has_nexttotal店铺符合条件的商品总数has_next是否有下一页提示该接口不返回商家详情信息如需获取店铺名称、信用等级、联系方式等数据需联动调用 seller_detail 接口。
接口限制与
注意事项权限类型日调用上限调用频率适用场景个人测试权限50 次 / 天1 次 / 秒功能调试、单个店铺商品查询企业基础权限500 次 / 天3 次 / 秒中小型采购商、经销商店铺选品企业高级权限5000 次 / 天10 次 / 秒大型供应链平台、电商聚合系统数据缓存规则店铺商品列表数据缓存15 分钟短时间内重复调用同一shop_id 筛选条件会返回缓存数据店铺权限限制部分品牌旗舰店的商品数据仅对授权合作方开放无权限时返回 403 错误调用频率限制超出频率上限会触发临时封禁 10 分钟多次超限会导致权限降级合规要求数据仅可用于企业内部采购决策或自有平台展示严禁转售、篡改或用于恶意竞品分析违反协议会被永久封禁账号。
对接前准备权限与环境搭建
获取接口权限官方唯一合规路径搜了网 item_search_shop 接口权限需通过搜了网开放平台申请步骤如下注册开发者账号选择个人开发者或企业开发者填写基本信息并完成实名认证提交资质审核企业用户上传营业执照、企业征信报告如有、法人身份证个人用户上传身份证填写应用用途如 “个人店铺商品检索工具”创建应用填写应用名称、服务器 IP 白名单、数据用途说明提交审核
个工作日完成获取密钥审核通过后在 “应用管理 - 密钥管理” 中获取app_key和app_secret申请接口权限在 “权限管理” 中选择soule.item_search_shop接口提交申请基础权限即时开通高级权限需额外提交《数据合规使用承诺书》。
风险提示严禁通过爬虫、抓包等非官方方式获取店铺商品数据违反协议会承担相应法律责任。
技术环境准备1支持语言与协议协议HTTPS强制HTTP 请求会被直接拦截并返回 403 错误开发语言Python、Java、PHP、Go 等主流语言均可推荐 Python代码简洁适配异步并发与数据解析。
2必备工具与依赖工具类型推荐工具用途调试工具搜了网开放平台调试工具在线输入参数、生成签名、测试接口响应Postman模拟 GET/POST 请求保存不同店铺的测试用例开发依赖Pythonrequests发送 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之前拼接参数为 key1value1key2value
.. 的字符串格式键值对用分隔将 app_secret 拼接在字符串首尾生成签名原串格式app_secret 拼接字符串 app_secret对原串进行 MD5 加密转为大写字符串即为签名 sign将 sign 添加到请求参数中发送 HTTPS GET 请求。
关键提醒搜了网接口的签名要求app_secret首尾双拼接这是与其他平台接口的核心差异需重点核对代码逻辑。
步骤 2完整代码实现含签名生成 调用 数据标准化1依赖安装bash 运行 pip install requests hashlib jsonpath-ng pandas2Python 代码实现import requests import hashlib import time import logging import pandas as pd from typing import Optional, Dict, List # 封装好API供应商demo urlhttps://console.open.onebound.cn/console/?iLex # 日志配置记录调用日志便于问题排查与审计 logging.basicConfig( levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s, handlers[logging.FileHandler(soule_item_search_shop.log), logging.StreamHandler()] ) # 配置信息替换为你的开放平台密钥 CONFIG { app_key: 你的app_key, app_secret: 你的app_secret, api_url: https://openapi.soule.com/router/rest, format: json, version:
0 } def generate_sign(params: Dict[str, str], app_secret: str) - str: 生成搜了网接口签名MD5加密大写 #
按参数名ASCII升序排序 sorted_params sorted(params.items(), keylambda x: x[0]) #
拼接为 key1value1key2value2 格式 param_str .join([f{k}{v} for k, v in sorted_params]) #
app_secret拼接首尾 MD5加密 转大写 sign_str f{app_secret}{param_str}{app_secret} sign hashlib.md5(sign_str.encode(utf-
).hexdigest().upper() return sign def standardize_shop_product(raw_product: Dict) - Dict: 标准化店铺商品数据统一输出格式 # 处理库存状态 stock_status raw_product.get(stock_status,
stock_status_desc { 1: 现货, 2: 预售, 3: 缺货, 0: 不限 }.get(stock_status, 未知) # 处理价格信息 price_retail raw_product.get(price_retail,
0.
price_wholesale raw_product.get(price_wholesale,
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 无阶梯报价 # 处理运营属性 recommend_level raw_product.get(recommend_level,
promotion_tag raw_product.get(promotion_tag, ) promotion_desc promotion_tag if promotion_tag else 无 return { 商品ID: raw_product.get(item_id, ), 商品名称: raw_product.get(item_title, ), 品牌: raw_product.get(brand, 无品牌), 规格参数: raw_product.get(spec, 暂无), 零售价(元/单位): price_retail, 批发价(元/单位): price_wholesale, 阶梯报价: step_price_desc, 库存数量: raw_product.get(stock,
, 库存状态: stock_status_desc, 店铺分类: raw_product.get(shop_cate_name, 暂无), 店铺推荐等级: f{recommend_level}级, 促销标签: promotion_desc, 是否在售: 是 if raw_product.get(on_sale) else 否, 上架时间: raw_product.get(publish_time, 暂无), 数据更新时间: raw_product.get(update_time, 暂无), 请求时间: time.strftime(%Y-%m-%d %H:%M:%S, time.localtime()) } def soule_item_search_shop( shop_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接口获取店铺商品列表 #
校验必填参数 if not shop_id: return {success: False, error_msg: shop_id不能为空, data: [], pagination: {}} if not CONFIG[app_key] or not CONFIG[app_secret]: return {success: False, error_msg: app_key或app_secret未配置, data: [], pagination: {}} #
构建公共参数 params { app_key: CONFIG[app_key], method: soule.item_search_shop, format: CONFIG[format], v: CONFIG[version], timestamp: str(int(time.time())), shop_id: shop_id, stock_status: str(stock_status), sort_type: sort_type, page_num: str(page_num), page_size: str(min(page_size,
) # 限制最大条数为50 } #
添加工业务参数 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) #
生成签名 sign generate_sign(params, CONFIG[app_secret]) params[sign] sign try: #
发送HTTPS请求 response requests.get( urlCONFIG[api_url], paramsparams, timeout15, verifyTrue # 生产环境必须开启证书验证 ) response.raise_for_status() # 抛出HTTP状态码异常 result response.json() #
解析响应结果 if result.get(code) ! 200: error_msg f[{result.get(code, 未知错误)}] {result.get(msg, 无错误信息)} logging.error(f获取店铺商品失败店铺ID{shop_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,
, 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{shop_id}) return {success: True, error_msg: , data: [], pagination: pagination} #
标准化数据 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{shop_id}{str(e)}) return {success: False, error_msg: f网络异常{str(e)}, data: [], pagination: {}} except Exception as e: logging.error(f数据解析异常店铺ID{shop_id}{str(e)}) return {success: False, error_msg: f解析异常{str(e)}, data: [], pagination: {}} # 封装好API供应商demo urlhttps://console.open.onebound.cn/console/?iLex # 调用示例 if __name__ __main__: # 示例获取指定店铺现货商品价格
元按销量排序 target_shop_id SLSHOP20260201001 cate_id 203005 # 店铺内阀门分类 price_min
1
0 price_max
5
0 stock_status 1 # 仅现货 sort_type sales_desc # 销量优先 result soule_item_search_shop( shop_idtarget_shop_id, cate_idcate_id, price_minprice_min, price_maxprice_max, stock_statusstock_status, sort_typesort_type, page_size20 ) if result[success]: print(f获取成功店铺 {target_shop_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_shop_id}.xlsx, indexFalse) # 翻页示例 if result[pagination][has_next]: next_page_result soule_item_search_shop( shop_idtarget_shop_id, cate_idcate_id, price_minprice_min, price_maxprice_max, stock_statusstock_status, sort_typesort_type, page_num2, page_size20 ) print(f下一页获取到 {len(next_page_result[data])} 件商品) else: print(f获取失败{result[error_msg]})
调试与问题排查快速解决对接异常
优先用官方工具调试排除签名与参数问题登录搜了网开放平台调试工具选择soule.item_search_shop接口输入shop_id、cate_id、price_min等参数点击 “生成签名” 并发送请求若官方工具调用成功 → 问题出在代码的签名生成逻辑或参数拼接错误如app_secret未首尾拼接、数值参数未转字符串若官方工具调用失败 → 问题出在权限配置或参数有效性如shop_id错误、IP 未加入白名单、无店铺数据访问权限。
高频问题排查表问题现象常见原因解决方案签名验证失败
app_key/app_secret 错误或过期
参数未按 ASCII 升序排序
app_secret 未首尾拼接
timestamp 与服务器时差 5 分钟
核对开放平台密钥信息过期则重新申请
严格按参数名 ASCII 升序排序所有非空参数
修正签名逻辑确保 app_secret 首尾双拼接
调用 soule.time.get 接口同步服务器时间权限不足
未申请 item_search_shop 接口权限
服务器 IP 不在白名单
调用频率超限
店铺为品牌旗舰店且无授权
在开放平台 “权限管理” 中申请接口
添加服务器公网 IP 到应用白名单
降低调用频率控制并发数≤权限上限
联系店铺或平台申请授权访问参数错误
shop_id 为空或格式非法
price_min price_max
cate_id 非店铺内有效分类编码
page_size 超过
确保传入有效的 shop_id格式为SLSHOP日期序号
校验价格区间确保下限≤上限
通过店铺主页获取有效分类编码
将 page_size 限制在 50 以内无商品数据返回200 但 data 为空
店铺无符合筛选条件的商品
店铺已下架所有商品或被封禁
stock_status 设置为 1 但店铺无现货
放宽筛选条件如 stock_status 设为
扩大价格区间
验证 shop_id 对应的店铺是否正常运营
更换 stock_status 参数值重新测试响应超时
网络波动或服务器负载高
page_size 设置过大如 50且店铺商品数量多
高峰期调用工作日 9:
:00/14:
:
添加重试机制设置超时时间为 15 秒
减小 page_size如改为 20分批次获取数据
避开高峰期调用调度到凌晨低峰期
进阶优化生产级稳定性提升
性能与配额优化批量店铺查询优化多店铺商品查询时采用异步并发框架如 Python 的aiohttp并发数严格控制在权限允许的频率上限内如企业基础权限 3 次 / 秒为不同店铺的请求设置独立的请求队列避免单店铺请求阻塞整体流程。
分层缓存策略用 Redis 构建二级缓存体系降低接口调用频率一级缓存缓存店铺 筛选条件的商品列表key 为soule_shop_search_店铺ID_分类ID_价格区间_库存状态缓存时间 15 分钟二级缓存缓存单个商品详情复用item_get接口的缓存key 为soule_item_商品ID缓存时间 30 分钟缓存主动失效当监测到店铺有商品上新或价格调整时主动删除对应店铺的一级缓存。
请求参数优化前端筛选组件增加参数合法性校验例如限制price_min≥
page_num≥1对高频筛选条件如现货、价格区间做预设选项减少无效请求。
数据质量优化数据清洗与去重按item_id去重避免同一商品因筛选条件不同重复出现在列表中过滤异常数据如价格≤
库存≤0 且状态为现货的商品统一字段格式如价格保留 2 位小数上架时间统一为YYYY-MM-DD HH:MM:SS格式缺失值填充如无品牌的商品填充为 “无品牌”无促销标签的填充为 “无”。
多维度数据增强联动item_get接口补充商品参数、交易政策等信息联动seller_detail接口补充店铺名称、信用等级等信息提升数据的完整性。
合规与安全优化密钥与权限管理生产环境禁止硬编码密钥将app_key和app_secret存入配置中心如 Nacos、Apollo应用启动时通过加密通道拉取为不同环境测试 / 生产配置不同的开发者账号避免测试环境密钥泄露影响生产定期轮换app_secret建议每 3 个月一次并同步更新配置中心的密钥信息。
熔断与降级机制引入熔断器如pybreaker当接口连续失败次数≥5 次时触发熔断暂停调用 5 分钟熔断期间返回缓存数据或友好提示对非核心业务如店铺商品推荐设置降级策略当接口调用压力过大时关闭该功能优先保障核心的商品检索功能。
日志与审计记录每次调用的shop_id、筛选条件、响应状态、耗时、返回数据量等信息日志保留至少 30 天定期审计日志排查异常调用行为。