实战代码解析：item_get——获取某鱼商品详情接口

适用接口：goodfish.item_get / xianyu.item.get

更新日期：2026-01-23

一、接口定位

item_get 是某鱼（闲鱼）开放平台提供的商品粒度 详情接口。

输入一个 item_id，即可一次性拿到标题、价格、成色、卖家、交易状态、图文、视频等 30+ 维度数据，平均响应 <200 ms，适合比价、选品、风控、内容聚合等场景。

二、核心能力速览

能力	说明
实时性	价格、库存、交易状态与源站同步，缓存 ≤1 min
二手特征	成色（全新/9 成新）、验货担保、是否包邮、所在地
卖家维度	昵称、信用等级、好评率、历史成交（需高阶权限）
媒体资源	主图、多图、视频 URL、详情 HTML
同款比价	可扩展返回同品类价格区间（需额外权限）

三、请求结构

1. 公共参数（必填）

method=xianyu.item.get
app_key=xxx
timestamp=毫秒级时间戳
sign=HMAC-SHA256 小写 32 位
version=2.0
format=json

2. 业务参数

item_id：商品 ID，可从 https://2.taobao.com/item.htm?id={item_id} 提取
fields：按需返回字段，逗号分隔，例如 title,price,condition,seller_info

签名有效期 5 min；fields 不传则返回全字段，体积较大。

四、返回字段（常用）

字段	类型	示例	说明
title	string	"iPhone 14 128G 星光色"	商品标题
price	object	{"current": 4200, "original": 4999}	当前价/原价
condition	string	"九成新"	成色枚举
status	string	"onsale"	在售/已售/下架
pics	array	["//img.alicdn.com/xxx.jpg", ...]	多图 URL
video_url	string	"//cloud.video.taobao.com/..."	视频直链
seller_nick	string	"小鱼不吃鱼"	卖家昵称
seller_level	string	"3冠"	信用等级
location	string	"浙江杭州"	商品所在地
guarantee	array	["验货担保", "七天无理由"]	保障标签
desc	string	HTML	图文详情
same_items	array	[{item_id, price, seller_nick}]	同款列表（高阶）

五、Python 3 实战（官方推荐）

python 复制代码

import time, requests, hashlib, hmac, urllib.parse

APP_KEY = '你的app_key'
APP_SECRET = '你的app_secret'
ITEM_ID = '698765432109876543'  # 示例商品

def sign(params: dict) -> str:
    """HMAC-SHA256 小写 32 位"""
    params = {k: v for k, v in params.items() if v is not None}
    query = '&'.join([f'{k}={urllib.parse.quote(str(v), safe="")}'
                      for k, v in sorted(params.items())])
    raw = f'{APP_SECRET}{query}{APP_SECRET}'
    return hmac.new(APP_SECRET.encode(), raw.encode(),
                    digestmod=hashlib.sha256).hexdigest().lower()

def item_get(item_id, fields=None):
    params = {
        'method': 'xianyu.item.get',
        'app_key': APP_KEY,
        'timestamp': int(time.time() * 1000),
        'version': '2.0',
        'format': 'json',
        'item_id': item_id,
        'fields': fields or ''
    }
    params['sign'] = sign(params)
    url = 'https://api.xianyu.com/router/rest'
    resp = requests.post(url, data=params, timeout=10)
    result = resp.json()
    if result.get('code') != 200:
        raise RuntimeError(result.get('message'))
    return result['data']['item']

if __name__ == '__main__':
    detail = item_get(ITEM_ID, 'title,price,condition,pics,video_url,seller_nick')
    print('标题:', detail['title'])
    print('价格:', detail['price']['current'])
    print('成色:', detail['condition'])
    print('视频:', detail.get('video_url'))

六、Java 17 快速版本（OkHttp + FastJSON2）

java 复制代码

public class XianyuItemGet {
    private static final String APP_KEY  = "你的app_key";
    private static final String APP_SEC  = "你的app_secret";
    private static final String GATEWAY  = "https://api.xianyu.com/router/rest";

    public static JSONObject getItem(String itemId) throws Exception {
        Map<String, String> params = new HashMap<>();
        params.put("method", "xianyu.item.get");
        params.put("app_key", APP_KEY);
        params.put("timestamp", String.valueOf(System.currentTimeMillis()));
        params.put("version", "2.0");
        params.put("format", "json");
        params.put("item_id", itemId);
        params.put("sign", sign(params));

        FormBody.Builder body = new FormBody.Builder();
        params.forEach(body::add);
        Request req = new Request.Builder()
                .url(GATEWAY)
                .post(body.build())
                .build();
        try (Response resp = new OkHttpClient().newCall(req).execute()) {
            JSONObject json = JSON.parseObject(resp.body().string());
            if (!"200".equals(json.getString("code")))
                throw new RuntimeException(json.getString("message"));
            return json.getJSONObject("data").getJSONObject("item");
        }
    }

    private static String sign(Map<String, String> params) {
        String query = params.entrySet().stream()
                .sorted(Map.Entry.comparingByKey())
                .map(e -> e.getKey() + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
                .collect(Collectors.joining("&"));
        String raw = APP_SEC + query + APP_SEC;
        return Hex.encodeHexString(DigestUtils.sha256(raw)).toLowerCase();
    }

    public static void main(String[] args) throws Exception {
        JSONObject item = getItem("698765432109876543");
        System.out.println("标题：" + item.getString("title"));
        System.out.println("价格：" + item.getJSONObject("price").getBigDecimal("current"));
    }
}

七、调用限额 & 反爬策略

权限等级	日调用量	频率	说明
个人测试	100/IP	1 qps	仅基础字段
企业基础	10 k/IP	5 qps	含卖家等级
企业高级	100 k/IP	20 qps	含同款比价、成交记录

风控建议

本地缓存 60 s，避免重复拉取
指数退避重试（403/504）
随机 UA + 调用间隔 1~3 s
不得抓取卖家手机号、微信号等隐私字段，否则直接封权

八、1 分钟接入清单

注册闲鱼开放平台 → 创建应用 → 申请 xianyu.item.get 权限
白名单配置：出口 IP、线上域名
把 app_key / app_secret 放入配置中心，禁止硬编码
复制上方 Python/Java 代码，改 3 处密钥即可跑通
生产环境打开日志：item_id、耗时、code，保留 7 天备审

九、小结

item_get 让二手数据也能像新品一样标准化：

成色、担保、所在地一目了然
视频、多图、同款一键关联
毫秒响应 + 阶梯权限，既适合个人脚本，也支撑百万级比价平台