Python/Java 代码示例：手把手教程调用 1688 API 获取商品详情实时数据

在电商数据采集与分析场景中，1688 作为国内知名的 B2B 电商平台，其 API 提供了获取商品详情、价格、库存等实时数据的便捷途径。本文将以 "获取商品详情实时数据" 为核心，通过Python和Java两种主流语言的完整代码示例，手把手教你完成 API 调用全流程，从前期准备到代码运行，每一步都附带详细说明，即使是新手也能轻松上手。​

一、API 调用前期准备​

在编写代码前，需完成 1688 账号配置与权限申请，这是确保 API 调用成功的基础步骤。​

1. 注册并登录

完成开发者认证（个人认证需身份证，企业认证需营业执照），认证通过后才能创建应用并获取 API 调用权限。​

2. 获取关键参数​

• 步骤 1：创建应用

选择应用类型，填写应用名称、用途等信息，提交审核（通常 1-2 个工作日审核通过）。​

• 步骤 2：获取 Api Key 与 Api Secret

应用审核通过后，在 "应用详情" 页面可查看Api Key和Api Secret（这两个参数是 API 调用的 "身份凭证"，需妥善保存，避免泄露）。​

• 步骤 3：申请 API 权限

进入 "API 市场"，搜索 "商品详情查询" 相关 API（推荐使用官方推荐的alibaba.item.get接口，支持获取商品标题、价格、库存、规格等核心信息），点击 "申请权限"，选择已创建的应用，提交后等待权限开通（通常即时开通）。​

3. 了解 API 调用规则​

• 请求方式：alibaba.item.get接口支持 GET 或 POST 请求，推荐使用 GET（参数拼接更简单）。

• 请求参数：核心参数包括app_key（应用 ID）、method（接口名称，固定为alibaba.item.get）、timestamp（时间戳，格式为yyyy-MM-dd HH:mm:ss，需与当前时间误差不超过 10 分钟）、format（返回数据格式，可选json或xml，推荐json）、v（API 版本，固定为2.0）、sign（签名，用于验证请求合法性，需通过 App Secret 生成）、item_id（商品 ID，即 1688 商品详情页 URL 中id=后的数字，例如商品 URL 为https://detail.1688.com/offer/123456789.html，则item_id=123456789）。

• 签名生成规则：1688 API 签名采用 "参数排序 + 拼接 + MD5 加密" 方式，具体步骤为：①将所有请求参数（除sign外）按参数名 ASCII 码升序排序；②将排序后的参数以 "key=value" 形式拼接成字符串，最后拼接App Secret；③对拼接后的字符串进行 MD5 加密（32 位小写），结果即为sign值。

二、Python 代码示例：调用 1688 API 获取商品详情​

Python 凭借简洁的语法和丰富的第三方库，非常适合快速实现 API 调用。以下代码使用requests库发送 HTTP 请求，hashlib库生成 MD5 签名，完整实现商品详情获取。​

1. 环境准备​

首先确保已安装requests库（若未安装，执行命令pip install requests）。​

2. 完整代码（含注释）

   import requests
   import hashlib
   import time
   from urllib.parse import urlencode

   def get_1688_item_detail(app_key, app_secret, item_id):
   """
   调用1688 API获取商品详情
   :param app_key: 应用App Key
   :param app_secret: 应用App Secret
   :param item_id: 商品ID（1688商品详情页中的id）
   :return: 商品详情字典（若失败返回None）
   """
   # 1. 定义API基础参数
   params = {
   "app_key": app_key,
   "method": "alibaba.item.get", # 固定接口名称
   "timestamp": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()), # 当前时间戳
   "format": "json", # 返回JSON格式
   "v": "2.0", # 固定版本
   "item_id": item_id # 目标商品ID
   }

    # 2. 生成签名（按1688 API规则）
    # 步骤1：按参数名ASCII升序排序
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    # 步骤2：拼接参数字符串（key=value&key=value）+ 拼接App Secret
    sign_str = ""
    for key, value in sorted_params:
        sign_str += f"{key}={value}&"
    # 移除最后一个&，并拼接App Secret
    sign_str = sign_str[:-1] + app_secret
    # 步骤3：MD5加密（32位小写）
    sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().lower()
    # 将签名加入参数列表
    params["sign"] = sign
   
    # 3. 构造请求URL（GET方式，参数拼接在URL后）
    api_url = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.item.get"
    request_url = api_url + "?" + urlencode(params)
   
    try:
        # 4. 发送HTTP请求（设置超时时间10秒，避免请求阻塞）
        response = requests.get(request_url, timeout=10)
        # 5. 解析返回结果（JSON格式）
        result = response.json()
   
        # 6. 验证请求是否成功（1688 API成功返回code=0）
        if result.get("error_response"):
            # 打印错误信息（如权限不足、商品ID不存在等）
            error_msg = result["error_response"]["msg"]
            print(f"API调用失败：{error_msg}")
            return None
        else:
            # 提取商品核心信息（可根据需求扩展字段）
            item_info = result["alibaba_item_get_response"]["result"]["item"]
            detail_data = {
                "商品ID": item_info["item_id"],
                "商品标题": item_info["title"],
                "原价（元）": item_info["original_price"],
                "批发价（元）": item_info["trade_price"],
                "库存数量": item_info["stock"],
                "商品链接": item_info["detail_url"],
                "卖家名称": item_info["seller"]["nick"],
                "发货地址": item_info["seller"]["address"]
            }
            return detail_data
   
    except Exception as e:
        # 捕获网络异常、超时等错误
        print(f"请求异常：{str(e)}")
        return None

   ------------------- 调用示例 -------------------

   if name == "main":
   # 替换为你的App Key、App Secret和目标商品ID
   APP_KEY = "your_app_key" # 例如："12345678"
   APP_SECRET = "your_app_secret" # 例如："abcdef1234567890abcdef1234567890"
   ITEM_ID = "123456789" # 例如："6987654321"（替换为真实商品ID）

    # 调用函数获取商品详情
    item_detail = get_1688_item_detail(APP_KEY, APP_SECRET, ITEM_ID)
   
    # 打印结果
    if item_detail:
        print("商品详情实时数据：")
        for key, value in item_detail.items():
            print(f"{key}：{value}")
    else:
        print("未获取到商品详情")

3. 代码运行与调试​

• 步骤 1：将代码中的APP_KEY、APP_SECRET替换为你在 1688 开放平台获取的真实参数，ITEM_ID替换为 1688 真实商品 ID（可从商品详情页 URL 中提取）。

• 步骤 2：运行代码，若输出 "商品详情实时数据" 及具体字段，则调用成功；若提示 "API 调用失败"，需根据错误信息排查（常见错误：app_key不存在→检查 App Key 是否正确，item_id不存在→检查商品 ID 是否有效，sign无效→检查签名生成逻辑是否正确）。

三、Java 代码示例：调用 1688 API 获取商品详情​

Java 作为企业级开发常用语言，代码规范性更强，以下示例使用OkHttp库发送 HTTP 请求（比原生HttpURLConnection更高效），commons-codec库生成 MD5 签名，完整实现商品详情获取。​

1. 环境准备​

• Maven 项目：在pom.xml中添加OkHttp和commons-codec依赖（若为非 Maven 项目，需手动下载 JAR 包并导入）：

  <dependencies> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.9.3</version> </dependency> <dependency> <groupId>commons-codec</groupId> <artifactId>commons-codec</artifactId> <version>1.15</version> </dependency> </dependencies>

2. 完整代码（含注释）

   import okhttp3.OkHttpClient;
   import okhttp3.Request;
   import okhttp3.Response;
   import org.apache.commons.codec.digest.DigestUtils;

   import java.io.IOException;
   import java.text.SimpleDateFormat;
   import java.util.*;

   public class Ali1688ApiDemo {
   // 1. 配置API核心参数（替换为你的真实参数）
   private static final String APP_KEY = "your_app_key"; // 你的App Key
   private static final String APP_SECRET = "your_app_secret"; // 你的App Secret
   private static final String API_URL = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.item.get"; // API请求地址

    /**
     * 生成1688 API签名
     * @param params 请求参数（不含sign）
     * @return 签名字符串（32位小写MD5）
     */
    private static String generateSign(Map<String, String> params) {
        // 步骤1：按参数名ASCII升序排序
        List<Map.Entry<String, String>> entryList = new ArrayList<>(params.entrySet());
        Collections.sort(entryList, Comparator.comparing(Map.Entry::getKey));
   
        // 步骤2：拼接参数字符串（key=value&key=value）+ 拼接App Secret
        StringBuilder signSb = new StringBuilder();
        for (Map.Entry<String, String> entry : entryList) {
            signSb.append(entry.getKey()).append("=").append(entry.getValue()).append("&");
        }
        // 移除最后一个&，并拼接App Secret
        String signStr = signSb.substring(0, signSb.length() - 1) + APP_SECRET;
   
        // 步骤3：MD5加密（32位小写）
        return DigestUtils.md5Hex(signStr).toLowerCase();
    }
   
    /**
     * 调用1688 API获取商品详情
     * @param itemId 商品ID
     * @return 商品详情JSON字符串（若失败返回null）
     */
    public static String get1688ItemDetail(String itemId) {
        // 2. 构建请求参数
        Map<String, String> params = new HashMap<>();
        params.put("app_key", APP_KEY);
        params.put("method", "alibaba.item.get"); // 固定接口名称
        params.put("timestamp", new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date())); // 当前时间戳
        params.put("format", "json"); // 返回JSON格式
        params.put("v", "2.0"); // 固定版本
        params.put("item_id", itemId); // 目标商品ID
   
        // 3. 生成签名并加入参数
        String sign = generateSign(params);
        params.put("sign", sign);
   
        // 4. 拼接请求URL（GET方式，参数拼接在URL后）
        StringBuilder urlSb = new StringBuilder(API_URL).append("?");
        for (Map.Entry<String, String> entry : params.entrySet()) {
            urlSb.append(entry.getKey()).append("=").append(entry.getValue()).append("&");
        }
        String requestUrl = urlSb.substring(0, urlSb.length() - 1); // 移除最后一个&
   
        // 5. 使用OkHttp发送GET请求
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder().url(requestUrl).build();
   
        try (Response response = client.newCall(request).execute()) {
            // 6. 验证响应是否成功
            if (response.isSuccessful() && response.body() != null) {
                return response.body().string();
            } else {
                System.out.println("API请求失败，响应码：" + response.code());
                return null;
            }
        } catch (IOException e) {
            System.out.println("请求异常：" + e.getMessage());
            return null;
        }
    }
   
    // ------------------- 调用示例 -------------------
    public static void main(String[] args) {
        String itemId = "123456789"; // 替换为真实商品ID（例如："6987654321"）
        String itemDetailJson = get1688ItemDetail(itemId);
   
        if (itemDetailJson != null) {
            System.out.println("商品详情实时数据（JSON）：");
            System.out.println(itemDetailJson);
            // 若需解析JSON为Java对象，可使用FastJSON、Jackson等库（需额外添加依赖）
            // 示例（FastJSON）：JSONObject jsonObj = JSON.parseObject(itemDetailJson);
            // String title = jsonObj.getJSONObject("alibaba_item_get_response").getJSONObject("result").getJSONObject("item").getString("title");
            // System.out.println("商品标题：" + title);
        } else {
            System.out.println("未获取到商品详情");
        }
    }

   }

3. 代码运行与调试​

• 步骤 1：替换APP_KEY、APP_SECRET和itemId为真实参数。

• 步骤 2：运行main方法，若输出 JSON 格式的商品详情数据，则调用成功；若提示错误，可根据控制台输出的错误信息（如 "权限不足""商品不存在"）排查问题。

• 步骤 3：若需解析 JSON 数据（如提取商品标题、价格），可添加FastJSON依赖（在pom.xml中添加com.alibaba:fastjson:1.2.83），并使用代码中注释的解析逻辑。

四、常见问题与解决方案​

1.签名无效（sign 无效）​

• 原因：参数排序错误、时间戳与当前时间误差过大（超过 10 分钟）、App Secret 错误、参数值包含特殊字符未编码。

解决方案：①确保参数按 ASCII 升序排序；②使用System.currentTimeMillis()获取当前时间，避免手动输入时间戳；③核对 App Secret 是否与应用匹配；④对参数值进行 URL 编码（Python 中urlencode已自动处理，Java 中可使用URLEncoder.encode(value, "UTF-8")）。​

2.权限不足（error_code=10001）​

• 原因：未申请alibaba.item.get接口权限，或应用未通过审核。
• 解决方案：在 1688 开放平台 "API 市场" 重新申请接口权限，确保应用已通过开发者认证。

3.商品 ID 不存在（error_code=20001）​

• 原因：item_id错误（如从 URL 中提取时多写 / 少写数字）、商品已下架或被删除。
• 解决方案：重新核对商品详情页 URL 中的item_id，确保商品处于上架状态。

4.请求超时​

• 原因：网络不稳定、1688 API 服务器负载高。
• 解决方案：增加超时时间（Python 中requests.get(timeout=15)，Java 中 `client.newBuilder ().connectTimeout (15, TimeUnit