闲鱼商品详情 API 接口解析（附 JSON 样例）-CRMEB社区

闲鱼商品详情 API 接口解析（附 JSON 样例）

管理

编辑

删除

摘要

在二手 ERP、鱼小铺店铺管理、二手货源监控、商品素材归档等项目开发中，很多开发者希望获取闲鱼商品结构化详情数据。这里有一个核心前提：闲鱼 TOP 开放平台没有对外提供可以随意读取全网任意陌生人商品的通用详情接口。

本文完整解析官方goodfish.item_get接口，包含接口基础信息、请求参数、返回 JSON 样例、字段释义、错误码、开发流程和线上踩坑经验。

一、接口基础信息

1.公共请求参数

参数名	类型	必填	说明
method	string	是	固定值 alibaba.idle.isv.item.query
app_key	string	是	TOP 开放平台分配的 ISV 应用密钥
timestamp	string	是	GMT+8 时区，格式yyyy‑MM‑dd HH:mm:ss；时间误差不可超过 10 分钟
v	string	是	协议版本，固定2.0
sign_method	string	是	签名算法，hmac‑sha256 /md5
sign	string	是	加密生成的签名字符串
session	string	是	店铺托管授权 OAuth session，必填，无托管授权调用直接报错

2.接口基础信息

项目	说明
接口 Method	goodfish.item_get（前往Taobaoapi2014体验）
请求网关	c0b.cc/R4rbK2
请求方式	GET / POST，生产环境推荐 POST
鉴权方式	app_key + app_secret + OAuth session 授权；必须完成店铺托管授权
签名算法	md5 /hmac‑sha256；参数按 ASCII 字典序升序生成 sign 签名
协议版本	v2.0
返回格式	JSON / XML，项目开发优先 JSON
硬性边界	只能查询该应用托管的闲鱼 / 鱼小铺商品；外部陌生人商品直接返回查询失败；需要闲管家 ISV 服务商资质。

3.业务入参

参数名	类型	必填	说明
item_id	long	是	闲鱼商品 ID，来自托管店铺商品列表接口alibaba.idle.isv.item.list.query返回
need_sku	boolean	否	是否返回 SKU 信息，不需要传 false，减少接口响应耗时

二、返回 JSON 样例

{
    "alibaba_idle_isv_item_query_response": {
        "request_id": "req‑20260924101200345678",
        "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"
        }
    }
}

异常返回示例（查询非托管外部商品 / 权限不足）

{
    "error_response": {
        "code":15,
        "msg":"调用失败",
        "sub_code":"TOP_NOT_CURRENT_INSPECT_ITEM",
        "sub_msg":"非当前服务商托管的商品，禁止查询",
        "request_id":"req‑20260924101300876543"
    }
}

三、核心返回字段释义

字段	释义	业务处理提示
item_id	闲鱼商品 ID	业务主键，用于和商品列表接口做数据关联
title	商品标题	二手商品标题，用于展示、本地关键词检索
sub_title	商品副标题	部分商品为空字符串，代码需要判空
status	商品状态	on_sale在售；off_sale下架；delete已删除
quality	成色	全新、99 新、95 新、9 成新、85 新等二手特有字段，部分商品为空
price	售卖价格，字符串类型	业务层转为 Decimal 做成本、利润计算
original_price	原价 / 购入价	二手划线参考价
is_fish_treasure	是否验货宝商品	二手业务核心筛选标识
is_personal	是否个人闲置	区分个人闲置商品与鱼小铺商家货源
main_images	主图图片数组	CDN 防盗链，图片链接不可直接对外引用，需下载转自有对象存储
desc	商品详情 HTML 文本	业务层清洗 HTML 标签，提取纯文本描述
delivery_from	发货地	用于评估物流时效、运费成本预估
freight_type	运费类型	seller_pay包邮，buyer_pay买家承担运费
freight_fee	运费金额	仅买家付运费场景有效
browse_count	浏览量	平台脱敏数据，仅作参考，不能当作真实访问量
want_count	想要数量	用户标记想要人数，用于评估商品热度，脱敏值
created_time	商品发布时间
modified_time	商品最后编辑时间	用于判断商品是否发生变更，做增量同步

四、常见错误码说明

sub_code	错误说明	处理方案
TOP_NOT_CURRENT_INSPECT_ITEM	不是当前服务商托管的商品	官方接口不能访问外部陌生人店铺商品
isv.invalid‑permission	ISV 服务商权限未开通	需要申请闲管家 ISV 服务商资质，普通账号无权限调用
TOP_ITEM_QUERY_FAIL	商品查询失败，商品已删除 / 下架	捕获异常，标记本地商品为失效，停止监控
isv.missing‑parameter:itemId	缺少 item_id 入参	入参校验，保证必传参数不为空
isv.missing‑parameter:session	缺少托管授权 session	引导卖家完成店铺托管授权，获取有效 session 令牌

五、业务拓展联动其他 ISV 接口

goodfish.item_search_shop：托管店铺商品列表接口，批量获取店铺全部 item_id，批量拉取商品详情；

闲鱼 ISV 订单接口：读取托管店铺订goodfish.item_get

单，完成 ERP 进销存业务闭环；

AI 文本处理：对商品标题、描述进行改写，生成二手商品上架文案。

已处理 待处理 {{opt.name}} 已处理 待处理 分析中 投票中 优化中 已优化 已回复 待规划 {{opt.name}} 分析中 投票中 优化中 已优化 已回复 待规划 闲鱼商品详情 API 接口解析（附 JSON 样例）

摘要