在电商数据对接、比价工具、选品分析等场景中，获取京东商品详情是最常见的需求。本文基于 2026 年京东开放平台的最新规则，系统讲解 Java 调用京东商品详情接口 的完整流程：从接口选型、签名鉴权、完整代码实现到高频避坑。
一、先分清两套 API，选对方向
京东商品详情接口分为两大体系，调用前先判断自己属于哪类用户：
| 对比项 | 京东联盟 API | 宙斯 JOS 商家 API |
|---|---|---|
| 面向人群 | 个人、CPS 推广者、比价工具 | 有自有京东店铺的商家/ERP 服务商 |
| 核心接口 | jd.union.open.goods.detail.query | jingdong.item.read.get |
| 数据特点 | 含佣金、优惠券、券后价 | 数据最全：真实库存、售后、内部价 |
| 门槛 | 个人实名认证即可 | 企业认证 + 店铺授权 |
| 限制 | 未参加联盟的商品查不到 | 只能查自己店铺的商品 统一调用网关：https://api.jd.com/routerjson（POST） 如果你没有京东店铺，只想做比价、选品、导购，直接选京东联盟 API 即可。 |
二、接入准备
- 注册与认证：在京东联盟官网注册媒体账号，完成个人实名认证。
- 创建应用：进入「开发者管理」创建应用，获取 AppKey 和 AppSecret（密钥务必存服务器，禁止暴露到前端）。
- 申请权限：申请商品详情 API 权限，填写用途（比价/选品/导购），一般当天审核通过。
三、签名机制（90% 的调用失败都源于签名错误）
签名流程：将所有请求参数（除 sign 本身）按 ASCII 升序 排序，拼接成 key1value1key2value2...，再使用 AppSecret 做 HMAC-SHA256 加密并转大写。
常见错误码速查：401 签名错误、403 权限不足、10003 限流、1004 AppKey 无效。
四、Maven 依赖
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
<version>4.5.14</version>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>2.0.53</version>
</dependency>
五、Java 完整实现
5.1 签名工具类
package com.example.jdapi.util;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Map;
import java.util.TreeMap;
public class JdSignUtil {
/**
* 京东联盟签名：参数 ASCII 升序拼接 + HmacSHA256 + 转大写
*/
public static String sign(Map<String, String> params, String appSecret) throws Exception {
// TreeMap 天然按 key 字典序（ASCII）排序
Map<String, String> sorted = new TreeMap<>(params);
StringBuilder raw = new StringBuilder();
for (Map.Entry<String, String> entry : sorted.entrySet()) {
String key = entry.getKey();
String value = entry.getValue();
// 跳过空值与 sign 本身
if (key.equals("sign") || value == null || value.isEmpty()) {
continue;
}
raw.append(key).append(value);
}
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(appSecret.getBytes("UTF-8"), "HmacSHA256"));
byte[] digest = mac.doFinal(raw.toString().getBytes("UTF-8"));
StringBuilder sb = new StringBuilder();
for (byte b : digest) {
sb.append(String.format("%02x", b));
}
return sb.toString().toUpperCase();
}
}
5.2 商品详情 API 客户端
package com.example.jdapi.client;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.example.jdapi.util.JdSignUtil;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import java.util.HashMap;
import java.util.Map;
public class JdGoodsApiClient {
private static final String API_URL = "https://api.jd.com/routerjson";
private final String appKey;
private final String appSecret;
private final CloseableHttpClient httpClient = HttpClients.createDefault();
public JdGoodsApiClient(String appKey, String appSecret) {
this.appKey = appKey;
this.appSecret = appSecret;
}
/**
* 查询商品详情（京东联盟）
*
* @param skuIds 商品 SKU ID，支持多个，逗号分隔（批量最多 20 个）
*/
public JSONObject queryGoodsDetail(String skuIds) throws Exception {
// 1. 公共参数
Map<String, String> params = new HashMap<>();
params.put("app_key", appKey);
params.put("method", "jd.union.open.goods.detail.query");
params.put("timestamp", String.valueOf(System.currentTimeMillis()));
params.put("format", "json");
params.put("v", "2.0");
// 2. 业务参数：指定字段可减少响应体积、提升速度
JSONObject goodsReq = new JSONObject();
goodsReq.put("skuIds", skuIds);
goodsReq.put("fields", "skuId,name,price,mainImg,stock,monthSales,promotionInfo");
params.put("goods_req", goodsReq.toJSONString());
// 3. 生成签名
params.put("sign", JdSignUtil.sign(params, appSecret));
// 4. 发送 POST 请求
HttpPost post = new HttpPost(API_URL);
post.setEntity(new StringEntity(JSON.toJSONString(params),
"application/json"));
post.setHeader("Content-Type", "application/json");
try (CloseableHttpResponse response = httpClient.execute(post)) {
String body = EntityUtils.toString(response.getEntity(), "UTF-8");
JSONObject result = JSON.parseObject(body);
// 5. 统一错误处理
if (result.containsKey("error_response")) {
JSONObject err = result.getJSONObject("error_response");
throw new RuntimeException(
"调用失败: " + err.getString("msg")
+ " (code=" + err.getString("code") + ")");
}
return result;
}
}
public static void main(String[] args) throws Exception {
JdGoodsApiClient client = new JdGoodsApiClient("你的AppKey", "你的AppSecret");
JSONObject result = client.queryGoodsDetail("100012345678");
System.out.println(result.toJSONString());
}
}
5.3 响应示例
JSON
{
"jd_union_open_goods_detail_query_response": {
"code": "0",
"result": {
"goodsInfo": {
"skuId": 100012345678,
"title": "Apple iPhone 17 Pro 256GB",
"lowPrice": 8999.00,
"monthSales": 5200,
"mainImg": "https://img10.360buyimg.com/...",
"promotionInfo": "满8000减500"
}
}
}
}
六、调用频率限制（2026 官方标准）
- 京东联盟基础权限：QPS ≤ 10 次/秒，日上限 5000 次；高级权限可提升至 QPS ≤ 20、日上限 10 万。
- 商家 JOS：个人/基础账号 QPS ≤ 2，企业账号默认 5 QPS，可申请至 50 QPS。
- 批量接口：单次最多 20 个 SKU，注意 1 次批量调用按 20 次单品调用计数。
七、高频避坑指南
- 签名失败排査：时间戳必须是毫秒级（误差需在有效期内）；参数值含空格或空值参与拼接会破坏签名；排序必须严格按 ASCII 升序。
- 限流应对：生产环境加请求间隔（建议 ≥1 秒）+ 本地缓存 + 失败退避重试，不要粗暴并发打满 QPS。
- 批量查询分批：一次最多 20 个 SKU，超过要分批处理。
- 合规红线：严禁爬取售卖数据、绕链引流或伪造商品信息；密钥放服务端，前端绝不暴露。
- 按需指定 fields：只取需要的字段，能显著减小响应体积并提升接口速度。
八、总结
Java 接入京东商品详情接口的核心就三步：申请密钥 → HmacSHA256 签名 → POST 到 routerjson 网关。把签名工具类封装好、错误码处理好、限流做平滑，一个稳定可靠的京东商品数据服务就搭建完成了。如果是商家自建 ERP，则切换到 jingdong.item.read.get 体系并额外携带 OAuth2 的 access_token 即可，整体签名逻辑保持一致。
如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。
