摘要
很多开发者想要搭建闲鱼二手商品监控、二手选品系统，会优先寻找「关键词搜品、单品详情、整店抓取」三类 能力。但很多人踩坑：混淆闲鱼 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 |
四、业务拓展联动其他 ISV 接口
闲鱼 ISV 订单接口：读取托管店铺订单，完成 ERP 进销存闭环；
商品变更消息回调：订阅商品上下架、价格变更推送，减少轮询调用；
AI 能力：标题、描述改写，生成二手商品上架文案。
