在电商数据采集与分析场景中，1688 作为国内知名的 B2B 电商平台，其 API 提供了获取商品详情、价格、库存等实时数据的便捷途径。本文将以 “获取商品详情实时数据” 为核心，通过Python和Java两种主流语言的完整代码示例，手把手教你完成 API 调用全流程，从前期准备到代码运行，每一步都附带详细说明，即使是新手也能轻松上手。
一、API 调用前期准备
在编写代码前，需完成 1688 账号配置与权限申请，这是确保 API 调用成功的基础步骤。
- 注册并登录
完成开发者认证（个人认证需身份证，企业认证需营业执照），认证通过后才能创建应用并获取 API 调用权限。
- 获取关键参数
- 步骤 1：创建应用
选择应用类型，填写应用名称、用途等信息，提交审核（通常 1-2 个工作日审核通过）。
- 步骤 2：获取 Api Key 与 Api Secret
应用审核通过后，在 “应用详情” 页面可查看Api Key和Api Secret（这两个参数是 API 调用的 “身份凭证”，需妥善保存，避免泄露）。
- 步骤 3：申请 API 权限
进入 “API 市场”，搜索 “商品详情查询” 相关 API（推荐使用官方推荐的alibaba.item.get接口，支持获取商品标题、价格、库存、规格等核心信息），点击 “申请权限”，选择已创建的应用，提交后等待权限开通（通常即时开通）。
- 了解 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 为detail.1688.com/offer/12345…，则item_id=123456789）。
- 签名生成规则：1688 API 签名采用 “参数排序 + 拼接 + MD5 加密” 方式，具体步骤为：①将所有请求参数（除sign外）按参数名 ASCII 码升序排序；②将排序后的参数以 “key=value” 形式拼接成字符串，最后拼接App Secret；③对拼接后的字符串进行 MD5 加密（32 位小写），结果即为sign值。
二、Python 代码示例：调用 1688 API 获取商品详情
Python 凭借简洁的语法和丰富的第三方库，非常适合快速实现 API 调用。以下代码使用requests库发送 HTTP 请求，hashlib库生成 MD5 签名，完整实现商品详情获取。
- 环境准备
首先确保已安装requests库（若未安装，执行命令pip install requests）。
- 完整代码（含注释）
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("未获取到商品详情")
- 代码运行与调试
- 步骤 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 签名，完整实现商品详情获取。
- 环境准备
- Maven 项目：在pom.xml中添加OkHttp和commons-codec依赖（若为非 Maven 项目，需手动下载 JAR 包并导入）：
<dependencies>
<!-- OkHttp：HTTP请求库 -->
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>4.9.3</version>
</dependency>
<!-- commons-codec：MD5加密工具 -->
<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.15</version>
</dependency>
</dependencies>
- 完整代码（含注释）
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("未获取到商品详情");
}
}
}
- 代码运行与调试
- 步骤 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
