阿里巴巴作为国内最大的 B2B 电商平台，其item_search接口是通过关键词、分类、价格等条件批量商品的核心工具，广泛应用于供应商筛选、市场分析、采购系统集成等场景。本文将系统讲解该接口的对接流程、参数配置、代码实现及最佳实践，帮助开发者从入门到精通，构建高效的商品搜索系统。
一、接口基础认知
二、对接前置准备
三、接口调用流程
四、代码实现示例（Python）
import requests
import time
import hashlib
import json
from urllib.parse import urlencode
class AlibabaSearchApi:
def __init__(self, app_key, app_secret):
self.app_key = app_key
self.app_secret = app_secret
self.base_url = "https://gw.api.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.search/"
self.format = "json"
self.version = "1.0"
def generate_sign(self, params):
"""生成MD5签名"""
# 1. 按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接为key=value字符串
sign_str = urlencode(sorted_params)
# 3. 拼接app_secret并加密
sign_str += f"&app_secret={self.app_secret}"
return hashlib.md5(sign_str.encode()).hexdigest().upper()
def item_search(self, keywords, **kwargs):
"""
搜索商品列表
:param keywords: 搜索关键词（必填）
:param kwargs: 可选参数：
- categoryId: 分类ID
- startPrice/endPrice: 价格区间
- page: 页码（默认1）
- pageSize: 每页条数（1-50，默认20）
- sort: 排序方式（price_asc/price_desc/volume_desc）
:return: 搜索结果
"""
# 1. 组装公共参数
public_params = {
"app_key": self.app_key,
"method": "com.alibaba.product.alibaba.product.search",
"timestamp": int(time.time() * 1000), # 毫秒级时间戳
"format": self.format,
"v": self.version
}
# 2. 组装业务参数
param = {
"keywords": keywords,
"page": kwargs.get("page", 1),
"pageSize": min(kwargs.get("pageSize", 20), 50) # 限制最大条数
}
# 可选参数
if "categoryId" in kwargs:
param["categoryId"] = kwargs["categoryId"]
if "startPrice" in kwargs:
param["startPrice"] = kwargs["startPrice"]
if "endPrice" in kwargs:
param["endPrice"] = kwargs["endPrice"]
if "sort" in kwargs:
param["sort"] = kwargs["sort"]
# 3. 合并参数并生成签名
all_params = public_params.copy()
all_params["param"] = json.dumps(param) # 业务参数JSON序列化
all_params["sign"] = self.generate_sign(all_params)
try:
# 4. 发送POST请求
response = requests.post(
url=self.base_url,
data=all_params,
timeout=15
)
response.raise_for_status()
result = response.json()
# 5. 处理响应
if "error_response" in result:
error = result["error_response"]
return {
"success": False,
"error_code": error["code"],
"error_msg": error["msg"]
}
# 6. 提取搜索结果
search_result = result.get("alibaba_product_search_response", {}).get("result", {})
return {
"success": True,
"total_items": search_result.get("totalCount", 0),
"total_pages": (search_result.get("totalCount", 0) + param["pageSize"] - 1) // param["pageSize"],
"current_page": param["page"],
"items": search_result.get("products", [])
}
except Exception as e:
return {
"success": False,
"error_msg": f"请求异常: {str(e)}"
}
# 使用示例
if __name__ == "__main__":
# 替换为实际参数
APP_KEY = "your_app_key"
APP_SECRET = "your_app_secret"
# 初始化API客户端
api = AlibabaSearchApi(APP_KEY, APP_SECRET)
# 搜索"蓝牙耳机"，价格50-200元，按销量降序，第1页，30条/页
result = api.item_search(
keywords="蓝牙耳机",
startPrice=50,
endPrice=200,
sort="volume_desc",
page=1,
pageSize=30
)
if result["success"]:
print(f"搜索结果: 共 {result['total_items']} 个商品，{result['total_pages']} 页")
print(f"当前第 {result['current_page']} 页，显示 {len(result['items'])} 个商品\n")
# 打印前5个商品信息
for i, item in enumerate(result["items"][:5]):
print(f"商品 {i+1}:")
print(f"ID: {item.get('productId')}")
print(f"标题: {item.get('title')[:50]}...") # 截断长标题
print(f"单价: {item.get('price', {}).get('price')} 元")
print(f"起订量: {item.get('minOrderQuantity', {}).get('value')} {item.get('minOrderQuantity', {}).get('unit')}")
print(f"30天成交: {item.get('saleInfo', {}).get('tradeCount', 0)} 笔")
print(f"供应商: {item.get('sellerInfo', {}).get('companyName')}")
print(f"主图: {item.get('imageList', [{}])[0].get('url')}\n")
else:
print(f"搜索失败: {result.get('error_msg')} (错误码: {result.get('error_code')})")