摘要
在二手 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 文本处理：对商品标题、描述进行改写，生成二手商品上架文案。
