京东商品详情API技术解析与落地应用（含标准JSON示例）

原创

用户1597063760

发布于 2026-08-24 17:37:35

500

文章被收录于专栏：经验经验

摘要：在跨境 ERP 开发、跨平台铺货、竞品价格监控、选品数据分析、CPS 导购业务场景，经常需要获取京东完整商品结构化数据。jd.item_get京东商品详情 API，传入商品 SKU 编号，返回商品基础信息、SKU 规格、图集、参数属性、促销、店铺、自营标识等完整业务数据。本文从接口能力、请求参数、返回字段解析、标准 JSON 样例、业务处理流程、开发踩坑、业务场景完整讲解，适合电商后端、ERP、数据采集开发者参考。

一、接口概述

jd.item_get京东商品详情 API，核心入参为商品num_iid（京东 SKU 编号），输出完整商品详情 JSON 数据，支持京东自营、第三方店铺、京东国际商品查询。

接口简介

接口名称：jd.item_get（京东商品详情API，taobaoapi2014前往体验）

请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）

接口版本：2.0

调用限制：存在单秒频次、每日调用配额，高频场景需做限流、缓存处理。

核心作用：根据商品 ID，获取商品标题、价格、SKU、库存、图文、类目、销量、规格属性等全量详情数据。

接口能力覆盖

商品元数据：标题、促销价、市场价、销量、评价数、发货地
多媒体资源：主图、轮播图集、商品详情 HTML
SKU 规格集合：各规格售价、库存、规格文本、规格图片
属性参数：品牌、类目、材质、规格参数
店铺信息：店铺 ID、店铺名称、是否京东自营
营销促销：满减、优惠券、券后价、活动时间

二、核心请求入参

参数	类型	必填	说明
num_iid	bigint	是	京东商品 SKU 编号，核心入参
area	string	否	地区编码，不同地区库存、售价存在差异，不传默认北京地区数据
fields	string	否	指定返回字段，按需裁剪，减小返回包体积

三、返回数据结构解析

顶层响应结构

字段	类型	说明
code	int	0调用成功；非 0 代表异常错误码
message	string	提示信息，成功返回ok，失败返回错误描述
data	object	商品详情业务主体对象

data 主体核心字段

字段	类型	说明
num_iid	bigint	京东 SKU 商品 ID
title	string	商品完整标题
price	float	当前促销售卖价
original_price	float	划线市场价，无则为 0
sales	int	近 30 天销量
comment_count	int	商品总评价数量
good_rate	string	商品好评率
pic_url	string	商品主图 URL
images	array[string]	全部轮播图片数组
desc	string	商品详情 HTML 源码
province	string	发货省份
city	string	发货城市
shop_id	bigint	店铺 ID
seller_nick	string	店铺名称
is_self	boolean	true = 京东自营，false = 第三方商家店铺
cat_id	int	三级类目 ID
cat_name	string	完整类目名称
brand	object	品牌对象，brandId、brandName 品牌编号与品牌名称
product_params	array[object]	商品参数集合 {"name":"材质","value":"金属"}

sku_list SKU 子数组（data.sku_list）

多规格商品返回，单规格商品数组长度为 1。

字段	类型	说明
sku_id	bigint	子 SKU 唯一编号
spec_text	string	规格组合文本，例黑色 128G
sku_price	float	该规格售卖价格
sku_stock	int	该规格可用库存
sku_img	string	规格图，部分商品为空

promotion_info 促销信息（data.promotion_info）

字段	类型	说明
promotion_desc	string	满减活动描述
coupon_price	float	可抵扣优惠券金额
promotion_start	string	活动开始时间
promotion_end	string	活动结束时间

四、标准 JSON 返回示例

{
    "code": 0,
    "message": "ok",
    "data": {
        "num_iid": 100089765432,
        "title": "无线蓝牙耳机主动降噪长续航入耳式耳机",
        "price": 199.00,
        "original_price": 299.00,
        "sales": 8620,
        "comment_count": 32600,
        "good_rate": "97.6%",
        "pic_url": "https://img10.360buyimg.com/n1/demo.jpg",
        "images": [
            "https://img10.360buyimg.com/n1/demo1.jpg",
            "https://img10.360buyimg.com/n1/demo2.jpg"
        ],
        "desc": "<p>主动降噪，40小时综合续航，蓝牙5.4</p>",
        "province": "广东",
        "city": "深圳",
        "shop_id": 100012389,
        "seller_nick": "数码官方自营旗舰店",
        "is_self": true,
        "cat_id": 737,
        "cat_name": "数码>耳机>蓝牙耳机",
        "brand": {
            "brandId": 2365,
            "brandName": "数码先锋"
        },
        "product_params": [
            {"name":"蓝牙版本","value":"5.4"},
            {"name":"续航时间","value":"40小时"}
        ],
        "sku_list": [
            {
                "sku_id": 10008976543201,
                "spec_text": "星空黑",
                "sku_price": 199.00,
                "sku_stock": 860,
                "sku_img": ""
            },
            {
                "sku_id": 10008976543202,
                "spec_text": "珍珠白",
                "sku_price": 199.00,
                "sku_stock": 620,
                "sku_img": ""
            }
        ],
        "promotion_info": {
            "promotion_desc": "满150减20",
            "coupon_price": 20.00,
            "promotion_start": "2026‑08‑01 00:00:00",
            "promotion_end": "2026‑08‑31 23:59:59"
        }
    }
}

五、完整业务处理流程

传入商品num_iid，可选传入地区area，调用jd.item_get接口获取 JSON 数据；
判断顶层code状态码，捕获调用异常；
解析data主体，提取标题、价格、图集、类目品牌参数；
循环解析sku_list数组，保存每个规格的 sku_id、价格、库存；
图片资源处理：下载京东 CDN 图片转存自有对象存储，解决防盗链 403 问题；
详情 HTML 清洗：过滤京东平台内部跳转标签、埋点代码；
解析promotion_info促销活动，无活动时该对象可能为 null；
清洗完成后入库，供给 ERP、铺货、价格监控、导购业务模块。

六、开发高频踩坑总结

SPU 与 SKU 混淆 京东查询必须使用 SKU 编号，SPU 拿不到独立规格价格库存；业务系统以sku_id作为规格主键，遍历 sku_list 数组，不要直接取下标 0。
地区带来价格库存差异 不传 area 默认返回北京地区数据，不同省份库存、售价会不一样，做真实业务建议传入业务目标地区编码。
图片防盗链问题 京东 CDN 图片带有防盗链，直接引用一段时间就 403 失效；业务系统必须下载迁移图片资源。
promotion_info 空值兼容 商品无活动促销时，promotion_info会返回 null，解析代码必须做空判断，防止程序崩溃。
商品下架、删除状态 商品下架、删除接口返回非 0 错误码，程序捕获异常，标记商品失效，不要直接抛出程序崩溃。
接口限流与缓存策略 批量同步大量商品，接入任务队列控制 QPS；标题图片类静态数据增加缓存，价格库存短周期更新，减少接口调用量，避免 429 限流报错。
自营标识判断is_self字段区分京东自营与第三方商家，比价、选品业务经常需要过滤自营商品。

七、Python 简易调用伪代码

def get_jd_item_detail(num_iid, area=""):
    resp = call_jd_item_get_api(num_iid=num_iid, area=area)
    if resp.get("code") != 0:
        print("接口调用失败", resp.get("message"))
        return None
    item_data = resp.get("data")
    # 数据清洗、图片下载、入库
    save_jd_goods_db(item_data)
    return item_data

detail = get_jd_item_detail(100089765432)

八、落地业务场景

ERP 系统跨平台搬家、商品刊登，完整获取京东货源素材
竞品监控系统，定时抓取商品价格、库存变动
CPS 导购分销业务，读取 SKU、券后促销信息
选品系统，采集品牌、参数、评价数据构建货源库
市场数据分析，统计类目价格、销量、好评率分布

九、总结

jd.item_get京东商品详情 API 是京东电商开发的核心接口，可以拿到商品完整结构化数据。开发的难点不在于简单接口调用，而在于 SKU 解析、地区价格差异处理、图片防盗链迁移、HTML 详情清洗、空值异常捕获、限流缓存策略。处理好以上问题，接口可以稳定支撑 ERP 铺货、竞品监控、导购分销、选品分析等各类电商业务。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

开发经验

#京东API

#京东商品详情API