闲鱼 item_get 接口是获取闲鱼平台二手商品详情的核心接口，支持通过商品 ID查询商品标题、价格、成色、卖家信息、交易状态、图文描述、物流方式等全量数据，适配二手商品比价、交易监控、数据聚合、商家运营等场景。该接口采用HTTP/HTTPS + 签名认证机制，权限分级严格，数据实时性强。本攻略从接口认知、权限获取、实操对接、调试排错到生产级优化，提供结构化全链路指导，兼顾入门易用性与企业级稳定性。
一、接口核心认知：功能与适配场景
1. 接口定位与核心价值
2. 核心参数与返回字段
（1）请求参数（公共参数 + 私有参数，POST/GET 均可）
（2）返回核心字段（按业务场景分类）
3. 接口限制与注意事项
二、对接前准备：权限与环境搭建
1. 获取接口权限（官方唯一合规路径）
2. 技术环境准备
（1）支持语言与协议
（2）必备工具与依赖
三、实操步骤：接口对接全流程（Python 示例）
步骤 1：理解签名认证规则（核心，必掌握）
步骤 2：完整代码实现（含签名生成 + 接口调用 + 数据标准化）
（1）依赖安装
（2）Python 代码实现
import requests
import hmac
import hashlib
import time
import pandas as pd
import logging
from urllib.parse import urlencode
# 日志配置
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
handlers=[logging.FileHandler("xianyu_item_get.log"), logging.StreamHandler()]
)
# 配置信息（替换为你的阿里开放平台信息）
CONFIG = {
"app_key": "你的app_key",
"app_secret": "你的app_secret",
"api_url": "https://gw.api.taobao.com/router/rest", # 闲鱼接口网关
"version": "v2"
}
def generate_sign(params: dict, app_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 = urlencode(sorted_params, encoding="utf-8") + f"&app_secret={app_secret}"
# 4. HMAC-SHA256加密，生成小写签名
sign = hmac.new(
app_secret.encode("utf-8"),
param_str.encode("utf-8"),
hashlib.sha256
).hexdigest().lower()
return sign
def standardize_item_data(raw_item: dict) -> dict:
"""标准化商品详情数据，统一输出格式"""
# 解析商品成色
condition_map = {
"new": "全新",
"like_new": "九成新",
"very_good": "八成新",
"good": "七成新",
"acceptable": "六成新及以下"
}
condition = condition_map.get(raw_item.get("condition", ""), "未知成色")
# 解析商品状态
status_map = {
"onsale": "在售",
"soldout": "已售",
"offline": "下架"
}
status = status_map.get(raw_item.get("status", ""), "未知状态")
# 解析上架时间
valid_time = raw_item.get("valid_time", 0)
valid_time_str = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(valid_time/1000)) if valid_time else ""
return {
"商品ID": raw_item.get("item_id", ""),
"商品标题": raw_item.get("title", ""),
"商品主图": raw_item.get("pic_url", ""),
"商品标价(元)": float(raw_item.get("price", 0)),
"原价(元)": float(raw_item.get("original_price", 0)),
"商品成色": condition,
"商品类目": raw_item.get("category", ""),
"商品状态": status,
"已售数量": int(raw_item.get("sales", 0)),
"物流方式": raw_item.get("logistics", ""),
"商品所在地": raw_item.get("location", ""),
"上架时间": valid_time_str,
"保障服务": ",".join(raw_item.get("guarantee", [])),
"卖家昵称": raw_item.get("seller_nick", ""),
"卖家等级": raw_item.get("seller_level", ""),
"卖家好评率": f"{raw_item.get('seller_score', 0)}%",
"请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
}
def xianyu_item_get(item_id: str, fields: str = None) -> dict:
"""调用闲鱼item_get接口获取商品详情"""
# 1. 构建请求参数
params = {
"app_key": CONFIG["app_key"],
"method": "xianyu.item.get", # 闲鱼item_get接口方法名
"timestamp": str(int(time.time() * 1000)),
"version": CONFIG["version"],
"item_id": item_id
}
# 补充字段筛选参数
if fields:
params["fields"] = fields
# 2. 生成签名
params["sign"] = generate_sign(params, CONFIG["app_secret"])
try:
# 3. 发送POST请求（闲鱼接口推荐POST）
response = requests.post(
url=CONFIG["api_url"],
data=params,
headers={"Content-Type": "application/x-www-form-urlencoded; charset=utf-8"},
timeout=10,
verify=True
)
response.raise_for_status()
result = response.json()
# 4. 解析响应结果
if result.get("error_response"):
error_msg = f"{result['error_response']['code']}: {result['error_response']['msg']}"
logging.error(f"接口调用失败（商品ID：{item_id}）：{error_msg}")
return {"success": False, "error_msg": error_msg, "data": {}}
raw_item = result.get("item_get_response", {}).get("item", {})
if not raw_item:
logging.warning(f"无商品数据返回（商品ID：{item_id}）")
return {"success": False, "error_msg": "无商品数据", "data": {}}
# 5. 标准化数据
standard_data = standardize_item_data(raw_item)
return {
"success": True,
"data": standard_data,
"error_msg": ""
}
except requests.exceptions.RequestException as e:
logging.error(f"网络请求异常（商品ID：{item_id}）：{str(e)}")
return {"success": False, "error_msg": f"网络异常：{str(e)}", "data": {}}
except Exception as e:
logging.error(f"数据解析异常（商品ID：{item_id}）：{str(e)}")
return {"success": False, "error_msg": f"解析异常：{str(e)}", "data": {}}
# 调用示例
if __name__ == "__main__":
# 替换为真实的闲鱼商品ID
item_id = "698765432109876543"
# 按需指定返回字段，减少响应体积
fields = "title,price,condition,status,seller_nick,seller_score"
result = xianyu_item_get(item_id=item_id, fields=fields)
if result["success"]:
print("闲鱼商品详情：")
for k, v in result["data"].items():
print(f"{k}: {v}")
# 保存为Excel
df = pd.DataFrame([result["data"]])
df.to_excel("xianyu_item_detail.xlsx", index=False)
else:
print(f"获取失败：{result['error_msg']}")