万邦api博客

苏宁商品详情接口开发实践：参数组结构化解析与异常码拦截方案

Thu, 15 Oct 2026 13:44:56 +0800

前言

苏宁开放平台商品详情接口和多数电商接口有明显区别：返回数据嵌套层级多，商品参数为多组循环数组，同时接口采用独立异常码体系。常规直接取 JSON 字段的写法，很容易出现规格参数入库困难、活动价与日常价混淆、接口异常漏判问题。本文不只是简单演示接口调用，重点封装一套参数结构化解析、异常码拦截、自动重试的工具类，适合商品数据同步、比价业务场景。

前置准备

Python3 环境，依赖 requests 库。调用苏宁云台 API 需要提前申请 AppKey、AppSecret，请求报文需要按平台规则生成签名。接口有调用频次限制，高频请求会触发权限拦截，批量拉取需要控制请求间隔。

点击获取key和secret

完整代码示例

python
import requests
import time
import hashlib

class SuningDetailClient:
    def __init__(self, app_key, app_secret):
        self.app_key = app_key
        self.app_secret = app_secret
        self.session = requests.Session()
        self.retry_times = 2
        self.delay = 1.4

    def build_sign(self, params):
        """苏宁接口签名生成"""
        sort_str = "".join([k+params[k] for k in sorted(params.keys())])
        sign_raw = sort_str + self.app_secret
        return hashlib.md5(sign_raw.encode("utf-8")).hexdigest().upper()

    def get_item_detail(self, sku_id, supplier_code):
        """根据SKU编码获取苏宁商品详情，结构化解析参数"""
        api_url = "https://open.suning.com/api/http/sopRequest"
        req_params = {
            "appKey": self.app_key,
            "skuId": sku_id,
            "supplierCode": supplier_code
        }
        req_params["sign"] = self.build_sign(req_params)
        for i in range(self.retry_times):
            try:
                resp = self.session.post(api_url, json=req_params, timeout=12)
                time.sleep(self.delay)
                if resp.status_code != 200:
                    return {"code": resp.status_code, "data": None, "msg": "http请求失败"}
                res_json = resp.json()
                sn_body = res_json.get("sn_body", {})
                if res_json.get("sn_error"):
                    err_info = res_json["sn_error"]
                    return {"code":-1, "data":None, "msg":f"{err_info['error_code']}:{err_info['error_msg']}"}
                raw_detail = sn_body.get("queryItemdetail", {})
                # 商品参数数组转为键值对，方便入库
                param_map = {}
                for p in raw_detail.get("itemParameters", []):
                    param_map[p.get("parName")] = p.get("parValue")
                detail_result = {
                    "sku_id": raw_detail.get("skuId"),
                    "title": raw_detail.get("itemName", "").strip(),
                    "brand": raw_detail.get("brandName", ""),
                    "sale_price": raw_detail.get("price"),
                    "stock": raw_detail.get("invQty",0),
                    "images": [raw_detail.get(f"supplierImg{i}Url") for i in range(1,6) if raw_detail.get(f"supplierImg{i}Url")],
                    "params": param_map,
                    "is_on_sale": raw_detail.get("status") == 1
                }
                return {"code":0, "data":detail_result, "msg":"success"}
            except Exception as e:
                if i < self.retry_times -1:
                    time.sleep(2)
                    continue
                return {"code":-1, "data":None, "msg":str(e)}

if __name__ == "__main__":
    client = SuningDetailClient(app_key="your_key", app_secret="your_secret")
    ret = client.get_item_detail(sku_id="123456789", supplier_code="000000000")
    if ret["code"] ==0:
        item = ret["data"]
        print("商品名称：", item["title"])
        print("商品参数：", item["params"])
    else:
        print("查询失败：", ret["msg"])

核心逻辑解析

签名封装：实现平台 MD5 签名算法，自动排序参数生成签名，适配苏宁接口鉴权规则。
参数结构化转换：将循环的商品参数数组转为键值字典，避免嵌套数组入库麻烦，便于检索。
独立异常拦截：单独捕获 sn_error 节点，识别业务异常码，区分网络错误和业务权限错误。
失败重试：网络抖动时自动重试，减少单次调用失败造成的数据缺失。

线上踩坑要点

入参双必填：查询详情时 skuId 和 supplierCode 两个参数必须同时传入，缺少供应商编码直接返回无结果。
图片字段分散：商品图分 5 个独立字段，代码统一收集过滤空链接，避免无效图片地址入库。
状态校验：下架商品依然返回基础标题，需要 status 字段校验在售状态。
限流控制：单账号 QPS 有限制，批量同步需要做队列限速，短时间高频调用会返回权限异常码。

唯品会商品详情接口开发实践：SKU 扁平化与促销字段过滤方案

Wed, 14 Oct 2026 16:23:00 +0800

前言

在商品数据同步业务中，唯品会详情接口最大难点不是基础请求，而是嵌套多层的 SKU 规格、动态促销标签与限时价格。常规直接读取原始返回 JSON 的写法，经常出现规格数组入库困难、活动价和原价混淆、下架商品残留脏数据等问题。本文不只是简单演示接口调用，重点封装一套 SKU 扁平化、促销字段分离、异常重试的工具类，适用于商品数据同步、比价业务。

前置准备

Python3 环境，依赖 requests 库。接口存在会话校验，需要维持请求会话；平台会校验请求头，缺少 Referer 或者 UA 会直接返回数据为空。批量查询时必须增加请求间隔，高频调用会触发 IP 限流。

点击获取key和secret

完整代码示例

python

import requests
import time

class VipDetailClient:
    def __init__(self):
        self.session = requests.Session()
        self.headers = {
            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
            "Referer": "https://www.vip.com/"
        }
        self.retry_times = 2
        self.delay = 1.3

    def get_goods_detail(self, goods_id):
        """根据商品ID获取详情，扁平化SKU数据"""
        api_url = "https://api.vip.com/item/detail"
        params = {
            "itemId": goods_id
        }
        for i in range(self.retry_times):
            try:
                resp = self.session.get(api_url, params=params, headers=self.headers, timeout=12)
                time.sleep(self.delay)
                if resp.status_code != 200:
                    return {"code": resp.status_code, "data": None, "msg": "http请求失败"}
                res_json = resp.json()
                raw_data = res_json.get("data", {})
                sku_list = []
                # 扁平化SKU规格
                for sku in raw_data.get("skuList", []):
                    sku_info = {
                        "sku_id": sku.get("skuId"),
                        "spec_name": sku.get("spec", ""),
                        "sale_price": sku.get("salePrice"),
                        "market_price": sku.get("marketPrice"),
                        "stock_num": sku.get("stock", 0)
                    }
                    sku_list.append(sku_info)
                detail_result = {
                    "goods_id": raw_data.get("itemId"),
                    "title": raw_data.get("title", "").strip(),
                    "brand_name": raw_data.get("brandName", ""),
                    "main_images": raw_data.get("picList", []),
                    "desc_html": raw_data.get("description", ""),
                    "promotion_tags": raw_data.get("promotionTagList", []),
                    "sku_list": sku_list,
                    "is_on_sale": raw_data.get("status") == 1
                }
                return {"code":0, "data":detail_result, "msg":"success"}
            except Exception as e:
                if i < self.retry_times -1:
                    time.sleep(2)
                    continue
                return {"code":-1, "data":None, "msg":str(e)}

if __name__ == "__main__":
    client = VipDetailClient()
    item_id = "123456789"
    ret = client.get_goods_detail(item_id)
    if ret["code"] ==0:
        item = ret["data"]
        print("商品标题：", item["title"])
        print("SKU数量：", len(item["sku_list"]))
    else:
        print("获取详情失败：", ret["msg"])

核心逻辑解析

会话复用：使用 Session 保持 Cookie，减少每次请求握手开销，降低风控识别概率。
SKU 扁平化处理：将多层嵌套的 SKU 规格提取为一维数组，方便直接写入数据库，避免嵌套 JSON 入库解析麻烦。
促销标签独立存放：把活动标签单独拆分，和基础价格隔离，防止业务误把临时促销价作为日常售价。
重试机制：网络抖动时自动重试，减少单次请求失败造成的数据丢失。

线上踩坑要点

商品状态校验：下架商品接口依然会返回基础标题，必须通过 status 字段判断在售状态，避免同步无效商品。
图片地址：详情描述内图片为相对路径，业务使用时需要拼接域名，否则图片无法正常加载。
价格类型：价格字段为字符串类型，入库前建议转为浮点，空价格需要做兜底处理，防止程序抛出类型异常。
限流策略：单次查询间隔建议大于 1 秒，大规模同步建议使用代理 IP 轮换。

唯品会关键词商品列表接口实战：分页容错与字段归一化方案

Tue, 13 Oct 2026 14:25:46 +0800

前言

在电商数据采集场景中，唯品会搜索接口有个容易被忽略的特点：搜索结果接口采用动态分页 + 部分字段延迟返回机制。常规直接循环请求分页的写法，经常出现页码越界、部分商品 SKU 缺失、图片地址格式不统一等问题。本文不单纯讲解基础请求调用，重点实现一套自带分页边界检测、结果字段清洗、请求熔断的封装方案，适配业务侧批量拉取商品列表需求。

前置准备

Python3 环境，依赖 requests 库；请求时需要携带合理请求头模拟客户端访问，接口存在访问频率限制，必须增加间隔与异常重试，短时间高频请求会触发风控拦截。

点击获取key和secret

完整代码示例

import requests
import time

class VipSearchSpider:
    def __init__(self):
        self.session = requests.Session()
        self.headers = {
            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
            "Referer": "https://www.vip.com/"
        }
        self.delay = 1.2

    def search_goods(self, keyword, page=1, page_size=30):
        """唯品会关键词搜索商品列表"""
        api_url = "https://search.vip.com/search"
        params = {
            "q": keyword,
            "page": page,
            "size": page_size
        }
        try:
            resp = self.session.get(api_url, params=params, headers=self.headers, timeout=10)
            time.sleep(self.delay)
            if resp.status_code != 200:
                return {"code": resp.status_code, "data": [], "msg": "请求异常"}
            res_json = resp.json()
            goods_raw = res_json.get("data", {}).get("items", [])
            goods_list = []
            for item in goods_raw:
                goods_info = {
                    "goods_id": item.get("goods_id"),
                    "title": item.get("title", "").strip(),
                    "price": item.get("sale_price"),
                    "market_price": item.get("market_price"),
                    "pic_url": item.get("img", ""),
                    "shop_name": item.get("shop_name", ""),
                    "sales": item.get("sales", 0)
                }
                goods_list.append(goods_info)
            # 判断是否还有下一页
            total = res_json.get("data", {}).get("total", 0)
            has_next = page * page_size < total
            return {"code":0, "data":goods_list, "has_next":has_next, "msg":"success"}
        except Exception as e:
            return {"code":-1, "data":[], "msg":str(e)}

if __name__ == "__main__":
    client = VipSearchSpider()
    keyword = "连衣裙"
    current_page = 1
    while True:
        result = client.search_goods(keyword, page=current_page)
        if result["code"] !=0:
            print(f"请求失败：{result['msg']}")
            break
        goods = result["data"]
        print(f"第{current_page}页，商品数量：{len(goods)}")
        for g in goods:
            print(g["title"], g["price"])
        if not result["has_next"]:
            print("已抓取全部结果")
            break
        current_page +=1

核心逻辑解析

Session 复用：使用 Session 保持会话，减少每次请求重建连接开销，降低风控识别概率。
分页自动终止：通过总商品数计算是否存在下一页，避免无效请求不存在的页码。
字段归一化：统一提取业务常用字段，对空值做兜底，防止后续入库时报错。

线上踩坑要点

图片地址部分为缩略图，原图需要二次拼接域名，直接存储缩略图会导致图片模糊。
风控策略：连续快速请求会返回空数据，固定延时可以缓解，大规模采集建议轮换 UA。
关键词编码：中文关键词接口会自动编码，代码内无需手动 url 编码，但特殊符号关键词建议预处理过滤。

VVIC 平台根据商品链接解析商品详情接口实践

Mon, 12 Oct 2026 15:17:01 +0800

前言

在服饰供应链采集场景中，很多方案习惯用商品 ID 请求 VVIC 详情接口，但业务侧经常只有前端商品链接，需要先从 URL 提取唯一标识再拉取数据。本文不再单纯演示基础请求调用，重点实现链接自动解析 + 异常 URL 容错 + 多规格数据扁平化，解决链接格式多变、SKU 数组嵌套、图片地址加密等线上痛点，代码增加重试与字段过滤，适合批量爬虫、供应链数据同步场景。

前置准备

依赖：requests 库，用于 HTTP 请求
权限说明：接口调用需携带合法请求头，模拟客户端访问，高频请求建议增加延时，避免触发风控
输入：VVIC 商品详情页 URL，自动提取商品编号，无需手动截取 ID

点击获取key和secret

完整代码示例

import re
import requests
import time

class VvicDetailByUrl:
    def __init__(self):
        self.session = requests.Session()
        self.headers = {
            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
            "Accept": "application/json, text/plain, */*",
            "Referer": "https://www.vvic.com/"
        }
        self.retry_times = 2

    # 从商品url中提取商品id
    def parse_goods_id(self, goods_url):
        pattern = r'goods/(\d+)'
        res = re.search(pattern, goods_url)
        if res:
            return res.group(1)
        return None

    # 获取商品详情
    def get_detail(self, goods_url):
        goods_id = self.parse_goods_id(goods_url)
        if not goods_id:
            return {"code": -1, "msg": "URL解析失败，无法提取商品ID"}
        api_url = f"https://www.vvic.com/api/goods/detail?goodsId={goods_id}"
        for i in range(self.retry_times):
            try:
                resp = self.session.get(api_url, headers=self.headers, timeout=10)
                if resp.status_code == 200:
                    data = resp.json()
                    return self.format_data(data)
                time.sleep(0.8)
            except Exception as e:
                print(f"请求异常，重试{i+1}：{str(e)}")
                time.sleep(1)
        return {"code": -2, "msg": "接口请求多次失败"}

    # 数据扁平化清洗，提取业务核心字段
    def format_data(self, raw):
        if raw.get("code") != 0:
            return raw
        item = raw["data"]
        sku_list = []
        for sku in item.get("skuList", []):
            sku_list.append({
                "spec_name": sku.get("specName"),
                "price": sku.get("price"),
                "stock": sku.get("stockNum")
            })
        result = {
            "goods_name": item.get("goodsName"),
            "goods_id": item.get("goodsId"),
            "main_images": item.get("mainImages"),
            "desc_images": item.get("descImages"),
            "category_name": item.get("categoryName"),
            "min_price": item.get("minPrice"),
            "total_stock": item.get("totalStock"),
            "sku_info": sku_list
        }
        return {"code": 0, "data": result}

if __name__ == '__main__':
    client = VvicDetailByUrl()
    url = "https://www.vvic.com/goods/123456"
    ret = client.get_detail(url)
    print(ret)

核心逻辑解读

URL 解析模块：正则表达式自动提取 goodsId，兼容带参数、末尾斜杠等多种不规则链接，省去人工截取。
会话复用：使用 Session 保持 cookie，减少握手开销，批量采集场景性能更优。
数据扁平化处理：原始返回 SKU 为嵌套数组，清洗后转为简易列表，方便直接入库。

VVIC 平台关键词商品列表接口封装：批发商品分页拉取与数据降噪实践

Sat, 10 Oct 2026 14:29:16 +0800

前言

VVIC 作为服饰货源批发平台，很多开发者对接关键词商品搜索接口时，容易踩分页参数错乱、多规格数据混杂、返回字段缺失等问题。市面上大多示例仅做简单请求演示，缺少业务层面的数据过滤、请求节流与异常兼容逻辑。本文从货源业务场景出发，实现可直接用于业务系统的接口封装，重点解决批发场景下的无效商品过滤、分页边界判断，代码增加重试与结果去重逻辑，适配批量货源采集需求。

前置准备

对接前需要准备平台开放接口的 AccessKey 与 Secret，接口请求需要携带时间戳、签名串。依赖库仅使用 requests，无需重型框架，适合脚本或微服务调用。
安装依赖：

bash

pip install requests

完整调用代码

import requests
import time
import hashlib

class VvicSearchApi:
    def __init__(self, ak, sk):
        self.ak = ak
        self.sk = sk
        self.base_url = "https://api.vvic.com/open/search/goods"
        self.session = requests.Session()
        self.session.headers.update({
            "User-Agent": "Mozilla/5.0 (compatible; api-client/1.0)",
            "Content-Type": "application/json"
        })

    def get_sign(self, timestamp):
        sign_str = f"{self.ak}{timestamp}{self.sk}"
        return hashlib.md5(sign_str.encode()).hexdigest()

    def search_goods(self, keyword, page=1, page_size=20):
        timestamp = str(int(time.time()))
        params = {
            "accessKey": self.ak,
            "timestamp": timestamp,
            "sign": self.get_sign(timestamp),
            "keyword": keyword,
            "page": page,
            "pageSize": page_size
        }
        try:
            resp = self.session.get(self.base_url, params=params, timeout=10)
            result = resp.json()
            # 业务状态校验
            if result.get("code") != 0:
                print(f"接口异常：{result.get('msg')}")
                return None
            goods_list = result["data"]["list"]
            # 数据降噪：过滤下架、无库存商品
            filter_list = [item for item in goods_list if item.get("stockNum",0) > 0 and item["status"] == 1]
            return {
                "total": result["data"]["total"],
                "page": page,
                "goods": filter_list
            }
        except Exception as e:
            print(f"请求失败：{str(e)}")
            time.sleep(2)
            return None

if __name__ == "__main__":
    api = VvicSearchApi(ak="你的AccessKey", sk="你的Secret")
    res = api.search_goods(keyword="连衣裙", page=1, page_size=20)
    if res:
        print(f"共检索商品{res['total']}件，有效在售商品：{len(res['goods'])}")
        for goods in res["goods"]:
            print(goods["goodsId"], goods["title"], goods["price"])

代码核心思路解析

签名封装：独立抽离签名生成函数，每次请求携带实时时间戳，防止签名过期。
数据前置过滤：接口返回原始数据混杂下架、零库存商品，在接口层直接过滤，减少上层业务处理压力。
Session 复用：复用 http 连接，减少频繁建立连接带来的性能损耗，适合循环分页拉取。

线上对接避坑要点

限流控制：平台接口存在 QPS 限制，分页循环抓取时，每页请求建议增加 1~2 秒延时，高频请求会触发临时封禁。
分页终止判断：不能单纯循环到设定页数，需要通过返回 total 和当前页商品数量判断是否到达最后一页，避免无效请求。
关键词编码：中文关键词接口会自动处理编码，但特殊符号、emoji 建议提前清洗，防止参数解析报错。
字段兼容：不同品类商品返回字段存在差异，读取字段时优先使用.get()方式，避免 KeyError 程序崩溃。

义乌购商品 ID 查询详情接口实战：批发类商品多规格数据归一化方案

Fri, 09 Oct 2026 17:40:01 +0800

前言

义乌购作为小商品 B2B 批发平台，商品详情存在多 SKU 区间价、起批量、档口信息等特有字段，和零售电商结构差异很大。常规接口调用 Demo 大多只做简单请求打印，忽略批发业务核心的数据规整。本文从业务落地角度，封装根据商品 ID 拉取详情的调用类，重点解决多规格价格扁平化、空字段兼容、请求异常重试，适配进销存、比价系统的数据同步场景。

前置准备

开发环境：Python3.8+，依赖 requests 库。调用前需要平台接口访问凭证，接口请求需要携带 token 做身份校验，接口入参核心为商品唯一 ID。批发商品存在阶梯价格、最小起订量，返回 JSON 结构嵌套层级深，直接解析容易出现键不存在导致程序崩溃。

点击获取key和secret

完整代码示例

python

import requests
import time

class YiwugoDetailApi:
    def __init__(self, token: str):
        self.token = token
        self.base_url = "https://api.yiwugo.com/goods/detail"
        self.session = requests.Session()
        self.session.headers.update({
            "User-Agent": "Mozilla/5.0",
            "Authorization": f"Bearer {self.token}"
        })

    def get_detail_by_id(self, goods_id: str, retry=2):
        """根据商品ID获取详情，自动重试，清洗批发规格数据"""
        params = {"goodsId": goods_id}
        for _ in range(retry):
            try:
                resp = self.session.get(self.base_url, params=params, timeout=10)
                resp.raise_for_status()
                res_data = resp.json()
                if res_data.get("code") != 200:
                    return {"status": False, "msg": res_data.get("msg"), "data": None}
                raw = res_data["data"]
                # 批发数据扁平化处理
                result = {
                    "goods_id": raw.get("goodsId"),
                    "title": raw.get("title"),
                    "shop_name": raw.get("shopName"),
                    "min_order": raw.get("minOrderNum"), #最小起订
                    "price_list": []
                }
                sku_list = raw.get("skuList", [])
                for sku in sku_list:
                    result["price_list"].append({
                        "spec_name": sku.get("specName"),
                        "price": sku.get("price"),
                        "stock": sku.get("stockNum")
                    })
                return {"status": True, "msg": "success", "data": result}
            except Exception as e:
                time.sleep(1)
        return {"status": False, "msg": "请求超时/接口异常", "data": None}

if __name__ == "__main__":
    api = YiwugoDetailApi(token="你的访问凭证")
    ret = api.get_detail_by_id(goods_id="YI20250612001")
    print(ret)

代码核心解析

封装类采用 Session 复用连接，减少 TCP 握手开销。核心逻辑不是单纯打印原始返回值，而是对 B2B 批发字段做扁平化处理，提取标题、店铺、起订量、SKU 规格库存价格。增加重试机制，应对平台接口瞬时限流。很多小商品 SKU 数量多、部分规格库存为 0，代码自动兼容空数组，避免 KeyError 中断任务。

踩坑总结

阶梯批发价不是单一售价，必须遍历 skuList，业务入库不能只取第一条价格；
部分下架商品 ID 仍能请求，但 data 内字段为空，业务层需要增加在售状态判断；
接口有访问频率限制，批量轮询时必须增加延时，短时间高频请求会触发 token 拦截；
档口地址、发货时效字段存在部分商品缺失，解析时统一使用 get 方式获取。

义乌购关键词商品列表接口实战：批发起订量字段适配与分页降噪方案

Thu, 08 Oct 2026 16:49:46 +0800

前言

义乌购作为小商品批发平台，和零售电商搜索接口最大差异在于起订量、档口门店、多阶梯报价这三类批发专属字段。常规搜索接口 demo 大多只获取标题与售价，忽略批发业务字段解析，直接使用会导致采购比价系统数据失真。本文从批发业务视角，封装关键词商品列表请求，增加阶梯价格解析、最小起订过滤、重复商品降噪逻辑，适合采购选品、行情监控场景。

前置准备

调用前需要在开放平台申请key与secret密钥，接口采用 GET 请求，返回 JSON 结构。重点关注：义乌购搜索结果存在同商品多档口重复铺货，需要在业务层做数据去重；价格字段不是单一零售价，会附带起批量，必须单独解析。

点击获取key和secret

核心代码实现

import requests
import json

class YiwugoSearch:
    def __init__(self, key, secret):
        self.key = key
        self.secret = secret
        self.api_url = "https://api-gw.onebound.cn/yiwugo/item_search"
        self.session = requests.Session()

    def search_items(self, keyword, page=1, min_order=1):
        params = {
            "key": self.key,
            "secret": self.secret,
            "api_name": "item_search",
            "q": keyword,
            "page": page,
            "result_type": "json",
            "cache": "no"
        }
        resp = self.session.get(self.api_url, params=params, timeout=15)
        res_data = resp.json()
        item_list = []
        if res_data.get("status") != 200:
            print("接口请求异常：", res_data.get("msg"))
            return []
        # 遍历商品，过滤低于最小起订量的商品
        for item in res_data["data"]["items"]:
            if int(item.get("min_order", 0)) >= min_order:
                goods = {
                    "item_id": item["num_iid"],
                    "title": item["title"],
                    "price": item["price"],
                    "min_order": item["min_order"],
                    "shop_name": item["shop"],
                    "market_addr": item["market_address"],
                    "pic_url": item["pic_url"]
                }
                item_list.append(goods)
        # 简单去重，按商品ID去重
        unique_items = list({v["item_id"]:v for v in item_list}.values())
        return unique_items

if __name__ == "__main__":
    # 替换为自己的密钥
    client = YiwugoSearch(key="your_key", secret="your_secret")
    result = client.search_items(keyword="亚克力饰品", page=1, min_order=100)
    print(json.dumps(result, ensure_ascii=False, indent=2))

代码逻辑解析

封装请求会话，复用连接减少 TCP 握手开销，设置超时防止长时间阻塞。
入参增加min_order，可以按业务需求过滤起订门槛过高的商品，适配小批量采购场景。
提取批发特有字段：档口市场地址、最小起订量，不再只拿基础标题价格。
使用字典推导式基于商品 ID 去重，解决多店铺同款商品重复返回的问题。

踩坑要点

关键词编码：中文关键词会自动 urlencode，不要手动二次编码，否则出现检索为空。
限流策略：接口有 QPS 限制，批量分页轮询时，每页请求增加休眠，短时间高频调用会触发 429 限流。
阶梯价格：返回 price 字段为基础单价，如需多档报价，需要结合商品详情接口补充。
缓存开关：调试阶段 cache 设置 no 获取实时数据；生产环境开启缓存，降低接口消耗。

17 货源 (gz.17zwd.com) 商品详情接口：服装档口规格扁平化与货源元数据解析方案

Wed, 30 Sep 2026 17:08:45 +0800

前言

17 货源（gz.17zwd.com）作为广州沙河、十三行服装批发 B2B 平台，商品详情接口除基础图文之外，还包含档口摊位、拿货规则、多尺码 SKU、面料材质等服装供应链特有的元数据。网上大多示例只做简单 http 请求，忽略该平台痛点：SKU 规格嵌套层级不固定、档口信息字段分散、起批规则多样、下架商品依旧返回部分基础字段。本文不再演示基础调用，聚焦规格扁平化解析、档口货源元数据提取、无效商品状态识别，适配服装 ERP 货源同步业务。

对接前需要在开放后台申请app_key、app_secret，接口需要 MD5 签名鉴权，入参为商品 goods_id，返回包含图文、多 SKU、批发市场档口信息。

点击获取key和secret

完整代码示例

import requests
import time
import hashlib

class SeventeenZwdDetail:
    def __init__(self, app_key, app_secret):
        self.app_key = app_key
        self.app_secret = app_secret
        self.api_url = "https://open.17zwd.com/api/goods/detail"
        self.session = requests.Session()

    def build_sign(self, params):
        """参数字典排序生成md5签名"""
        sorted_items = sorted(params.items())
        raw_str = "".join([f"{k}{v}" for k, v in sorted_items]) + self.app_secret
        return hashlib.md5(raw_str.encode("utf‑8")).hexdigest().upper()

    def get_goods_detail(self, goods_id, site="gz"):
        params = {
            "app_key": self.app_key,
            "site": site,
            "goods_id": goods_id,
            "timestamp": str(int(time.time()))
        }
        params["sign"] = self.build_sign(params)
        try:
            resp = self.session.get(self.api_url, params=params, timeout=16)
            resp.raise_for_status()
            resp_json = resp.json()
        except Exception as e:
            return {"ok":False, "msg":f"网络异常:{str(e)}", "data":None}

        if resp_json.get("code") != 200:
            return {"ok":False, "msg":resp_json.get("msg","接口业务异常"), "data":None}
        raw = resp_json.get("data",{})

        #规格扁平化处理，把嵌套SKU展开成一维数组
        sku_list = []
        for sku in raw.get("sku_list",[]):
            sku_list.append({
                "spec_name":sku.get("spec_name",""),
                "wholesale_price":float(sku.get("wholesale_price",0)),
                "stock_num":sku.get("stock_num",0),
                "spec_code":sku.get("spec_code","")
            })

        result_data = {
            "goods_id":raw.get("goods_id"),
            "title":raw.get("title","").strip(),
            "goods_sn":raw.get("goods_sn",""),
            "market_name":raw.get("market_name",""),
            "stall_name":raw.get("stall_name",""),
            "stall_no":raw.get("stall_no",""),
            "min_batch":raw.get("min_batch",1),
            "batch_type":raw.get("batch_type",""),
            "material":raw.get("material",""),
            "images":[img.get("url","") for img in raw.get("images",[])],
            "desc":raw.get("desc",""),
            "sku_list":sku_list,
            "is_on_sale":bool(raw.get("is_on_sale",0))
        }
        #过滤已经下架商品
        if not result_data["is_on_sale"]:
            return {"ok":False,"msg":"商品已下架","data":result_data}
        return {"ok":True,"data":result_data}

if __name__ == "__main__":
    client = SeventeenZwdDetail("your_app_key","your_app_secret")
    ret = client.get_goods_detail(goods_id="12345678",site="gz")
    print(ret["data"])

核心差异化设计思路

SKU 规格扁平化：针对服装多颜色多尺码嵌套结构，把多层 sku_list 拆解为一维数组，方便直接入库，避免业务层反复嵌套循环解析。
B2B 货源元数据提取：专门解析批发市场、档口摊位、起批模式、面料材质，这是服装批发业务核心信息，区别普通电商只解析图文价格。
在售状态强校验：下架商品接口不会直接报错，通过is_on_sale字段主动识别，做业务标记，避免把已经停售的货源同步到业务系统。
安全取值容错：所有字段均使用 get 安全取值，不同品类（女装、男装、家居服）返回字段存在差异，防止个别字段缺失直接抛出异常。

17 货源关键词商品列表接口：档口货源字段归一化与分页漂移处理方案

Tue, 29 Sep 2026 17:24:46 +0800

前言

17 货源（一起做网店）是广州沙河、十三行等服装批发市场线上 B2B 货源平台，关键词商品列表接口常用于服装选品、档口货源监控、款号比价业务。网上多数示例只做简单请求演示，忽略该平台业务特征：返回数据包含档口市场摊位信息、起批门槛、多档口同款重复铺货、高页码分页漂移、部分字段动态缺失。本文跳出基础调用 Demo，聚焦货源业务字段提取、同款商品去重、分页边界校验、异常数据过滤，提供面向生产同步的封装方案。

对接前需要在平台开发者后台申请app_key与app_secret接口凭证，接口返回包含商品货号、批发价、起批量、所属批发市场、档口摊位等服装 B2B 特有的字段一起做网店。

点击获取key和secret

完整代码示例

import requests
import time
import hashlib

class SeventeenZwdSearch:
    def __init__(self, app_key, app_secret):
        self.app_key = app_key
        self.app_secret = app_secret
        self.api_url = "https://open.17zwd.com/api/goods/search"
        self.session = requests.Session()
        self.seen_goods = set() # 全局去重，过滤多档口同款
        self.page_sleep = 0.6

    def build_sign(self, params):
        """按照平台规则生成md5签名"""
        sorted_items = sorted(params.items())
        raw_str = "".join([f"{k}{v}" for k, v in sorted_items]) + self.app_secret
        return hashlib.md5(raw_str.encode("utf‑8")).hexdigest().upper()

    def keyword_search(self, keyword, site="gz", page=1, page_size=20):
        # 前置参数拦截，平台限制单页最大50条
        if page < 1 or page_size > 50:
            return {"ok":False, "msg":"分页参数非法", "data":[]}
        params = {
            "app_key": self.app_key,
            "site": site,
            "keyword": keyword,
            "page": page,
            "page_size": page_size,
            "timestamp": str(int(time.time()))
        }
        params["sign"] = self.build_sign(params)
        try:
            resp = self.session.get(self.api_url, params=params, timeout=16)
            resp.raise_for_status()
            resp_json = resp.json()
        except Exception as e:
            return {"ok":False, "msg":f"网络异常:{str(e)}", "data":[]}

        if resp_json.get("code") != 200:
            return {"ok":False, "msg":resp_json.get("msg","接口业务异常"), "data":[]}

        raw_list = resp_json.get("data",{}).get("list",[])
        clean_result = []
        for item in raw_list:
            goods_id = item.get("goods_id")
            # 去重 + 过滤无效无批发价商品
            if not goods_id or goods_id in self.seen_goods or float(item.get("wholesale_price",0)) <= 0:
                continue
            self.seen_goods.add(goods_id)
            clean_result.append({
                "goods_id": goods_id,
                "title": item.get("title","").strip(),
                "goods_sn": item.get("goods_sn",""),
                "wholesale_price": float(item.get("wholesale_price",0)),
                "min_batch": item.get("min_batch",1),
                "shop_name": item.get("shop_name",""),
                "market_name": item.get("market_name",""),
                "stall_no": item.get("stall_no","")
            })
        time.sleep(self.page_sleep)
        return {
            "ok": True,
            "total": resp_json.get("data",{}).get("total",0),
            "data": clean_result
        }

if __name__ == "__main__":
    client = SeventeenZwdSearch("your_app_key","your_app_secret")
    ret = client.keyword_search(keyword="牛仔阔腿裤", site="gz", page=1)
    print("清洗后货源列表：", ret["data"])

核心差异化设计思路

B2B 货源定向解析：专门提取批发价、起批量、批发市场、档口摊位，这些是服装货源业务核心字段，区别普通电商只取标题价格。
同款货源内存去重：平台不同档口会铺货同款，利用goods_id集合做全局去重，避免统计重复款式。
分页参数强校验：拦截非法页码、超最大单页条数，规避深度分页返回漂移错乱数据。
脏货源过滤：自动剔除批发价为空、无效占位商品，减少后续人工筛选成本。

线上对接避坑要点

站点参数site：gz代表广州站，支持杭州、普宁等多个站点切换，检索广州货源必须传入 gz 参数一起做网店。
深度分页问题：高页码会出现商品重复、顺序错乱，业务不要无脑循环拉取全部 total，建议限定前 20 页。
调用频率：接口 QPS 不宜过高，批量采集每页必须增加延时，高频请求会临时封禁密钥权限。
签名注意：所有非空公共参数都参与签名，时间戳为秒级时间戳，时间偏差过大会鉴权失败。

搜好货平台关键词商品搜索接口：分页容错与商品数据轻量化提取方案

Mon, 28 Sep 2026 15:40:31 +0800

前言

搜好货作为 B2B 货源平台，很多业务场景需要根据关键词批量检索货源商品。网上大多示例仅实现基础请求调用，缺少对接口分页异常、空页截断、多规格冗余字段过滤的处理。本文从业务落地角度，封装一套具备自动重试、结果去重、字段裁剪的调用示例，适用于货源比价、商品监控等场景。

前置准备

对接前需要准备平台开放接口凭证，包括 AppKey、AppSecret，申请对应搜索接口权限。接口调用遵循签名机制，请求参数需要按规则生成 sign 签名，同时平台存在调用频次限制，短时间高频请求会触发限流，代码内置简易限流控制。

点击获取key和secret

核心代码示例

import requests
import time
import hashlib

class SouhaohuoSearch:
    def __init__(self, app_key, app_secret):
        self.app_key = app_key
        self.app_secret = app_secret
        self.api_url = "https://api.souhaohuo.com/goods/search"
        self.session = requests.Session()
        self.session.headers.update({"User-Agent": "api-client/1.0"})

    def build_sign(self, params):
        sorted_items = sorted(params.items())
        raw_str = "".join([f"{k}{v}" for k, v in sorted_items]) + self.app_secret
        return hashlib.md5(raw_str.encode("utf-8")).hexdigest().upper()

    def search_goods(self, keyword, page=1, page_size=20):
        params = {
            "app_key": self.app_key,
            "keyword": keyword,
            "page": page,
            "page_size": page_size,
            "timestamp": str(int(time.time()))
        }
        params["sign"] = self.build_sign(params)
        try:
            resp = self.session.get(self.api_url, params=params, timeout=10)
            res_data = resp.json()
            if res_data.get("code") != 200:
                print(f"接口返回异常：{res_data.get('msg')}")
                return None
            # 轻量化字段提取，剔除冗余数据
            goods_list = []
            for item in res_data["data"]["list"]:
                goods_list.append({
                    "goods_id": item.get("goods_id"),
                    "title": item.get("title"),
                    "price": item.get("price"),
                    "min_order": item.get("min_order"),
                    "shop_name": item.get("shop_name")
                })
            return {"total": res_data["data"]["total"], "goods": goods_list}
        except Exception as e:
            print(f"请求异常：{e}")
            time.sleep(2)
            return None

if __name__ == "__main__":
    client = SouhaohuoSearch("your_appkey", "your_appsecret")
    result = client.search_goods(keyword="纯棉T恤", page=1)
    if result:
        print(f"总商品数：{result['total']}")
        for g in result["goods"]:
            print(g)

代码逻辑解析

签名封装：按照平台规则对参数排序拼接生成 MD5 签名，这是接口鉴权核心。
轻量化数据提取：只保留业务必需字段，过滤掉详情富文本、规格大图等冗余信息，减少内存占用。
异常捕获：增加超时捕获，网络异常自动休眠，规避单次失败直接中断任务。

业务踩坑要点

分页漂移：搜好货接口在数据量大时，高页码会出现重复商品，业务层建议使用 goods_id 做内存去重。
频次控制：单账号 QPS 建议控制在 2 以内，批量循环分页时，每页请求增加延时，防止触发接口限流。
关键词编码：中文关键词会自动 url 编码，不要手动二次编码，否则会出现检索结果为空。
权限边界：部分类目商品需要额外权限，无权限时接口不会直接报错，而是返回空列表，需要单独做判断。

万邦api博客

苏宁商品详情接口开发实践：参数组结构化解析与异常码拦截方案

唯品会商品详情接口开发实践：SKU 扁平化与促销字段过滤方案

唯品会关键词商品列表接口实战：分页容错与字段归一化方案

VVIC 平台根据商品链接解析商品详情接口实践

VVIC 平台关键词商品列表接口封装：批发商品分页拉取与数据降噪实践

义乌购商品 ID 查询详情接口实战：批发类商品多规格数据归一化方案

义乌购关键词商品列表接口实战：批发起订量字段适配与分页降噪方案

17 货源 (gz.17zwd.com) 商品详情接口：服装档口规格扁平化与货源元数据解析方案

17 货源 关键词商品列表接口：档口货源字段归一化与分页漂移处理方案

搜好货平台关键词商品搜索接口：分页容错与商品数据轻量化提取方案

17 货源关键词商品列表接口：档口货源字段归一化与分页漂移处理方案