摘要：二手电商业务开发过程中，经常需要获取闲鱼商品完整结构化数据，用于二手比价、竞品监控、货源分析、二手机器人选品、风险识别等场景。goodfish.item_get（闲鱼商品详情 API）可根据商品num_iid获取标题、价格、成色、图文描述、卖家信用、物流、浏览想要等全量字段。
一、接口基础信息
接口名称：goodfish.item_get（闲鱼商品详情 API，taobaoapi2014前往体验）
请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）
请求方式：GET / POST
核心功能：传入商品唯一 ID num_iid，返回闲鱼商品完整详情数据
必传私有参数：num_iid（商品 ID，从商品 URL 提取）
适用业务场景：二手商品价格监控、同款比价、卖家信用评估、货源采集入库、违规商品识别、二手选品系统开发。
二、核心请求参数
参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 是 | 应用密钥 |
secret | string | 是 | 密钥用于生成签名 |
num_iid | string | 是 | 闲鱼商品唯一 ID |
timestamp | long | 是 | 毫秒时间戳 |
sign | string | 是 | 参数签名校验 |
fields | string | 否 | 按需指定返回字段，逗号分隔 |
三、标准 JSON 返回示例
{
"code": 200,
"msg": "success",
"data": {
"item": {
"num_iid": "750828541223",
"title": "二手iPhone 14 256G 99新 无拆无修",
"price": "3899.00",
"original_price": "5999.00",
"currency": "CNY",
"condition": "99新",
"location": "广东深圳",
"created_time": "2026-08-10 14:22:10",
"status": "on_sale",
"post_type": "包邮",
"description": "个人自用iPhone14，256G，外观几乎无划痕，功能全部正常，无拆无修，配件齐全。",
"category_id": "100101",
"category_name": "手机>苹果手机",
"brand": "Apple",
"model": "iPhone 14",
"params": {
"存储容量": "256GB",
"颜色": "黑色",
"是否过保": "已过保"
},
"item_imgs": [
"https://img.alicdn.com/bao/uploaded/i2/O1CN01xxxx.jpg",
"https://img.alicdn.com/bao/uploaded/i2/O1CN01yyyy.jpg"
],
"video_url": "https://cloud.video.taobao.com/play/u/xxxx",
"sales": {
"view_count": 1268,
"want_count": 86,
"total_sales": 0
},
"express_fee": "0.00",
"seller": {
"seller_id": "s_12345678",
"nick": "数码个人卖家",
"credit_level": "极好",
"good_rate": "98.7%",
"seller_avatar": "https://avatar.xxx.jpg"
}
}
}}四、返回字段解析
外层响应
字段 | 类型 | 说明 |
|---|---|---|
code | int | 200 成功；400 参数错误；403 权限不足；429 限流；500 服务异常 |
msg | string | 返回提示文本 |
data | object | 业务主体对象 |
item 商品主体对象
字段 | 类型 | 说明 |
|---|---|---|
num_iid | string | 商品唯一主键，入库去重核心字段 |
title | string | 商品标题 |
price | string | 当前售价 |
original_price | string | 商品原价，二手商品可能为空 |
condition | string | 成色：全新、99 新、95 新、九成新、八成新等 |
location | string | 商品所在地，用于物流成本评估 |
created_time | string | 商品发布时间 |
status | string | on_sale在售；sold已售出；offline商品下架 |
post_type | string | 包邮 / 自提 / 运费到付 |
description | string | 商品详情富文本描述，需要做 HTML 标签清洗 |
category_id / category_name | string | 类目 ID 与类目名称 |
brand / model | string | 品牌、型号，二手 3C 场景非常关键 |
params | object | 商品规格参数键值对，存储容量、颜色等 |
item_imgs | array[string] | 商品图片 URL 数组 |
video_url | string | 商品视频地址，无视频返回空字符串 |
sales | object | 浏览量、想要数量、销量 |
express_fee | string | 运费金额 |
seller | object | 卖家信息子对象 |
seller 卖家信息子对象
字段 | 类型 | 说明 |
|---|---|---|
seller_id | string | 卖家加密 ID |
nick | string | 卖家昵称 |
credit_level | string | 闲鱼信用等级：极好、优秀、良好、一般 |
good_rate | string | 卖家好评率 |
seller_avatar | string | 卖家头像地址 |
五、业务落地开发流程
1.获取商品 ID：通过闲鱼搜索接口拿到num_iid商品 ID 列表；
2.发起接口请求，捕获网络异常、超时异常；
3.状态码判断：非 200 直接记录错误日志；商品下架 / 删除会返回对应错误码；
4.数据清洗：对description去除 HTML 标签；空值做容错；
5.数据标准化入库：以num_iid作为数据库唯一索引，防止重复写入；
6.上层业务使用：比价统计、价格异动监控、二手选品系统、卖家风险分析。
