在电商数据对接、比价工具、选品分析等场景中获取京东商品详情是最常见的需求。本文基于 2026 年京东开放平台的最新规则系统讲解Java 调用京东商品详情接口的完整流程从接口选型、签名鉴权、完整代码实现到高频避坑。一、先分清两套 API选对方向京东商品详情接口分为两大体系调用前先判断自己属于哪类用户对比项京东联盟 API宙斯 JOS 商家 API面向人群个人、CPS 推广者、比价工具有自有京东店铺的商家/ERP 服务商核心接口jd.union.open.goods.detail.queryjingdong.item.read.get数据特点含佣金、优惠券、券后价数据最全真实库存、售后、内部价门槛个人实名认证即可企业认证 店铺授权限制未参加联盟的商品查不到只能查自己店铺的商品统一调用网关https://api.jd.com/routerjsonPOST如果你没有京东店铺只想做比价、选品、导购直接选京东联盟 API即可。二、接入准备注册与认证在京东联盟官网注册媒体账号完成个人实名认证。创建应用进入「开发者管理」创建应用获取AppKey和AppSecret密钥务必存服务器禁止暴露到前端。申请权限申请商品详情 API 权限填写用途比价/选品/导购一般当天审核通过。三、签名机制90% 的调用失败都源于签名错误签名流程将所有请求参数除 sign 本身按ASCII 升序排序拼接成key1value1key2value2...再使用 AppSecret 做HMAC-SHA256加密并转大写。常见错误码速查401签名错误、403权限不足、10003限流、1004AppKey 无效。四、Maven 依赖dependency groupIdorg.apache.httpcomponents/groupId artifactIdhttpclient/artifactId version4.5.14/version /dependency dependency groupIdcom.alibaba/groupId artifactIdfastjson/artifactId version2.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(MapString, String params, String appSecret) throws Exception { // TreeMap 天然按 key 字典序ASCII排序 MapString, String sorted new TreeMap(params); StringBuilder raw new StringBuilder(); for (Map.EntryString, 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. 公共参数 MapString, 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 响应示例{ 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即可整体签名逻辑保持一致。
