快手电商作为主流的内容电商平台，item_search 接口是通过关键词批量获取快手商品列表的核心工具，支持按关键词、价格区间、销量、佣金比例、店铺类型等多维度筛选，返回商品标题、价格、佣金、销量、店铺信息等关键数据。该接口广泛应用于快手小店选品、电商数据分析、分销推广系统搭建等场景。
本攻略从接口认知、前置准备、分步骤对接、调试优化到合规上线，提供结构化的全流程指导，兼顾入门易用性与生产级稳定性，帮助开发者高效完成对接。
一、接口核心认知：功能与适配场景
- 接口定位与核心价值
核心功能：输入搜索关键词（支持多关键词组合），筛选快手电商平台的商品列表，支持价格区间、销量排序、佣金比例筛选、店铺类型（旗舰店 / 专卖店 / 普通店）过滤等，返回分页商品数据，可联动 item_get 接口获取商品详情（如规格参数、售后政策）。
快手平台特性
数据覆盖：收录快手小店、快手好物联盟的公开商品，新商品收录延迟 10-30 分钟；
筛选能力：支持精确 / 模糊匹配、价格区间（price_min/price_max）、销量 / 佣金 / 价格排序、佣金比例区间（commission_rate_min/commission_rate_max）、店铺资质筛选；
分销属性：部分商品返回佣金比例、推广链接、达人带货数据，适配分销推广场景；
权限要求：需通过快手开放平台或合规第三方服务商获取接口权限，个人开发者需实名认证，企业开发者需完成资质认证。
典型应用场景
选品工具开发：为快手达人 / 商家提供关键词选品功能，筛选高销量、高佣金商品；
电商数据分析：按行业关键词（如 “家居好物”“美妆护肤”）采集商品数据，分析品类趋势、价格带分布；
分销推广系统：获取商品推广链接和佣金信息，搭建快手分销平台，自动同步商品动态；
竞品监测：输入竞品关键词，分析竞品商品的定价、销量、佣金策略。 - 核心参数与返回字段
（1）请求参数（必填 + 可选，按优先级排序）
参数名称 类型 是否必填 说明 应用示例
app_key string 是 接口调用密钥，由快手开放平台 / 服务商分配 2025xxxxxxxxx
app_secret string 是 签名密钥，用于请求合法性校验（不可泄露） 5a6fxxxxxxxxx
keyword string 是 搜索关键词，支持多关键词空格分隔（AND 逻辑） 家居清洁 神器
price_min float 否 商品最低价格（单位：元），默认无下限 9.9
price_max float 否 商品最高价格（单位：元），默认无上限 99.9
sort string 否 排序方式，默认 relevance（相关度） sales（销量倒序）、price_asc（价格升序）、commission_rate_desc（佣金比例倒序）
commission_rate_min int 否 最低佣金比例（单位：%），仅好物联盟商品生效 10（筛选佣金≥10% 的商品）
commission_rate_max int 否 最高佣金比例（单位：%） 50
shop_type string 否 店铺类型筛选，默认 all flagship（旗舰店）、specialty（专卖店）、ordinary（普通店）
page_no int 否 页码，默认 1，最大支持 100 页 1、5
page_size int 否 每页商品数，默认 20，最大 50 20、50
timestamp long 是 请求时间戳（毫秒级，有效期 5 分钟） 1735689600000
sign string 是 签名值（按快手规则生成，核心校验项） 32 位 MD5 大写串
注意事项
价格区间：price_min 和 price_max 可单独设置（仅限制下限 / 上限），也可同时设置（区间筛选）；
佣金筛选：仅对加入快手好物联盟的商品生效，普通小店商品无佣金字段；
排序优先级：sort 设为 sales 时，优先展示近 30 天销量高的商品。
（2）返回核心字段（按业务场景分类）
字段分类 核心字段 说明
商品基础信息 item_id 快手商品唯一标识（用于调用 item_get 接口）
title 商品标题（含营销关键词，如 “买一送一”）
cover_url 商品主图 URL（高清）
price 商品售价（元，到手价）
original_price 商品原价（元，对比价）
sales 近 30 天销量
sku_count 商品规格数量（如颜色、尺寸选项数）
分销相关字段 commission_rate 佣金比例（%），仅好物联盟商品有值
commission 单件佣金（元，price * commission_rate / 100）
promotion_link 商品推广链接（分销专用）
店铺信息 shop_id 店铺 ID
shop_name 店铺名称
shop_type 店铺类型（旗舰店 / 专卖店 / 普通店）
shop_score 店铺评分（满分 5 分）
其他字段 create_time 商品上架时间
status 商品状态（on_sale 在售 /off_sale 下架）
location 商品发货地 - 接口限制与注意事项
调用频率限制
账号类型 调用频率 适用场景
个人开发者 10 次 / 分钟 小型选品工具、个人数据分析
企业开发者 50 次 / 分钟 分销平台、电商数据分析系统
数据缓存规则：搜索结果缓存 30 分钟，热门关键词缓存缩短至 10 分钟，企业用户可申请 refresh=1 强制刷新（需额外权限）；
内容限制：已下架商品、违规商品、未公开商品不会返回；部分商品因隐私设置，不返回店铺信息。
二、对接前准备：3 步搞定前置条件 - 获取接口权限（两种接入方式）
快手 item_search 接口无公开免费接入渠道，需通过官方开放平台或合规第三方服务商获取权限，两种方式对比如下：
接入方式 操作步骤 优缺点
快手开放平台（官方） 1. 登录 快手开放平台； - 注册账号并完成认证（个人 / 企业）；
- 创建应用，选择 “电商 API” 类目；
- 申请 item_search 接口权限，等待审核；
- 审核通过后，在应用详情页获取 app_key 和 app_secret 优点：数据权威、字段完整、合规性高；
缺点：审核严格（企业需提供营业执照）、周期长（3-5 个工作日）
第三方合规服务商 1. 选择口碑较好的服务商（如聚合数据、APISpace）； - 注册账号并完成实名认证；
- 购买快手电商接口套餐；
- 在服务商后台获取 app_key 和 app_secret 优点：接入快（10 分钟搞定）、无需复杂资质、提供调试工具；
缺点：部分高级字段（如推广链接）需付费升级
合规提示：禁止使用非法爬虫接口，违反快手平台规则和《反不正当竞争法》，存在法律风险。 - 技术环境准备
（1）支持语言与协议
协议：HTTPS（强制，确保数据传输安全）；
开发语言：支持 Python、Java、PHP、Go 等所有主流语言，推荐 Python（数据处理高效，适配批量请求场景）。
（2）必备工具与依赖
工具类型 推荐工具 用途
调试工具 Postman 快速验证接口可用性，排除代码逻辑干扰
在线 MD5 工具 校验签名生成正确性
开发依赖 requests（Python） 发送 HTTP 请求
hmac（Python） 生成接口签名
pandas（Python） 批量整理商品数据，导出 Excel
辅助工具 Redis 缓存搜索结果，减少重复请求
logging（Python） 记录接口调用日志，便于问题排查 - 业务需求梳理
关键词策略：明确核心关键词（如 “厨房好物”）和扩展关键词（如 “厨房收纳 神器”），避免过于宽泛导致结果冗余；
筛选条件定义：
选品场景：设置 sort=sales（销量优先）+ commission_rate_min=15（高佣金）；
低价商品采集：设置 price_max=19.9 + sort=price_asc（价格升序）；
字段筛选：仅保留业务必需字段（如选品需 title/price/sales/commission_rate），减少数据传输量。
三、实操步骤：接口对接全流程（Python 示例）
步骤 1：理解签名生成规则（关键！快手官方规则）
快手接口签名采用 MD5 加密，核心逻辑是参数排序 + 拼接密钥 + MD5 加密，具体步骤如下：
剔除请求参数中的 sign 字段；
将剩余参数按 参数名 ASCII 升序排序；
拼接成 key1=value1&key2=value2&... 的字符串；
在字符串末尾拼接 &app_secret=你的app_secret；
对拼接后的字符串进行 MD5 加密，生成 32 位大写字符串，即为 sign。
签名示例
假设参数：app_key=2025xxxx&keyword=家居清洁×tamp=1735689600000&app_secret=5a6fxxxx
排序后参数：app_key、keyword、timestamp；
拼接字符串：app_key=2025xxxx&keyword=家居清洁×tamp=1735689600000&app_secret=5a6fxxxx；
MD5 加密后得到 sign：E8F2C4D6A1B397508421FEDCBA654321。
步骤 2：完整代码实现（Python）
（1）依赖安装
bash
运行
pip install requests pandas
（2）核心代码（含签名生成、接口调用、数据保存）
import requests
import hashlib
import time
import json
import pandas as pd
from urllib.parse import urlencode
import logging
日志配置（记录接口调用日志，便于排查问题）
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
handlers=[logging.FileHandler("kuaishou_item_search.log"), logging.StreamHandler()]
)
接口配置（替换为自己的 app_key、app_secret、API 地址）
CONFIG = {
"app_key": "你的app_key",
"app_secret": "你的app_secret",
"api_url": "https://open.kuaishou.com/api/open/item_search", # 官方/服务商接口地址
"save_path": "快手商品列表.xlsx"
}
def generate_sign(params: dict, app_secret: str) -> str:
"""生成快手接口签名（MD5 32位大写）"""
# 1. 剔除 sign 字段（如果存在）
params.pop("sign", None)
# 2. 按参数名 ASCII 升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 3. 拼接参数字符串
param_str = urlencode(sorted_params, encoding="utf-8") + f"&app_secret={app_secret}"
# 4. MD5 加密并转大写
md5 = hashlib.md5()
md5.update(param_str.encode("utf-8"))
return md5.hexdigest().upper()
def kuaishou_item_search(
keyword: str,
price_min: float = None,
price_max: float = None,
sort: str = "relevance",
commission_rate_min: int = None,
shop_type: str = "all",
page_no: int = 1,
page_size: int = 20
) -> dict:
"""
调用快手 item_search 接口，获取商品列表
:param keyword: 搜索关键词
:param price_min: 最低价格
:param price_max: 最高价格
:param sort: 排序方式
:param commission_rate_min: 最低佣金比例
:param shop_type: 店铺类型
:param page_no: 页码
:param page_size: 每页条数
:return: 标准化后的商品数据
"""
# 1. 构建基础参数
params = {
"app_key": CONFIG["app_key"],
"keyword": keyword,
"sort": sort,
"shop_type": shop_type,
"page_no": page_no,
"page_size": page_size,
"timestamp": int(time.time() * 1000)
}
# 2. 补充可选参数
if price_min is not None:
params["price_min"] = price_min
if price_max is not None:
params["price_max"] = price_max
if commission_rate_min is not None:
params["commission_rate_min"] = commission_rate_min
# 3. 生成签名
params["sign"] = generate_sign(params, CONFIG["app_secret"])
try:
# 4. 发送 POST 请求（快手接口推荐 POST）
response = requests.post(
url=CONFIG["api_url"],
data=json.dumps(params),
headers={"Content-Type": "application/json"},
timeout=15,
verify=True
)
response.raise_for_status() # 抛出 HTTP 错误（如 401/403）
result = response.json()
# 5. 解析响应结果（以快手官方返回格式为例）
if result.get("code") == 0:
raw_data = result.get("data", {})
item_list = raw_data.get("item_list", [])
total = raw_data.get("total", 0) # 商品总数
page_total = raw_data.get("page_total", 1) # 总页码
# 标准化商品数据
standard_items = []
for item in item_list:
standard_items.append({
"关键词": keyword,
"商品ID": item.get("item_id", ""),
"商品标题": item.get("title", ""),
"主图链接": item.get("cover_url", ""),
"售价(元)": item.get("price", 0),
"原价(元)": item.get("original_price", 0),
"近30天销量": item.get("sales", 0),
"佣金比例(%)": item.get("commission_rate", 0),
"单件佣金(元)": round(item.get("price", 0) * item.get("commission_rate", 0) / 100, 2),
"店铺名称": item.get("shop_name", ""),
"店铺类型": item.get("shop_type", ""),
"店铺评分": item.get("shop_score", 0),
"商品状态": item.get("status", ""),
"发货地": item.get("location", ""),
"推广链接": item.get("promotion_link", ""),
"请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
})
return {
"success": True,
"data": standard_items,
"total": total,
"page_no": page_no,
"page_total": page_total
}
else:
error_msg = result.get("msg", "接口调用失败")
logging.error(f"接口返回错误：{error_msg}（code={result.get('code')}）")
return {"success": False, "error_msg": error_msg}
except requests.exceptions.RequestException as e:
logging.error(f"网络请求异常：{str(e)}")
return {"success": False, "error_msg": f"网络异常：{str(e)}"}
except Exception as e:
logging.error(f"数据解析异常：{str(e)}")
return {"success": False, "error_msg": f"解析异常：{str(e)}"}
def batch_get_items(
keyword: str,
max_page: int = 5,
kwargs
) -> list:
"""批量获取多页商品列表（控制频率，避免超限）"""
all_items = []
page_no = 1
while True:
logging.info(f"正在获取关键词「{keyword}」第 {page_no} 页商品")
result = kuaishou_item_search(keyword=keyword, page_no=page_no, kwargs)
if not result["success"]:
logging.error(f"第 {page_no} 页获取失败：{result['error_msg']}")
break
page_items = result["data"]
if not page_items:
logging.info(f"第 {page_no} 页无商品，批量获取结束")
break
all_items.extend(page_items)
logging.info(f"第 {page_no} 页获取成功，新增 {len(page_items)} 条商品（累计 {len(all_items)} 条）")
# 终止条件：达到最大页码或总页码
if page_no >= max_page or page_no >= result["page_total"]:
break
page_no += 1
# 控制调用频率（个人用户间隔 6 秒，企业用户间隔 1 秒）
time.sleep(6)
return all_items
def save_to_excel(items: list, save_path: str = CONFIG["save_path"]):
"""将商品列表保存为 Excel 文件"""
if not items:
logging.warning("无商品数据可保存")
return
df = pd.DataFrame(items)
# 去重（按商品ID）
df = df.drop_duplicates(subset=["商品ID"])
# 增量保存（避免覆盖历史数据）
try:
history_df = pd.read_excel(save_path, engine="openpyxl")
df = pd.concat([history_df, df], ignore_index=True).drop_duplicates(subset=["商品ID"])
except FileNotFoundError:
pass
df.to_excel(save_path, index=False, engine="openpyxl")
logging.info(f"商品数据已保存至：{save_path}（共 {len(df)} 条）")
调用示例
if name == "main":
# 单页获取：搜索“家居清洁 神器”，筛选价格 9.9-99.9 元，销量优先
single_page_result = kuaishou_item_search(
keyword="家居清洁 神器",
price_min=9.9,
price_max=99.9,
sort="sales",
page_size=20
)
if single_page_result["success"]:
print(f"单页获取 {len(single_page_result['data'])} 条商品")
print("第一条商品信息：", single_page_result["data"][0])
# 批量获取：获取前 5 页商品，保存到 Excel
# batch_items = batch_get_items(
# keyword="家居清洁 神器",
# price_min=9.9,
# price_max=99.9,
# sort="sales",
# max_page=5
# )
# save_to_excel(batch_items)
四、调试与问题排查：快速定位异常
- 优先用 Postman 调试（排除代码干扰）
构造请求：新建 POST 请求，填写接口 URL，请求头设置 Content-Type: application/json；
填写参数：在请求体中输入 app_key、keyword、timestamp 等必填项，补充筛选参数；
生成签名：用在线 MD5 工具手动计算 sign，填入参数；
发送请求：查看响应结果，验证接口是否正常。 - 高频问题排查表
问题现象 常见原因 解决方案
签名错误（401） 1. 参数排序错误；2. app_secret 不匹配；3. 时间戳过期；4. 中文关键词未 URL 编码 1. 按 ASCII 升序排序参数；2. 核对 app_secret 是否与开放平台一致；3. 校准本地时间（误差≤5 分钟）；4. 确保代码中使用 urlencode 处理中文
权限不足（403） 1. 未申请 item_search 接口权限；2. 账号类型不匹配（如个人账号使用企业字段）；3. 调用频率超限 1. 在开放平台确认接口已开通；2. 升级账号类型或移除企业专属参数；3. 降低调用频率，增加请求间隔
参数错误（400） 1. sort 取值非法（如填 sale 而非 sales）；2. 价格 / 佣金比例为非数字；3. page_size 超过 50 1. 核对 sort 取值（参考参数表）；2. 确保价格、佣金为数字类型；3. page_size 设为 ≤50
无商品返回 1. 关键词过于精准 / 无匹配商品；2. 筛选条件过于严格；3. 商品未被接口收录 1. 放宽关键词（如 “清洁神器” 改为 “家居清洁”）；2. 降低价格下限、提高佣金上限；3. 在快手小店搜索关键词，确认是否有商品
字段缺失（如无佣金） 1. 商品未加入好物联盟；2. 账号无分销权限 1. 仅筛选 commission_rate_min 时，确保商品是好物联盟商品；2. 申请快手好物联盟推广权限
五、进阶优化：生产级稳定性提升 - 性能优化
异步并发请求：批量获取多关键词 / 多页码时，使用 aiohttp 异步请求，控制并发数≤5（避免频率超限）；
缓存策略：用 Redis 缓存关键词 + 筛选条件的组合结果，缓存有效期 30 分钟，减少重复请求；
分页智能停止：获取第 1 页后，根据 page_total 计算总页码，仅请求有效页码，避免无效请求。 - 数据质量优化
商品去重：按 item_id 去重，避免同一商品多次入库；
异常值过滤：过滤价格为 0、销量为负的异常商品；
字段标准化：统一价格、佣金的小数位数（如保留 2 位小数）。 - 合规与安全
密钥管理：生产环境中，将 app_key 和 app_secret 存储在环境变量或配置中心（如 Nacos），禁止硬编码；
数据合规：获取的商品数据仅用于合规业务，禁止商业化售卖；分销需遵守快手好物联盟规则；
日志审计：详细记录每次接口调用的参数、响应、错误信息，便于合规审计和问题追溯。
六、扩展场景：接口联动与功能升级
联动 item_get 接口：通过 item_search 获取 item_id 后，调用 item_get 获取商品规格、详情页、售后政策等信息；
选品评分模型：结合 销量、佣金比例、店铺评分 构建选品评分公式，自动筛选优质商品；
实时监控：使用 APScheduler 定时调用接口，监控关键词商品的价格、销量变化，触发调价 / 选品告警。
