摘要：二手电商业务开发过程中，经常需要获取闲鱼商品完整结构化数据，用于二手比价、竞品监控、货源分析、二手机器人选品、风险识别等场景。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 返回示例
代码语言：javascript
{ "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 | 卖家头像地址 |
五、业务落地开发流程
- 获取商品 ID：通过闲鱼搜索接口拿到 num_iid 商品 ID 列表；
- 发起接口请求，捕获网络异常、超时异常；
- 状态码判断：非 200 直接记录错误日志；商品下架 / 删除会返回对应错误码；
- 数据清洗：对 description 去除 HTML 标签；空值做容错；
- 数据标准化入库：以 num_iid 作为数据库唯一索引，防止重复写入；
- 上层业务使用：比价统计、价格异动监控、二手选品系统、卖家风险分析。
