这是京东开放体系里最容易混淆、也最容易踩坑的点之一：

一、核心结论先给

• 京东联盟API（jd.union.open.goods.detail.query）
  ✅ 不需要店铺授权，只要京东联盟实名应用 + AppKey/Secret 就能调
  ❌ 库存只返回状态（有货 / 无货 / 预售），不返回具体可售库存数量
  ✅ 适合：选品、比价、佣金监控、CPS推广、价格追踪

• 京东开放平台JOS（jingdong.ware.read.get/ jingdong.stock.get）
  ✅ 需要企业认证 + 店铺卖家OAuth授权
  ✅ 返回真实SKU库存数量、区域库存、锁定库存
  ✅ 适合：ERP商品同步、防超卖、WMS出入库、店铺自营管理

如果你做电商ERP、库存预占、发货回写，联盟接口库存不够用，必须走JOS商家接口。

二、京东联盟接口“坑点”拆解

三、Python：京东联盟商品详情调用（含库存状态解析）

# jd_union_detail_demo.py
"""
京东联盟API 商品详情查询
jd.union.open.goods.detail.query
- 无需店铺授权
- 库存仅返回 有货(1) / 无货(0) / 预售 状态
依赖: requests
"""
import hashlib
import json
import time
import requests
from typing import Dict, List


class JdUnionClient:
    GW = "https://api.jd.com/routerjson"

    def __init__(self, app_key: str, app_secret: str):
        self.ak = app_key
        self.ask = app_secret

    # ───── JOS/联盟通用 MD5签名（秒级timestamp）─────
    def _sign(self, params: Dict) -> str:
        filt = sorted(
            (k, v) for k, v in params.items()
            if k != "sign" and v is not None and str(v).strip() != ""
        )
        qs = "".join(f"{k}{v}" for k, v in filt)
        raw = f"{self.ask}{qs}{self.ask}"
        return hashlib.md5(raw.encode("utf-8")).hexdigest().upper()

    def get_goods_detail(self, sku_ids: List[int], fields: str = None) -> Dict:
        """
        sku_ids: 最多20个SKU ID
        fields 建议: skuId,productName,price,promotionPrice,couponInfo,
                      stockState,commissionInfo,salesCount,shopName
        """
        fields = fields or (
            "skuId,productName,price,promotionPrice,couponInfo,"
            "stockState,commissionInfo,salesCount,shopName,logisticsType"
        )
        biz = {"skuIds": sku_ids, "fields": fields}

        params = {
            "app_key": self.ak,
            "method": "jd.union.open.goods.detail.query",
            "timestamp": str(int(time.time())),   # ← 秒级！
            "format": "json",
            "v": "2.0",
            "sign_method": "md5",
            "360buy_param_json": json.dumps(biz, ensure_ascii=False,
                                             separators=(',', ':'))
        }
        params["sign"] = self._sign(params)

        r = requests.post(self.GW, data=params, timeout=15)
        r.raise_for_status()
        d = r.json()

        resp_key = "jd_union_open_goods_detail_query_response"
        data = d.get(resp_key, {})
        if "error_response" in str(data):
            err = data.get("error_response")
            raise Exception(f"Union API Err: {err.get('code')} {err.get('zh_desc')}")
        return data

    # ───── 解析库存状态 ─────
    def parse_stock(self, item: Dict) -> str:
        """
        联盟接口库存只有状态，不是数量
        stockState: 1=有货, 0=无货, 可能含预售标识
        """
        state = item.get("stockState")
        if state == 1:
            return "有货"
        elif state == 0:
            = "无货"
        else:
            return f"未知状态({state})"

        # 有些返回在 skuList[].stock 用 1/0 表示
        skus = item.get("skuList", [])
        if skus:
            print("   SKU库存示意:", [(s.get("skuId"), s.get("stock", "N/A"))
                                       for s in skus[:3]])


# =========================================================
# 使用示例
# =========================================================
if __name__ == "__main__":
    client = JdUnionClient("YOUR_JD_APP_KEY", "YOUR_JD_APP_SECRET")
    SKU_IDS = [100012345678, 100087654321]   # ← 替换真实SKU ID

    try:
        result = client.get_goods_detail(SKU_IDS)
        data_list = result.get("data", [])
        if isinstance(data_list, dict):
            data_list = data_list.get("data") or []

        for item in (data_list or []):
            title = item.get("productName")
            price = item.get("promotionPrice") or item.get("price")
            stock_flag = client.parse_stock(item)
            commission = item.get("commissionInfo", {}).get("commission", "N/A")

            print(f"✅ SKU:{item.get('skuId')}")
            print(f"   标题:{title}")
            print(f"   促销价:¥{price}")
            print(f"   库存状态:{stock_flag}  ← 仅状态，无具体库存数")
            print(f"   预估佣金:{commission}")
            client.parse_stock(item)  # 打印sku示意

    except Exception as e:
        print("❌", e)
        print("→ 确认: 京东联盟应用已实名、jd.union.open.goods.detail.query 已申请")

四、如果你必须要真实库存数量，怎么办？

这部分代码在之前《京东商品详情API（jingdong.item.read.get）》《京东库存API（jd.stock.get）实时同步方案》中已经给过完整Python封装。

五、选型一句话总结（面试/方案）

京东联盟API（jd.union.open.goods.detail.query）不用店铺授权就能拿商品标题/价格/券/佣金/销量，但库存只有“有货/无货”状态；要做ERP库存同步、防超卖、发货回写，必须用京东开放平台JOS商家接口（jingdong.ware.read.get/ jd.stock.get）并走企业认证+卖家OAuth授权获取真实stockNum。