搜了网 item_search_shop 接口（官方标准命名 soule.item_search_shop）是面向多品类 B2B/B2C 混合交易场景的店铺商品批量检索接口，通过店铺唯一标识 shop_id 可获取指定店铺的全量商品列表，支持按品类、价格区间、库存状态、上架时间等维度筛选分页数据。该接口采用 HTTPS+AppKey+Secret+Sign 签名认证 机制，支持 JSON/XML 双格式返回，具备店铺商品全覆盖、筛选维度灵活、数据与店铺运营状态联动的特点，是构建商家店铺商品聚合页、供应商商品台账、店铺选品分析系统的核心工具。本攻略提供从接口认知、权限准备、实操对接、调试排错到生产级优化的全链路标准化指导。
一、接口核心认知：功能与适配场景

1. 接口定位与核心价值

核心功能：输入shop_id、品类编码、价格区间、库存状态、上架时间等筛选条件，返回指定店铺的分页商品列表；支持按价格、销量、上架时间、库存深度等维度排序，单页最大返回 50 条数据；可联动 seller_detail 接口获取店铺资质、item_get 接口获取商品详情，形成 “店铺洞察 - 商品检索 - 详情分析” 的完整链路。
搜了网数据特性
店铺商品全量覆盖：支持获取店铺在售、预售、定制款等全状态商品，区别于仅展示热销商品的通用搜索接口；
运营属性联动：返回商品的店铺分类、推荐优先级、促销标签等运营数据，适配店铺商品页的精细化展示需求；
多品类适配兼容：同时支持工业品、农产品、日用百货等品类的商品数据结构，无需单独开发适配逻辑；
数据实时性强：商品上架、价格调整、库存更新等动态数据5 分钟内同步，保障店铺商品列表的时效性。
典型应用场景
商家店铺聚合页：嵌入自有平台，展示指定店铺的全品类商品，支持按品类、价格筛选，提升用户采购效率；
供应商商品台账系统：批量采集合作店铺的商品数据，建立商品台账，跟踪商品价格与库存变化；
店铺选品分析工具：分析竞品店铺的商品结构、价格带分布、热销商品，辅助自身选品与定价决策；
采购需求匹配系统：基于店铺商品列表，匹配企业采购需求，推荐符合条件的供应商商品。

1. 核心参数与返回字段
   （1）请求参数（GET/POST 提交，需签名认证）

参数类型
参数名称
类型
是否必填
说明
应用示例
公共参数
app_key
string
是
应用唯一标识（开放平台获取）
soule_appkey_2026_abc123
app_secret
string
是
应用秘钥（签名核心，需保密）
soule_secret_2026_def456
method
string
是
接口名称，固定为soule.item_search_shop
soule.item_search_shop
format
string
否
响应格式，默认 JSON
json/xml
timestamp
string
是
秒级时间戳，与服务器时差≤5 分钟
1735689600
v
string
是
接口版本，固定为2.0
2.0
业务参数
shop_id
string
是
店铺唯一 ID
SLSHOP20260201001
cate_id
string
否
店铺内部分类编码
203005（阀门类）
price_min
float
否
最低价格（元 / 单位）
100
price_max
float
否
最高价格（元 / 单位）
5000
stock_status
int
否
库存状态（0 = 不限，1 = 现货，2 = 预售，3 = 缺货）
1
sort_type
string
否
排序方式，默认publish_time_desc
price_asc/sales_desc/stock_desc
page_num
int
否
页码，默认 1
2
page_size
int
否
单页条数，默认 20，最大 50
50
注意事项
shop_id 可通过 seller_detail 接口或搜了网店铺主页 URL 提取，格式为SLSHOP+日期+序号；
timestamp 需调用搜了网 soule.time.get 接口同步，避免时间误差导致签名失败；
签名生成需包含所有非空参数（排除app_secret），且参数名按 ASCII 升序排序，参数缺失或排序错误会直接触发认证失败。
（2）返回核心字段（按业务分类）
字段分类
核心字段
说明
商品基础标识
item_id、item_title、brand、spec、item_img
item_id为调用item_get接口的唯一凭证
价格与库存信息
price_retail、price_wholesale、step_price、stock、stock_status
step_price：阶梯报价（JSON 格式）；stock_status：1 = 现货 / 2 = 预售 / 3 = 缺货
店铺运营属性
shop_cate_name、recommend_level、promotion_tag
recommend_level：店铺推荐优先级（1-5 级）；promotion_tag：促销 / 新品 / 爆款
商品状态信息
on_sale、publish_time、update_time
on_sale：是否在售（true/false）；update_time：数据最后更新时间
分页信息
total、page_num、page_size、has_next
total：店铺符合条件的商品总数；has_next：是否有下一页
提示：该接口不返回商家详情信息，如需获取店铺名称、信用等级、联系方式等数据，需联动调用 seller_detail 接口。

1. 接口限制与注意事项
   权限类型
   日调用上限
   调用频率
   适用场景
   个人测试权限
   50 次 / 天
   1 次 / 秒
   功能调试、单个店铺商品查询
   企业基础权限
   500 次 / 天
   3 次 / 秒
   中小型采购商、经销商店铺选品
   企业高级权限
   5000 次 / 天
   10 次 / 秒
   大型供应链平台、电商聚合系统
   数据缓存规则：店铺商品列表数据缓存15 分钟，短时间内重复调用同一shop_id+ 筛选条件会返回缓存数据；
   店铺权限限制：部分品牌旗舰店的商品数据仅对授权合作方开放，无权限时返回 403 错误；
   调用频率限制：超出频率上限会触发临时封禁 10 分钟，多次超限会导致权限降级；
   合规要求：数据仅可用于企业内部采购决策或自有平台展示，严禁转售、篡改或用于恶意竞品分析，违反协议会被永久封禁账号。
   二、对接前准备：权限与环境搭建

2. 获取接口权限（官方唯一合规路径）
   搜了网 item_search_shop 接口权限需通过搜了网开放平台（https://open.soule.com）申请，步骤如下：
   注册开发者账号：选择个人开发者或企业开发者，填写基本信息并完成实名认证；
   提交资质审核：
   企业用户：上传营业执照、企业征信报告（如有）、法人身份证；
   个人用户：上传身份证，填写应用用途（如 “个人店铺商品检索工具”）；
   创建应用：填写应用名称、服务器 IP 白名单、数据用途说明，提交审核（1-2 个工作日完成）；
   获取密钥：审核通过后，在 “应用管理 - 密钥管理” 中获取app_key和app_secret；
   申请接口权限：在 “权限管理” 中选择soule.item_search_shop接口，提交申请，基础权限即时开通，高级权限需额外提交《数据合规使用承诺书》。

   风险提示：严禁通过爬虫、抓包等非官方方式获取店铺商品数据，违反协议会承担相应法律责任。

3. 技术环境准备
   （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之前）；
拼接参数为 key1=value1&key2=value2... 的字符串格式（键值对用&分隔）；
将 app_secret 拼接在字符串首尾，生成签名原串（格式：app_secret + 拼接字符串 + app_secret）；
对原串进行 MD5 加密，转为大写字符串，即为签名 sign；
将 sign 添加到请求参数中，发送 HTTPS GET 请求。

关键提醒：搜了网接口的签名要求app_secret首尾双拼接，这是与其他平台接口的核心差异，需重点核对代码逻辑。
步骤 2：完整代码实现（含签名生成 + 调用 + 数据标准化）

（1）依赖安装
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("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": "2.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. 拼接为 key1=value1&key2=value2 格式
param_str = "&".join([f"{k}={v}" for k, v in sorted_params])
# 3. app_secret拼接首尾 + MD5加密 + 转大写
sign_str = f"{app_secret}{param_str}{app_secret}"
sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()
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_retail = raw_product.get("price_retail", 0.0)
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 "无阶梯报价"

# 处理运营属性
recommend_level = raw_product.get("recommend_level", 0)
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", 0),
    "库存状态": 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接口获取店铺商品列表"""

# 1. 校验必填参数
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": {}}

# 2. 构建公共参数
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))  # 限制最大条数为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：{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", 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：{shop_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：{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": {}}

调用示例

if name == "main":

# 示例：获取指定店铺现货商品，价格100-5000元，按销量排序
target_shop_id = "SLSHOP20260201001"
cate_id = "203005"  # 店铺内阀门分类
price_min = 100.0
price_max = 5000.0
stock_status = 1  # 仅现货
sort_type = "sales_desc"  # 销量优先

result = soule_item_search_shop(
    shop_id=target_shop_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_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", index=False)
    # 翻页示例
    if result["pagination"]["has_next"]:
        next_page_result = soule_item_search_shop(
            shop_id=target_shop_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']}")

四、调试与问题排查：快速解决对接异常

1. 优先用官方工具调试（排除签名与参数问题）
   登录搜了网开放平台调试工具，选择 soule.item_search_shop 接口；
   输入shop_id、cate_id、price_min等参数，点击 “生成签名” 并发送请求；
   若官方工具调用成功 → 问题出在代码的签名生成逻辑或参数拼接错误（如app_secret未首尾拼接、数值参数未转字符串）；
   若官方工具调用失败 → 问题出在权限配置或参数有效性（如shop_id错误、IP 未加入白名单、无店铺数据访问权限）。
2. 高频问题排查表
   问题现象 常见原因 解决方案
   签名验证失败（401） 1. app_key/app_secret 错误或过期；
3. 参数未按 ASCII 升序排序；
4. app_secret 未首尾拼接；
5. timestamp 与服务器时差 > 5 分钟 1. 核对开放平台密钥信息，过期则重新申请；
6. 严格按参数名 ASCII 升序排序所有非空参数；
7. 修正签名逻辑，确保 app_secret 首尾双拼接；
8. 调用 soule.time.get 接口同步服务器时间
   权限不足（403） 1. 未申请 item_search_shop 接口权限；
9. 服务器 IP 不在白名单；
10. 调用频率超限；
11. 店铺为品牌旗舰店且无授权 1. 在开放平台 “权限管理” 中申请接口；
12. 添加服务器公网 IP 到应用白名单；
13. 降低调用频率，控制并发数≤权限上限；
14. 联系店铺或平台申请授权访问
    参数错误（400） 1. shop_id 为空或格式非法；
15. price_min > price_max；
16. cate_id 非店铺内有效分类编码；
17. page_size 超过 50 1. 确保传入有效的 shop_id，格式为SLSHOP+日期+序号；
18. 校验价格区间，确保下限≤上限；
19. 通过店铺主页获取有效分类编码；
20. 将 page_size 限制在 50 以内
    无商品数据返回（200 但 data 为空） 1. 店铺无符合筛选条件的商品；
21. 店铺已下架所有商品或被封禁；
22. stock_status 设置为 1 但店铺无现货 1. 放宽筛选条件（如 stock_status 设为 0、扩大价格区间）；
23. 验证 shop_id 对应的店铺是否正常运营；
24. 更换 stock_status 参数值重新测试
    响应超时（504） 1. 网络波动或服务器负载高；
25. page_size 设置过大（如 50）且店铺商品数量多；
26. 高峰期调用（工作日 9:00-12:00/14:00-18:00） 1. 添加重试机制，设置超时时间为 15 秒；
27. 减小 page_size（如改为 20），分批次获取数据；
28. 避开高峰期调用，调度到凌晨低峰期
    五、进阶优化：生产级稳定性提升
29. 性能与配额优化
    批量店铺查询优化：多店铺商品查询时，采用 异步并发框架（如 Python 的aiohttp），并发数严格控制在权限允许的频率上限内（如企业基础权限 3 次 / 秒）；为不同店铺的请求设置独立的请求队列，避免单店铺请求阻塞整体流程。
    分层缓存策略：用 Redis 构建二级缓存体系，降低接口调用频率：
    一级缓存：缓存店铺 + 筛选条件的商品列表，key 为 soule_shopsearch店铺ID分类ID价格区间_库存状态，缓存时间 15 分钟；
    二级缓存：缓存单个商品详情（复用item_get接口的缓存），key 为 souleitem商品ID，缓存时间 30 分钟；
    缓存主动失效：当监测到店铺有商品上新或价格调整时，主动删除对应店铺的一级缓存。
    请求参数优化：前端筛选组件增加参数合法性校验，例如限制price_min≥0、page_num≥1；对高频筛选条件（如现货、价格区间）做预设选项，减少无效请求。
30. 数据质量优化
    数据清洗与去重：
    按item_id去重，避免同一商品因筛选条件不同重复出现在列表中；
    过滤异常数据（如价格≤0、库存≤0 且状态为现货的商品）；
    统一字段格式（如价格保留 2 位小数，上架时间统一为YYYY-MM-DD HH:MM:SS格式）；
    缺失值填充（如无品牌的商品填充为 “无品牌”，无促销标签的填充为 “无”）。
    多维度数据增强：联动item_get接口补充商品参数、交易政策等信息，联动seller_detail接口补充店铺名称、信用等级等信息，提升数据的完整性。
31. 合规与安全优化
    密钥与权限管理：
    生产环境禁止硬编码密钥，将app_key和app_secret存入配置中心（如 Nacos、Apollo），应用启动时通过加密通道拉取；
    为不同环境（测试 / 生产）配置不同的开发者账号，避免测试环境密钥泄露影响生产；
    定期轮换app_secret（建议每 3 个月一次），并同步更新配置中心的密钥信息。
    熔断与降级机制：
    引入熔断器（如pybreaker），当接口连续失败次数≥5 次时，触发熔断，暂停调用 5 分钟；熔断期间返回缓存数据或友好提示；
    对非核心业务（如店铺商品推荐）设置降级策略，当接口调用压力过大时，关闭该功能，优先保障核心的商品检索功能。
    日志与审计：记录每次调用的shop_id、筛选条件、响应状态、耗时、返回数据量等信息，日志保留至少 30 天；定期审计日志，排查异常调用行为。
    六、扩展场景：接口联动与功能升级
    店铺商品全景分析系统：联动 seller_detail 获取店铺资质 → item_search_shop 获取全量商品 → item_get 获取商品详情 → 分析店铺的商品结构、价格带分布、热销品类，生成店铺分析报告；
    供应商动态监控系统：定时调用 item_search_shop 接口，监控合作店铺的商品上新、价格调整、库存变化，当出现价格下跌或库存预警时，触发采购提醒；
    多店铺比价系统：同时获取多个同类店铺的商品列表，按商品名称、规格进行匹配，生成同款商品的跨店铺价格对比表，辅助采购决策；
    店铺商品聚合平台：整合多个优质店铺的商品数据，按品类、品牌、价格进行分类展示，搭建一站式采购商城