找商网 item_search_shop - 获得公司的所有商品接口对接全攻略：从入门到精通

一、接口核心认知：功能与适配场景

1. 接口定位与核心价值

• 核心功能：输入seller_id、品类编码、价格区间、库存状态、上架时间等筛选条件，返回指定企业的分页商品列表；支持按价格、销量、产能、上架时间等维度排序，单页最大返回 50 条数据；可联动 seller_info 接口获取企业资质、item_get 接口获取商品详情，形成 “企业洞察 - 商品检索 - 详情分析” 的 B2B 采购完整链路。

• 找商网数据特性

• 企业商品全量覆盖：支持获取企业在售、预售、定制款等全状态商品，区别于仅展示热销商品的通用搜索接口，适配供应商全品类商品梳理需求；

• 供应能力属性联动：返回商品的最小起订量、月产能、交货周期等供应数据，直接关联企业生产能力，辅助采购方评估供货稳定性；

• 工业品属性适配：商品列表字段包含材质、执行标准等工业品专属属性，无需额外接口调用即可获取核心采购决策信息；

• 数据实时性强：商品上架、价格调整、库存更新等动态数据5 分钟内同步，保障企业商品列表的时效性。

• 典型应用场景

1. 供应商商品台账系统：批量采集合作企业的商品数据，建立动态商品台账，跟踪商品价格、库存与供应能力变化；

2. 企业店铺聚合页：嵌入自有采购平台，展示指定供应商的全品类商品，支持按品类、价格筛选，提升采购对接效率；

3. 竞品分析工具：获取竞品企业的商品结构、价格带分布、热销品类，辅助自身产品定价与选品决策；

4. 采购需求匹配系统：基于企业商品列表，匹配采购方的品类、规格需求，智能推荐优质供应商商品。

2. 核心参数与返回字段

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

注意事项

1. seller_id 可通过 seller_info 接口或找商网企业店铺主页 URL 提取，格式为ZSS+日期+序号；

2. timestamp 需调用找商网 zhaoshang.time.get 接口同步，避免时间误差导致签名失败；

3. 签名生成需包含所有非空参数（排除app_secret），参数名按 ASCII 升序排序，参数缺失或排序错误会直接触发认证失败。

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

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

3. 接口限制与注意事项

• 数据缓存规则：企业商品列表数据缓存15 分钟，短时间内重复调用同一seller_id+ 筛选条件会返回缓存数据；

• 企业权限限制：部分品牌厂家的商品数据仅对授权合作方开放，无权限时返回 403 错误；

• 调用频率限制：超出频率上限会触发临时封禁 10 分钟，多次超限会导致权限降级；

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

二、对接前准备：权限与环境搭建

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

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

2. 提交资质审核：

• 企业用户：上传营业执照、工业品采购备案证明（如有）、法人身份证；

• 个人用户：上传身份证，填写应用用途（如 “个人供应商商品检索工具”）；

3. 创建应用：填写应用名称、服务器 IP 白名单、数据用途说明，提交审核（1-2 个工作日完成）；

4. 获取密钥：审核通过后，在 “应用管理 - 密钥管理” 中获取app_key和app_secret；

5. 申请接口权限：在 “权限管理” 中选择zhaoshang.item_search_shop接口，提交申请，基础权限即时开通，高级权限需额外提交《数据合规使用承诺书》。

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

2. 技术环境准备

（1）支持语言与协议

• 协议：HTTPS（强制），HTTP 请求会被直接拦截并返回 403 错误；

• 开发语言：Python、Java、PHP、Go 等主流语言均可，推荐 Python（代码简洁，适配异步并发与数据解析）。

（2）必备工具与依赖

三、实操步骤：接口对接全流程（Python 示例）

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

1. 收集所有非空请求参数（含公共参数和业务参数，排除app_secret）；

2. 按参数名ASCII 升序排序（如app_key排在cate_id之前）；

3. 拼接参数为 key1value1key2value2... 的字符串格式（无分隔符，参数值需与传入一致）；

4. 将 app_secret 拼接在字符串末尾，生成签名原串（格式：拼接参数串 + app_secret）；

5. 对原串进行 MD5 加密，转为小写字符串，即为签名 sign；

6. 将 sign 添加到请求参数中，发送 HTTPS GET 请求。

关键提醒：找商网接口签名为无分隔符拼接 + MD5 小写，与部分平台的key=value&拼接格式不同，需重点核对代码逻辑。

步骤 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("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": {}}
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 调用示例
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']}")

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

1. 优先用官方工具调试（排除签名与参数问题）

1. 登录找商网开放平台调试工具，选择 zhaoshang.item_search_shop 接口；

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

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

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

2. 高频问题排查表

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

1. 性能与配额优化

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

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

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

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

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

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

2. 数据质量优化

• 数据清洗与去重：

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

2. 过滤异常数据（如价格≤0、最小起订量≤0 且状态为现货的商品）；

3. 统一字段格式（如价格保留 2 位小数，交货周期统一为 “X 个工作日” 格式）；

4. 缺失值填充（如无品牌的商品填充为 “无品牌”，无月产能的填充为 “未知”）。

• 多维度数据增强：联动item_get接口补充商品技术参数、交易保障等信息，联动seller_info接口补充企业名称、信用等级等信息，提升数据的完整性和可用性。

3. 合规与安全优化

• 密钥与权限管理：

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

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

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

• 熔断与降级机制：

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

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

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

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

1. 企业商品全景分析系统：联动 seller_info 获取企业资质 → item_search_shop 获取全量商品 → item_get 获取商品详情 → 分析企业的商品结构、价格带分布、供应能力，生成企业供应能力评估报告；

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

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

4. 供应商准入评估系统：结合企业商品的品类覆盖度、价格竞争力、供应稳定性数据，构建供应商准入评分模型，自动化完成供应商准入审核。