一文吃透闲鱼三大开放 API：关键词搜品 + 单品详情 + 整店抓取，快速搭建二手商品监控平台

原创

用户1597063760

发布于 2026-09-24 09:15:13

1460

文章被收录于专栏：经验经验

摘要

很多开发者想要搭建闲鱼二手商品监控、二手选品系统，会优先寻找「关键词搜品、单品详情、整店抓取」三类能力。但很多人踩坑：混淆闲鱼 ISV 官方接口和逆向抓包接口。

整店商品列表（整店抓取：拉取本托管店铺全部商品 ID）

单品详情查询（alibaba.idle.isv.item.query 根据 item_id 获取单品详情）

店铺内关键词过滤（在自己店铺商品集合内做本地关键词筛选）

本文完整拆解闲鱼 ISV 三大合法能力，对比逆向方案，给出接口参数、JSON 样例、系统架构、开发流程、线上踩坑，帮助开发者正确评估二手监控平台可行性。

一、三大 ISV 能力接口基础信息

三大接口基础信息

能力	接口 Method	能力说明
①整店商品列表（整店抓取）	alibaba.idle.isv.item.list.query	获取当前 session 托管店铺下全部商品基础列表，拿到item_id
②单品详情查询	alibaba.idle.isv.item.query	根据item_id查询单品完整详情、成色、图片、运费等
③店铺内关键词搜品	无平台搜索 API	拿到整店商品列表后，业务服务本地内存 / 数据库做标题关键词过滤

公共请求基础信息

项目	说明
接口名称	goodfish.item_get (前往Taobaoapi2014体验)
请求方式	GET / POST，生产环境推荐 POST
请求网关	c0b.cc/R4rbK2
签名算法	md5 /hmac‑sha256；参数按 ASCII 字典序升序生成 sign 签名
协议版本	v2.0
返回格式	JSON / XML，项目优先 JSON

【整店商品列表】业务入参

参数名	类型	必填	说明
page_no	int	否	页码，起始为 1
page_size	int	否	每页最大 20 条，不可超限
status	string	否	筛选状态：on_sale在售 / off_sale下架；不传返回全部状态

整店列表 JSON 样例

{
    "alibaba_idle_isv_item_list_query_response": {
        "request_id": "req‑20260924141000123456",
        "total":42,
        "page_no":1,
        "page_size":20,
        "item_list":[
            {
                "item_id":"3100123456789",
                "title":"95新无线蓝牙耳机降噪长续航",
                "status":"on_sale",
                "quality":"95新",
                "price":"189.00",
                "is_fish_treasure":true,
                "created_time":"2026‑07‑10 15:30:22"
            },
            {
                "item_id":"3100123456790",
                "title":"机械键盘青轴游戏办公键盘",
                "status":"on_sale",
                "quality":"9成新",
                "price":"129.00",
                "is_fish_treasure":false,
                "created_time":"2026‑07‑12 10:20:11"
            }
        ]
    }
}

【单品详情】业务入参

参数名	类型	必填	说明
item_id	long	是	商品 ID，来自整店列表接口返回
need_sku	boolean	否	是否返回 SKU 信息，不需要传 false 减少耗时

单品详情 JSON 样例

{
    "alibaba_idle_isv_item_query_response": {
        "request_id": "req‑20260924141200345678",
        "item_info": {
            "item_id": "3100123456789",
            "title": "95新 无线蓝牙耳机 降噪长续航",
            "sub_title": "个人闲置，几乎无磨损",
            "status": "on_sale",
            "quality": "95新",
            "price": "189.00",
            "original_price": "399.00",
            "is_fish_treasure": true,
            "is_personal": true,
            "main_images": [
                "https://img1.taobao.org/imgextra/i2/O1CN01xxx1.jpg",
                "https://img1.taobao.org/imgextra/i2/O1CN01xxx2.jpg"
            ],
            "desc": "<p>自用蓝牙耳机，95新，功能全部正常，配件齐全。</p>",
            "delivery_from": "广东深圳",
            "freight_type": "buyer_pay",
            "freight_fee": 12.00,
            "browse_count": 1240,
            "want_count": 86,
            "created_time": "2026‑07‑10 15:30:22",
            "modified_time": "2026‑08‑02 09:10:11"
        }
    }
}

二、核心返回字段释义

字段	释义	业务处理提示
item_id	闲鱼商品 ID	业务主键，列表与详情接口关联主键
title	商品标题	用于本地关键词过滤、展示
status	商品状态	on_sale在售；off_sale下架；delete已删除
quality	成色	全新、99 新、95 新、9 成新等二手特有字段，部分商品为空，需要判空
price	售卖价格字符串	业务层转为 Decimal 做成本计算
is_fish_treasure	是否验货宝商品	二手业务重要筛选标识
main_images	主图数组	CDN 防盗链，必须下载转自有对象存储，不可直接对外引用
freight_type	运费类型	seller_pay包邮，buyer_pay买家付运费
browse_count/want_count	浏览、想要数	平台脱敏数据，仅做参考，不能当作绝对真实热度

三、常见错误码说明

sub_code	错误说明	处理方案
TOP_NOT_CURRENT_INSPECT_ITEM	不是当前服务商托管商品	官方接口不能访问外部陌生人店铺商品
isv.invalid‑permission	ISV 服务商权限未开通	需要闲管家 ISV 服务商资质，普通账号无权限
TOP_ITEM_QUERY_FAIL	商品查询失败，已删除 / 下架	捕获异常，标记本地商品失效，停止监控该商品
isv.missing‑parameter:session	缺少托管授权 session	必须完成店铺托管授权拿到有效 token