爱回收item_search_id（官方常称 “根关键字搜索接口”）是按根关键字（品牌 / 品类 / 型号）检索设备根 ID（品牌 ID / 品类 ID / 型号 ID）的核心入口，采用 POST+HMAC‑SHA256 签名认证，用于快速匹配爱回收设备库中的标准化 ID，为后续item_get_inquir（询价）、item_get_price（价格查询）提供精准索引，适配二手回收、以旧换新、批量估价等场景。本攻略从接口认知、权限获取、全流程代码、调试排错到生产级优化，提供结构化全链路指导，兼顾入门易用性与企业级稳定性，助力高效完成设备 ID 检索与数据聚合对接。
一、接口核心认知：功能与适配场景
1. 接口定位与核心价值
2. 核心参数与返回字段
（1）请求参数（公共 + 私有，POST 表单 / JSON）
（2）返回核心字段（按业务场景分类）
3. 接口限制与注意事项
二、对接前准备：权限与环境搭建
1. 获取接口权限（官方唯一合规路径）
2. 技术环境准备
（1）支持语言与协议
（2）必备工具与依赖
二、对接前准备：权限与环境搭建
1. 获取接口权限（官方唯一合规路径）
2. 技术环境准备
三、实操步骤：接口对接全流程（Python 示例）
步骤 1：理解认证与签名规则
（1）签名生成流程（核心，易出错）
（2）完整代码实现
import requests
import hashlib
import hmac
import time
import pandas as pd
import logging
# 封装好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("aihuishou_item_search_id.log"), logging.StreamHandler()]
)
# 配置（替换为你的信息）
APP_ID = "你的app_id"
APP_SECRET = "你的app_secret"
API_URL = "https://open.aihuishou.com/api/v2/item_search_id"
def generate_sign(params: dict, secret: str) -> str:
"""生成爱回收接口签名（HMAC‑SHA256）"""
# 1. 筛选非空参数，排除sign
filtered_params = {k: v for k, v in params.items() if v and k != "sign"}
# 2. 按参数名ASCII升序排序
sorted_params = sorted(filtered_params.items(), key=lambda x: x[0])
# 3. 拼接字符串
param_str = "&".join([f"{k}={v}" for k, v in sorted_params])
# 4. 添加密钥
param_str += f"&secret={secret}"
# 5. HMAC‑SHA256加密
sign = hmac.new(secret.encode("utf-8"), param_str.encode("utf-8"), hashlib.sha256).hexdigest().lower()
return sign
def standardize_root_data(raw_data: dict) -> dict:
"""标准化根ID数据，统一输出格式"""
return {
"根ID": raw_data.get("root_id", ""),
"根类型": raw_data.get("root_type", ""),
"根名称": raw_data.get("root_name", ""),
"设备类型": raw_data.get("device_type", ""),
"品牌": raw_data.get("brand", ""),
"型号": raw_data.get("model", ""),
"规格描述": raw_data.get("spec", ""),
"请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
}
def aihuishou_item_search_id(
keyword: str,
device_type: str = None,
match_type: str = "fuzzy",
page: int = 1,
page_size: int = 20
) -> dict:
"""调用爱回收item_search_id接口获取根关键字ID"""
# 1. 构建请求参数
timestamp = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
params = {
"app_id": APP_ID,
"timestamp": timestamp,
"version": "v2",
"q": keyword,
"match_type": match_type,
"page": page,
"page_size": min(page_size, 50) # 单次最多50条
}
# 补充分选参数
if device_type:
params["device_type"] = device_type
# 2. 生成签名
params["sign"] = generate_sign(params, APP_SECRET)
# 3. 发送POST请求
try:
response = requests.post(API_URL, data=params, verify=True)
response.raise_for_status()
result = response.json()
if result.get("code") != 0:
logging.error(f"接口返回错误：{result.get('msg')}")
return {"success": False, "error_msg": result.get("msg"), "data": [], "pagination": {}}
# 4. 标准化数据
items = result.get("data", {}).get("items", [])
standard_items = [standardize_root_data(item) for item in items]
pagination = {
"total": result.get("data", {}).get("total", 0),
"page": result.get("data", {}).get("page", 1),
"page_size": result.get("data", {}).get("page_size", 20),
"has_more": result.get("data", {}).get("has_more", False)
}
return {
"success": True,
"data": standard_items,
"pagination": pagination,
"error_msg": ""
}
except requests.exceptions.RequestException as e:
logging.error(f"请求异常：{str(e)}")
return {"success": False, "error_msg": str(e), "data": [], "pagination": {}}
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 调用示例
if __name__ == "__main__":
keyword = "苹果"
device_type = "手机"
result = aihuishou_item_search_id(keyword, device_type=device_type, page_size=10)
if result["success"]:
print(f"获取到 {len(result['data'])} 条根ID数据，总计 {result['pagination']['total']} 条")
for item in result["data"]:
print(f"根ID：{item['根ID']} | 根类型：{item['根类型']} | 根名称：{item['根名称']}")
# 翻页示例：获取下一页
if result["pagination"]["has_more"]:
next_page_result = aihuishou_item_search_id(
keyword,
device_type=device_type,
page=result["pagination"]["page"] + 1,
page_size=10
)
print(f"下一页获取到 {len(next_page_result['data'])} 条根ID数据")
else:
print(f"获取失败：{result['error_msg']}")