搜了网 item_search_shop - 获得店铺的所有商品接口对接全攻略：从入门到精通

1. 接口定位与核心价值

• 核心功能：输入shop_id、品类编码、价格区间、库存状态、上架时间等筛选条件，返回指定店铺的分页商品列表；支持按价格、销量、上架时间、库存深度等维度排序，单页最大返回 50 条数据；可联动 seller_detail 接口获取店铺资质、item_get 接口获取商品详情，形成 “店铺洞察 - 商品检索 - 详情分析” 的完整链路。
• 搜了网数据特性
• 店铺商品全量覆盖：支持获取店铺在售、预售、定制款等全状态商品，区别于仅展示热销商品的通用搜索接口；
• 运营属性联动：返回商品的店铺分类、推荐优先级、促销标签等运营数据，适配店铺商品页的精细化展示需求；
• 多品类适配兼容：同时支持工业品、农产品、日用百货等品类的商品数据结构，无需单独开发适配逻辑；
• 数据实时性强：商品上架、价格调整、库存更新等动态数据5 分钟内同步，保障店铺商品列表的时效性。
• 典型应用场景

1. 商家店铺聚合页：嵌入自有平台，展示指定店铺的全品类商品，支持按品类、价格筛选，提升用户采购效率；
2. 供应商商品台账系统：批量采集合作店铺的商品数据，建立商品台账，跟踪商品价格与库存变化；
3. 店铺选品分析工具：分析竞品店铺的商品结构、价格带分布、热销商品，辅助自身选品与定价决策；
4. 采购需求匹配系统：基于店铺商品列表，匹配企业采购需求，推荐符合条件的供应商商品。

2. 核心参数与返回字段

（1）请求参数（GET/POST 提交，需签名认证）

注意事项

1. shop_id 可通过 seller_detail 接口或搜了网店铺主页 URL 提取，格式为SLSHOP+日期+序号；
2. timestamp 需调用搜了网 soule.time.get 接口同步，避免时间误差导致签名失败；
3. 签名生成需包含所有非空参数（排除app_secret），且参数名按 ASCII 升序排序，参数缺失或排序错误会直接触发认证失败。

（2）返回核心字段（按业务分类）

提示：该接口不返回商家详情信息，如需获取店铺名称、信用等级、联系方式等数据，需联动调用 seller_detail 接口。

3. 接口限制与注意事项

• 合规要求：数据仅可用于企业内部采购决策或自有平台展示，严禁转售、篡改或用于恶意竞品分析，违反协议会被永久封禁账号。二、对接前准备：权限与环境搭建

1. 获取接口权限（官方唯一合规路径）

1. 注册开发者账号：选择个人开发者或企业开发者，填写基本信息并完成实名认证；
2. 提交资质审核：

• 企业用户：上传营业执照、企业征信报告（如有）、法人身份证；
• 个人用户：上传身份证，填写应用用途（如 “个人店铺商品检索工具”）；

1. 创建应用：填写应用名称、服务器 IP 白名单、数据用途说明，提交审核（1-2 个工作日完成）；
2. 获取密钥：审核通过后，在 “应用管理 - 密钥管理” 中获取app_key和app_secret；
3. 申请接口权限：在 “权限管理” 中选择soule.item_search_shop接口，提交申请，基础权限即时开通，高级权限需额外提交《数据合规使用承诺书》。

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

2. 技术环境准备

（1）支持语言与协议

• 协议：HTTPS（强制），HTTP 请求会被直接拦截并返回 403 错误；
• 开发语言：Python、Java、PHP、Go 等主流语言均可，推荐 Python（代码简洁，适配异步并发与数据解析）。

（2）必备工具与依赖

步骤 1：理解签名认证规则（核心，必掌握）

1. 收集所有非空请求参数（含公共参数和业务参数，排除 app_secret）；
2. 按参数名ASCII 升序排序（如app_key排在cate_id之前）；
3. 拼接参数为 key1=value1&key2=value2... 的字符串格式（键值对用&分隔）；
4. 将 app_secret 拼接在字符串首尾，生成签名原串（格式：app_secret + 拼接字符串 + app_secret）；
5. 对原串进行 MD5 加密，转为大写字符串，即为签名 sign；
6. 将 sign 添加到请求参数中，发送 HTTPS GET 请求。

关键提醒：搜了网接口的签名要求app_secret首尾双拼接，这是与其他平台接口的核心差异，需重点核对代码逻辑。

步骤 2：完整代码实现（含签名生成 + 调用 + 数据标准化）

（1）依赖安装

（2）Python 代码实现

import requests
import hashlib
import time
import logging
import pandas as pd
from typing import Optional, Dict, List
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 日志配置：记录调用日志，便于问题排查与审计
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": {}}
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 调用示例
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. 优先用官方工具调试（排除签名与参数问题）

1. 登录搜了网开放平台调试工具，选择 soule.item_search_shop 接口；

2. 输入shop_id、cate_id、price_min等参数，点击 “生成签名” 并发送请求；

3. 若官方工具调用成功 → 问题出在代码的签名生成逻辑或参数拼接错误（如app_secret未首尾拼接、数值参数未转字符串）；

4. 若官方工具调用失败 → 问题出在权限配置或参数有效性（如shop_id错误、IP 未加入白名单、无店铺数据访问权限）。

2. 高频问题排查表

五、进阶优化：生产级稳定性提升

1. 性能与配额优化

• 批量店铺查询优化：多店铺商品查询时，采用 异步并发框架（如 Python 的aiohttp），并发数严格控制在权限允许的频率上限内（如企业基础权限 3 次 / 秒）；为不同店铺的请求设置独立的请求队列，避免单店铺请求阻塞整体流程。

• 分层缓存策略：用 Redis 构建二级缓存体系，降低接口调用频率：

• 一级缓存：缓存店铺 + 筛选条件的商品列表，key 为 soule_shop_search_店铺ID_分类ID_价格区间_库存状态，缓存时间 15 分钟；

• 二级缓存：缓存单个商品详情（复用item_get接口的缓存），key 为 soule_item_商品ID，缓存时间 30 分钟；

  缓存主动失效：当监测到店铺有商品上新或价格调整时，主动删除对应店铺的一级缓存。

• 请求参数优化：前端筛选组件增加参数合法性校验，例如限制price_min≥0、page_num≥1；对高频筛选条件（如现货、价格区间）做预设选项，减少无效请求。

2. 数据质量优化

• 数据清洗与去重：

1. 按item_id去重，避免同一商品因筛选条件不同重复出现在列表中；

2. 过滤异常数据（如价格≤0、库存≤0 且状态为现货的商品）；

3. 统一字段格式（如价格保留 2 位小数，上架时间统一为YYYY-MM-DD HH:MM:SS格式）；

4. 缺失值填充（如无品牌的商品填充为 “无品牌”，无促销标签的填充为 “无”）。

• 多维度数据增强：联动item_get接口补充商品参数、交易政策等信息，联动seller_detail接口补充店铺名称、信用等级等信息，提升数据的完整性。

3. 合规与安全优化

• 密钥与权限管理：

1. 生产环境禁止硬编码密钥，将app_key和app_secret存入配置中心（如 Nacos、Apollo），应用启动时通过加密通道拉取；

2. 为不同环境（测试 / 生产）配置不同的开发者账号，避免测试环境密钥泄露影响生产；

3. 定期轮换app_secret（建议每 3 个月一次），并同步更新配置中心的密钥信息。

• 熔断与降级机制：

1. 引入熔断器（如pybreaker），当接口连续失败次数≥5 次时，触发熔断，暂停调用 5 分钟；熔断期间返回缓存数据或友好提示；

2. 对非核心业务（如店铺商品推荐）设置降级策略，当接口调用压力过大时，关闭该功能，优先保障核心的商品检索功能。

• 日志与审计：记录每次调用的shop_id、筛选条件、响应状态、耗时、返回数据量等信息，日志保留至少 30 天；定期审计日志，排查异常调用行为。

六、扩展场景：接口联动与功能升级

1. 店铺商品全景分析系统：联动 seller_detail 获取店铺资质 → item_search_shop 获取全量商品 → item_get 获取商品详情 → 分析店铺的商品结构、价格带分布、热销品类，生成店铺分析报告；

2. 供应商动态监控系统：定时调用 item_search_shop 接口，监控合作店铺的商品上新、价格调整、库存变化，当出现价格下跌或库存预警时，触发采购提醒；

3. 多店铺比价系统：同时获取多个同类店铺的商品列表，按商品名称、规格进行匹配，生成同款商品的跨店铺价格对比表，辅助采购决策；

4. 店铺商品聚合平台：整合多个优质店铺的商品数据，按品类、品牌、价格进行分类展示，搭建一站式采购商城