微店开放平台的item_search接口是根据关键词搜索商品列表的核心工具，适用于店铺选品、竞品分析、电商聚合平台等场景。本文将全面讲解该接口的对接流程、参数配置、代码实现及最佳实践，帮助开发者从入门到精通掌握接口使用。
一、接口基础认知
二、对接前置准备
三、接口调用流程
四、代码实现示例（Python）
import requests
import hashlib
import time
import json
class WeidianSearchApi:
def __init__(self, appkey, appsecret):
self.appkey = appkey
self.appsecret = appsecret
self.url = "https://api.weidian.com/item/search" # 正式环境
# 沙箱环境：https://sandbox.api.weidian.com/item/search
def generate_signature(self, params):
"""生成签名"""
# 1. 按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接为key=value&key=value格式
sign_str = "&".join([f"{k}={v}" for k, v in sorted_params])
# 3. 追加appsecret
sign_str += f"&appsecret={self.appsecret}"
# 4. MD5加密（32位小写）
signature = hashlib.md5(sign_str.encode()).hexdigest()
return signature
def item_search(self, keyword, page=1, page_size=20, **kwargs):
"""
搜索商品列表
:param keyword: 搜索关键词（必填）
:param page: 页码，默认1
:param page_size: 每页条数，默认20，最大50
:param kwargs: 可选参数（price_min, price_max, sort等）
:return: 搜索结果
"""
# 1. 组装基础参数
params = {
"appkey": self.appkey,
"timestamp": int(time.time()), # 秒级时间戳
"keyword": keyword,
"page": page,
"page_size": page_size
}
# 2. 合并可选参数
params.update(kwargs)
# 3. 生成签名
params["signature"] = self.generate_signature(params)
try:
# 4. 发送POST请求
response = requests.post(
url=self.url,
json=params,
headers={"Content-Type": "application/json"},
timeout=10
)
response.raise_for_status()
result = response.json()
# 5. 处理响应
if result.get("errcode") == 0:
return {
"success": True,
"total": result.get("total", 0),
"page": page,
"page_size": page_size,
"items": result.get("items", [])
}
else:
return {
"success": False,
"error_code": result.get("errcode"),
"error_msg": result.get("errmsg")
}
except Exception as e:
return {
"success": False,
"error_msg": f"请求异常: {str(e)}"
}
# 使用示例
if __name__ == "__main__":
# 替换为自己的appkey和appsecret
APPKEY = "your_appkey"
APPSECRET = "your_appsecret"
# 初始化API客户端
api = WeidianSearchApi(APPKEY, APPSECRET)
# 搜索"连衣裙"，第1页，20条/页，价格50-200元，按销量降序
result = api.item_search(
keyword="连衣裙",
page=1,
page_size=20,
price_min=50,
price_max=200,
sort="sales_desc" # 排序方式：sales_desc-销量降序，price_asc-价格升序
)
if result["success"]:
print(f"共搜索到 {result['total']} 个商品")
print(f"第 {result['page']} 页，当前页 {len(result['items'])} 个商品")
# 打印前5个商品信息
for i, item in enumerate(result["items"][:5]):
print(f"\n商品 {i+1}:")
print(f"ID: {item.get('item_id')}")
print(f"标题: {item.get('title')}")
print(f"售价: {item.get('price')} 元")
print(f"销量: {item.get('sales')} 件")
print(f"主图: {item.get('main_img')}")
else:
print(f"搜索失败: {result['error_msg']} (错误码: {result.get('error_code')})")