京东开放平台（JD Open Platform）提供了一系列店铺商品相关 API，用于实现店铺商品的查询、管理等操作。需特别注意：京东对 API 权限管控严格，商家可查询自身店铺的商品数据或第三方开发者可获取其他店铺的商品数据。本文将从接口选型、权限申请、调用规范、Python 实战等维度，全面讲解京东店铺所有商品 API 的使用。
一、摘要
京东店铺商品 API 属于平台接口体系，核心用于商家查询自身店铺下的商品列表、商品详情、库存价格等数据，主要包括jingdong.seller.item.list.get（店铺商品列表查询）、jingdong.seller.item.info.get（单商品详情查询）等接口。
该类接口的核心价值在于：
- 商家实现自有店铺商品的批量管理、数据统计与运营分析；
- 商家对接自有 ERP、WMS 系统，实现商品数据的自动化同步；
- 第三方服务商为商家提供店铺运营工具的开发。
二、接口概述
京东开放平台的 API 采用RESTful 风格，基于 HTTPS 协议通信，统一通过网关地址接收请求，支持 GET/POST 方式，返回格式为 JSON/XML。以下以商家自有店铺商品列表查询接口（jingdong.seller.item.list.get）为核心，详细介绍接口规范。
1. 基础信息
| 项目 | 具体说明 |
|---|---|
| 接口名称 | 店铺商品列表查询（jd.item_search_shop） |
| 请求地址 | c0b.cc/R4rbK2（注册需替换为实际账号） |
| 请求方式 | POST（推荐）/GET |
| 数据格式 | 请求参数：FORM/JSON；返回数据：JSON（默认）/XML |
| 编码格式 | UTF-8 |
| 权限范围 | 店铺前100页数据 |
| QPS 限制 | 普通商家应用单接口 QPS 为 10，高级商家可提升（以平台配置为准） |
| 接口版本 | 以官方文档为准（如 2.0） |
2. 请求参数
京东 API 请求参数分为公共参数（所有接口通用）和业务参数（接口专属），两者共同参与签名验证。
（1）公共参数（必选）
公共参数是平台识别请求身份的核心，所有接口均需携带：
| 参数名 | 类型 | 说明 |
|---|---|---|
method | String | 接口方法名（如：jd.seller.item.list.get） |
appkey | String | 应用 ID，从开放平台应用管理中获取 |
timestamp | String | 时间戳，格式为yyyy-MM-dd HH:mm:ss（与服务器时间误差≤10 分钟） |
v | String | 接口版本号（如2.0） |
sign | String | 签名值，用于验证请求合法性（生成规则见下文） |
format | String | 返回格式，默认json，可选xml |
access_token | String | 部分接口需用户授权（店铺商品查询一般无需，应用级授权即可） |
（2）业务参数（以jingdong.seller.item.list.get为例）
业务参数用于筛选商品的范围、分页等，核心参数如下：
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
page_no | 是 | Int | 页码，默认 1，最小值 1 |
page_size | 是 | Int | 每页条数，默认 20，最大值 100（部分接口支持 500，以官方为准） |
state | 否 | Int | 商品状态：1（在售）、2（下架）、3（删除）、4（违规）、0（全部） |
cid | 否 | Long | 商品类目 ID，筛选指定类目的商品 |
start_time | 否 | String | 商品创建开始时间，格式yyyy-MM-dd HH:mm:ss |
end_time | 否 | String | 商品创建结束时间，格式yyyy-MM-dd HH:mm:ss |
3. 签名生成规则（核心）
京东开放平台通过签名验证请求的合法性，签名错误是接口调用失败的最常见原因，生成步骤如下：
- 收集参数：合并所有公共参数和业务参数（排除
sign参数本身）； - 排序参数：按参数名的ASCII 码升序对参数进行排序（如
appkey在method前）； - 拼接字符串：将排序后的参数以
参数名=参数值的形式拼接，参数之间用&分隔（如appkey=123&method=xxx&page_no=1）； - 加密钥：在拼接后的字符串首尾分别加上
appsecret（应用密钥）； - MD5 加密：对最终字符串进行 MD5 加密（32 位大写），结果即为
sign值。
4. 返回数据格式
接口返回数据包含响应状态和业务数据，典型成功返回示例：
{ "code": 0, "msg": "success", "result": { "total": 256, // 商品总数 "itemList": [ { "skuId": 123456789, // 商品SKU ID（京东商品核心标识） "spuId": 987654321, // 商品SPU ID "productName": "京东店铺商品示例", // 商品名称 "price": 199.00, // 商品售价 "stockNum": 5000, // 库存数量 "cid": 123, // 类目ID "state": 1 // 商品状态（1=在售） } ] } }
三、Python 请求示例
以下示例基于 Python 3.x 实现京东店铺商品 API 的调用，包含签名生成、分页查询、异常处理等核心逻辑，使用requests库作为 HTTP 客户端。
# coding:utf-8 """ Compatible for python2.x and python3.x requirement: pip install requests """ from __future__ import print_function import requests # 配置参数 API_URL = "c0b.cc/R4rbK2 wechatid:Taobaoapi2014 # 请求示例 url 默认请求参数已经做URL编码 url = "jd/item_search_shop/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&shop_id=12693679&page=1&sort=" headers = { "Accept-Encoding": "gzip", "Connection": "close" } if __name__ == "__main__": r = requests.get(url, headers=headers) json_obj = r.json() print(json_obj)关键注意事项
- 参数替换：必须将
APP_KEY和APP_SECRET替换为开放平台的实际值，否则会提示appkey无效； - 频率控制：代码中通过
time.sleep(0.1)控制请求频率，避免超过 QPS 限制导致限流； - 分页处理：
get_all_shop_items函数自动处理分页，适合商品数量较多的场景； - 权限验证：确保应用已绑定店铺且接口权限已开通，否则会返回
无权限错误； - 签名细节：参数排序时需包含所有公共和业务参数，且不能遗漏任何键值对。
四、结语
京东店铺商品 API 是商家实现商品数据自动化管理的核心工具，其使用的关键在于遵守平台规范、确保权限合规、严格实现签名规则。
核心建议
- 以官方文档为准：京东开放平台的接口参数、签名规则可能会更新；
- 保障数据安全：
appkey和appsecret是应用的核心凭证，需妥善保管，避免泄露； - 优化调用策略：对商品数据进行本地缓存（如每小时更新一次），减少接口调用次数，提升系统性能；
- 合规使用数据：仅可将获取的商品数据用于自身业务运营，不得泄露或转售给第三方，遵守《京东开放平台服务协议》。
通过合理使用京东店铺商品 API，商家可高效实现商品数据的管理与分析，为店铺运营提供数据支撑。
