爱回收商品详情接口全方位对接指南：从认证机制到数据提取最佳实践

​

一、接口对接前置准备

1. 核心参数与权限说明（需平台申请）
   调用爱回收商品详情接口前，需先从平台获取专属凭证，确保请求合法性，关键参数如下：

参数名 类型 说明 是否必选
app_key String 应用唯一标识，爱回收开放平台为每个开发者分配，用于身份识别 是
app_secret String 接口调用密钥，用于生成签名（严禁泄露，建议通过环境变量或配置文件存储） 是
product_id String 回收商品唯一 ID（如手机型号对应 ID，可从爱回收商品列表接口获取） 是
timestamp String 毫秒级时间戳（格式：1719000000000），与平台服务器时间差需≤5 分钟 是
condition_type Integer 设备成色类型（可选，1 = 全新未拆封，2=95 新，3=9 新，4=8 新，5=7 新及以下） 否
sign String 签名信息（按爱回收规则生成，验证请求完整性，防止参数篡改） 是

1. 签名生成规则（爱回收特色逻辑）
   爱回收采用 HMAC-MD5 签名机制，相比普通 MD5 增加密钥二次校验，步骤如下（少一步都可能失败）：

1.参数筛选：仅保留非空的请求参数（含公共参数与condition_type等私有参数），排除sign本身；

2.字典序排序：按参数名首字母字典序升序排列（如app_key在condition_type前，product_id在timestamp前）；

3.字符串拼接：按 “key=value&key=value” 格式拼接排序后的参数（例：app_key=xxx&condition_type=2&product_id=123&timestamp=1719000000000）；

4.密钥拼接：在拼接字符串末尾添加 “&secret=xxx”（xxx 为app_secret，注意前缀有 “&secret=”）；

5.HMAC-MD5 加密：将最终字符串用app_secret作为密钥进行 HMAC-MD5 加密，结果转为小写，即为sign值。

二、核心技术实现（适配回收场景）

1. 接口调用客户端（含成色解析 + 缓存）
   针对爱回收 “估价实时变”“成色类型多” 的特点，客户端需额外处理成色编码映射、估价区间提取、短时效缓存，代码如下：

import requestsimport hashlibimport hmacimport timeimport jsonfrom threading import Lockfrom cachetools import TTLCacheclass AihuishouProductClient: """爱回收商品详情接口客户端（含签名、成色解析、短时效缓存）""" # 爱回收成色编码映射（固定对应关系，避免解析混乱） CONDITION_MAP = { 1: "全新未拆封", 2: "95新（轻微使用痕迹）", 3: "9新（明显使用痕迹，无功能问题）", 4: "8新（较多使用痕迹，无功能问题）", 5: "7新及以下（明显磨损或轻微功能瑕疵）" } def init(self, app_key, app_secret, timeout=8, max_retries=2, cache_ttl=600): """ 初始化客户端 :param app_key: 平台分配app_key :param app_secret: 平台分配app_secret :param timeout: 请求超时时间（秒），默认8秒（回收接口响应较快） :param max_retries: 失败重试次数，默认2次 :param cache_ttl: 缓存有效期（秒），默认10分钟（适配估价实时性） """ self.app_key = app_key self.app_secret = app_secret self.base_url = "https://api.aihuishou.com/product/detail" # 接口固定地址 self.timeout = timeout self.max_retries = max_retries # 短时效缓存：避免频繁调用导致估价数据重复获取 self.cache = TTLCache(maxsize=1000, ttl=cache_ttl) self.cache_lock = Lock() # 缓存操作线程锁 def _generate_sign(self, params): """生成爱回收HMAC-MD5签名""" # 1. 筛选非空参数并字典序排序 valid_params = {k: v for k, v in params.items() if v is not None} sorted_params = sorted(valid_params.items(), key=lambda x: x[0]) # 2. 拼接"key=value&key=value"格式 param_str = "&".join([f"{k}={v}" for k, v in sorted_params]) # 3. 追加"&secret=app_secret" sign_str = f"{param_str}&secret={self.app_secret}" # 4. HMAC-MD5加密（密钥为app_secret） hmac_obj = hmac.new( self.app_secret.encode("utf-8"), sign_str.encode("utf-8"), hashlib.md5 ) return hmac_obj.hexdigest().lower() def _get_cache_key(self, product_id, condition_type=None): """生成缓存键（区分商品ID和成色类型）""" cond_suffix = f"_cond{condition_type}" if condition_type else "default" return f"aihuishou{product_id}{cond_suffix}" def get_product_detail(self, product_id, condition_type=None, use_cache=True): """ 核心方法：获取爱回收商品详情（含估价、成色、回收方式） :param product_id: 回收商品ID :param condition_type: 设备成色类型（可选，见CONDITION_MAP） :param use_cache: 是否使用缓存（默认启用，实时场景可关闭） :return: 结构化商品数据（None表示失败） """ # 1. 先查缓存（避免重复请求） if use_cache: cache_key = self._get_cache_key(product_id, condition_type) with self.cache_lock: if cache_key in self.cache: print(f"[缓存命中] 商品{product_id}（成色：{condition_type}）") return self.cache[cache_key] # 2. 构建基础请求参数 base_params = { "app_key": self.app_key, "product_id": product_id, "timestamp": str(int(time.time() * 1000)), # 毫秒级时间戳 "condition_type": condition_type # 可选参数，非空才传入 } # 过滤None值（避免参数格式错误） base_params = {k: v for k, v in base_params.items() if v is not None} # 3. 生成签名并添加到参数 base_params["sign"] = self._generate_sign(base_params) # 4. 发送请求（带重试机制） retry_count = 0 while retry_count < self.max_retries: try: response = requests.get( url=self.base_url, params=base_params, headers={"User-Agent": "AihuishouProductClient/1.0"}, timeout=self.timeout ) response.raise_for_status() # 捕获4xx/5xx错误 # 5. 解析JSON响应 try: result = response.json() except json.JSONDecodeError: print(f"商品{product_id}：响应非JSON格式，解析失败") retry_count += 1 continue # 6. 处理业务错误（爱回收code=200为成功） if result.get("code") != 200: error_msg = result.get("msg", "未知错误") print(f"商品{product_id}：接口错误 - {error_msg}（code:{result.get('code')}）") # 签名/参数错误无需重试 if result.get("code") in [401, 402]: # 401=签名错，402=参数错 return None retry_count += 1 continue # 7. 解析回收特色数据 parsed_data = self._parse_recycle_data(result.get("data", {}), condition_type) if not parsed_data: print(f"商品{product_id}：数据解析为空，跳过") return None # 8. 写入缓存 if use_cache: with self.cache_lock: self.cache[cache_key] = parsed_data return parsed_data except requests.exceptions.RequestException as e: print(f"商品{product_id}：请求异常 - {str(e)}") retry_count += 1 time.sleep(1) # 重试前休眠1秒 print(f"商品{product_id}：超过{self.max_retries}次重试，获取失败") return None def _parse_recycle_data(self, raw_data, condition_type): """解析爱回收回收特色数据（核心：估价、成色、回收方式）""" if not isinstance(raw_data, dict): return None # 1. 基础商品信息（设备型号、品牌、规格） base_info = { "product_id": raw_data.get("productId", ""), "brand": raw_data.get("brandName", ""), # 如"苹果" "model": raw_data.get("modelName", ""), # 如"iPhone 15 Pro" "spec": raw_data.get("specInfo", ""), # 如"256GB·黑色" "release_year": raw_data.get("releaseYear", "") # 发布年份（回收估价参考） } # 2. 估价信息（区分不同成色的估价区间） price_info = self._parse_price(raw_data.get("priceRange", {}), condition_type) # 3. 回收方式与服务（上门/邮寄、质检周期） service_info = { "recycle_methods": [ "上门回收" if method == 1 else "邮寄回收" for method in raw_data.get("recycleMethods", []) ], "inspection_cycle": raw_data.get("inspectionCycle", "24小时内"), # 质检周期 "payment_time": raw_data.get("paymentTime", "质检通过后2小时内") # 打款时间 } # 4. 成色说明（当前查询成色+支持的成色列表） condition_info = { "current_condition": self.CONDITION_MAP.get(condition_type, "未指定"), "supported_conditions": [ {"code": k, "name": v} for k, v in self.CONDITION_MAP.items() ] } return { "base_info": base_info, "price_info": price_info, "service_info": service_info, "condition_info": condition_info, "parse_time": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()) } def _parse_price(self, raw_price, condition_type): """解析估价信息（爱回收按成色返回不同估价区间）""" if not raw_price: return {"price_range": "未知", "currency": "人民币"} # 若指定成色，优先取对应成色估价；否则取默认区间 if condition_type and str(condition_type) in raw_price: price = raw_price[str(condition_type)] return { "price_range": f"{price.get('min')}-{price.get('max')}元", "currency": "人民币", "note": "按指定成色计算" } else: # 默认取全成色区间（min取最小，max取最大） all_prices = list(raw_price.values()) min_total = min([p.get('min', 0) for p in all_prices]) max_total = max([p.get('max', 0) for p in all_prices]) return { "price_range": f"{min_total}-{max_total}元", "currency": "人民币", "note": "全成色区间（指定成色可获取更精准估价）" }

三、实战示例（贴合回收业务场景）

1. 单商品精准估价查询（指定成色）

def single_product_demo(): """单商品查询示例：查iPhone 15 Pro 256GB的95新估价""" # 1. 替换为自身的app_key和app_secret（从爱回收开放平台申请） APP_KEY = "your_aihuishou_app_key" APP_SECRET = "your_aihuishou_app_secret" # 2. 目标商品ID（假设iPhone 15 Pro 256GB的product_id为10086） TARGET_PRODUCT_ID = "10086" # 3. 指定成色：95新（对应condition_type=2） TARGET_CONDITION = 2 # 4. 初始化客户端（缓存10分钟，适配估价实时性） client = AihuishouProductClient( app_key=APP_KEY, app_secret=APP_SECRET, cache_ttl=600 ) # 5. 获取并打印详情 print(f"开始查询商品ID {TARGET_PRODUCT_ID}（{client.CONDITION_MAP[TARGET_CONDITION]}）...") product_detail = client.get_product_detail( product_id=TARGET_PRODUCT_ID, condition_type=TARGET_CONDITION ) if product_detail: print("\n=== 爱回收商品详情 ===") print(f"设备型号：{product_detail['base_info']['brand']} {product_detail['base_info']['model']}") print(f"规格配置：{product_detail['base_info']['spec']}") print(f"查询成色：{product_detail['condition_info']['current_condition']}") print(f"精准估价：{product_detail['price_info']['price_range']}") print(f"回收方式：{', '.join(product_detail['service_info']['recycle_methods'])}") print(f"质检周期：{product_detail['service_info']['inspection_cycle']}") else: print(f"\n商品{TARGET_PRODUCT_ID}详情获取失败")if name == "main": single_product_demo()

1. 批量商品回收数据采集（多型号 + 多成色）

from concurrent.futures import ThreadPoolExecutor, as_completeddef batch_product_demo(): """批量采集示例：多型号+多成色组合查询""" APP_KEY = "your_aihuishou_app_key" APP_SECRET = "your_aihuishou_app_secret" # 批量任务：(product_id, condition_type) 组合 BATCH_TASKS = [ ("10086", 2), # iPhone 15 Pro 256GB - 95新 ("10087", 3), # 华为Mate 60 Pro 512GB - 9新 ("10088", 4), # 小米14 256GB - 8新 ("10089", 1) # 三星S24 Ultra 512GB - 全新 ] MAX_WORKERS = 2 # 并发数（爱回收接口建议≤2，避免频率限制） # 初始化客户端 client = AihuishouProductClient(APP_KEY, APP_SECRET) batch_result = [] print(f"开始批量采集 {len(BATCH_TASKS)} 个商品回收数据（并发：{MAX_WORKERS}）...") # 多线程提交任务 with ThreadPoolExecutor(max_workers=MAX_WORKERS) as executor: future_map = { executor.submit(client.get_product_detail, task[0], task[1]): task for task in BATCH_TASKS } # 处理结果 for future in as_completed(future_map): product_id, cond_type = future_map[future] try: data = future.result() if data: batch_result.append(data) print(f"✅ 商品{product_id}（{client.CONDITION_MAP[cond_type]}）采集成功") else: print(f"❌ 商品{product_id}（{client.CONDITION_MAP[cond_type]}）采集失败") except Exception as e: print(f"⚠️ 商品{product_id}处理异常：{str(e)}") # 输出批量统计 print(f"\n=== 批量采集完成 ===") print(f"总任务数：{len(BATCH_TASKS)}") print(f"成功数：{len(batch_result)}") print(f"失败数：{len(BATCH_TASKS) - len(batch_result)}")# 运行批量示例# if name == "main":# batch_product_demo()

四、回收场景专属避坑指南

1. 成色编码别搞混：固定映射是关键
   •爱回收成色condition_type为整数编码（1-5），而非文字，需用CONDITION_MAP映射成可读文字（如 2→95 新）；

•若接口返回 “成色类型不支持”，检查condition_type是否在 1-5 范围内（部分老机型仅支持 3-5 成色）。

•

1. 估价数据别缓存太久：10 分钟是上限
   •回收估价受市场波动影响（如新机发布后旧机估价下跌），缓存时间建议≤10 分钟，实时场景（如用户实时查询）可关闭缓存；

•缓存键需包含product_id+condition_type（同一商品不同成色估价不同，避免缓存污染）。

•

1. 回收方式字段要适配：枚举值会更新
   •爱回收recycleMethods返回整数列表（1 = 上门，2 = 邮寄），若新增 “门店回收”（如 3 = 门店），需及时更新_parse_recycle_data中的映射逻辑；

•部分偏远地区不支持上门回收，需在业务层判断recycle_methods是否包含 “上门回收”。

•

1. 时间戳别踩坑：毫秒级 + 时差控制
   •爱回收要求时间戳为毫秒级（普通接口多为秒级），需用int(time.time() * 1000)生成；

•服务器时间为 UTC+8，本地时间若偏差超过 5 分钟，会返回 “时间戳无效”，需同步本地时间。

•

五、常见问题快速排查
问题现象 可能原因 解决办法
签名错误（code=401） 1. 签名时漏加 “&secret=xxx”；2. app_secret 错 1. 检查_generate_sign中是否有&secret={self.app_secret}；2. 核对 app_secret
估价区间为空 1. product_id 无效；2. 该机型暂不支持回收 1. 在爱回收官网验证 product_id 是否存在；2. 确认机型是否在回收列表中
缓存不生效 1. 缓存键未包含 condition_type；2. 缓存锁未加 1. 检查_get_cache_key是否拼接成色后缀；2. 确保缓存读写加cache_lock
批量调用部分失败 1. 频率超限；2. 个别商品 ID 无效 1. 减少并发数至 1-2，或增加请求间隔；2. 单独测试失败的 product_id 要是对接时卡壳 —— 不管是成色数据解析懵了，还是签名总踩坑，随时喊小编唠！评论区留个暗号（比如 “爱回收接口求助”），小编秒回，手把手帮你捋明白～毕竟回收接口的 “成色”“估价” 这些小细节，多聊两句就能少走弯路呀～
​