当前位置：首页 > news >正文

1688商品列表API调用全过程分享

news 2025/9/7 9:28:21

一、1688 商品列表 API 概述

1688 商品列表 API 是阿里巴巴开放平台为开发者和商家提供的重要接口，它具备强大的功能特性：

商品信息全面获取：能够获取商品的诸多基本信息，如商品唯一标识 ID，这是识别和追踪商品的关键；商品名称，清晰展示商品的品类；商品主图链接，直观呈现商品外观，吸引用户注意力；价格，为采购决策提供重要参考；起订量，满足不同采购规模需求；库存数量，帮助商家掌握商品的可售情况等。这些信息对于商家全面了解自家商品以及分析竞品态势极为重要，同时也为电商应用向用户展示商品提供了核心数据。

灵活筛选与排序：支持通过多种条件对商品进行筛选和排序。比如，可以根据商品类目 ID 进行筛选，精准定位特定类目的商品，例如在服装类目下查找女装商品；还能依据价格区间筛选商品，方便采购者快速找到符合预算的产品；以销量为依据进行排序，让畅销商品优先展示，帮助商家把握市场热门趋势。

分页查询功能：考虑到数据量庞大，该 API 允许开发者通过指定页码和每页显示的商品数量，分批次获取商品列表。例如，每页设置显示 50 条商品信息，通过逐步递增页码，实现对大量商品数据的有序获取，有效避免一次性获取过多数据导致的性能问题。

特定店铺商品获取：通过指定店铺 ID，能够获取该店铺下的所有商品列表。这对于商家监控自家店铺商品情况，如商品数量、品类分布、价格设定等，以及分析竞争对手店铺商品，了解其产品线布局、热门商品等，都有着重要意义。

二、API 调用前的准备工作

注册开发者账号：访问 1688 开放平台的官方网站，点击注册按钮，按照页面提示填写相关信息。对于个人开发者，需准确填写真实姓名、联系方式、电子邮箱等信息；若为企业开发者，则要提供企业名称、统一社会信用代码、企业法人信息等资料。提交信息后，等待平台审核，审核通过后即可获得开发者账号。

创建应用并获取凭证：使用注册成功的开发者账号登录 1688 开放平台，在平台控制台中找到创建应用的入口。点击创建应用，填写应用名称（需简洁明了且能体现应用功能）、应用描述（详细说明应用的用途、功能特点等）、应用图标（选择能代表应用形象的图标）等信息。应用创建成功后，平台会为应用分配唯一的 App Key 和 App Secret。这两个凭证就如同开发者在 1688 开放平台的 “身份证” 和 “密码”，在后续 API 调用过程中，用于验证开发者身份，确保请求来源合法，务必妥善保管，切勿泄露。

申请 API 权限：在开放平台的控制台中，找到已创建的应用，进入应用详情页面。在接口列表中搜索 “商品列表” 相关接口，如 “alibaba.trade.product.search4trade”（用于获取店铺在售商品列表）或 “1688.item_search_shop”（用于通过店铺 ID 获取店铺所有商品信息）。点击申请权限，根据平台提示填写申请理由（例如说明应用的业务场景中如何使用该接口获取数据，以支持业务功能实现）。提交申请后，等待平台审核，审核周期一般为 1 - 3 个工作日。只有审核通过，应用才能获得调用相应接口的权限。

三、签名生成机制

在调用 1688 商品列表 API 时，为确保请求的合法性和数据的安全性，需要对请求参数进行签名。签名生成步骤如下：

参数排序：将所有请求参数（除 sign 参数外）按照参数名的字典序进行排序。例如，假设有请求参数 {"param1": "value1", "param3": "value3", "param2": "value2"}，排序后变为 {"param1": "value1", "param2": "value2", "param3": "value3"}。

字符串拼接：将排序后的参数名和参数值拼接成一个字符串。拼接格式为 “参数名 1 参数值 1 参数名 2 参数值 2……”，继续以上述示例，拼接后的字符串为 “param1value1param2value2param3value3”。

添加密钥：在拼接字符串的前后分别加上 App Secret。假设 App Secret 为 “your_secret_key”，则最终拼接的字符串为 “your_secret_keyparam1value1param2value2param3value3your_secret_key”。

加密生成签名：使用 MD5 算法对拼接后的字符串进行加密，得到签名结果。在 Python 中，可以使用 hashlib 库来实现 MD5 加密，示例代码如下：

import hashlib

sign_content = "your_secret_keyparam1value1param2value2param3value3your_secret_key"

sign = hashlib.md5(sign_content.encode('utf-8')).hexdigest().upper()

得到的签名值需作为 sign 参数添加到请求中，以此向平台证明请求的合法性和完整性。

四、构造请求参数

根据 1688 商品列表 API 文档的要求，构造包含必要参数的请求。常见参数如下：

app_key：即之前创建应用时获取的 App Key，用于标识应用身份。

sign：按照上述签名生成机制生成的签名，用于验证请求合法性。

timestamp：请求的时间戳，一般为当前时间的毫秒数。在 Python 中，可以使用如下代码获取当前时间戳：

import time

timestamp = int(time.time() * 1000)

时间戳的作用是防止请求被重放攻击，因为平台会验证请求时间与服务器时间的差值是否在合理范围内。

4. 筛选、排序、分页参数：

categoryId（商品类目 ID）：若要筛选特定类目的商品，需传入该类目对应的 ID。例如，若要获取手机类商品，可查询 1688 平台类目表获取手机类目的准确 ID 并传入。

pageNo（页码）：指定要获取的商品列表页码，从 1 开始。

pageSize（每页商品数量）：设置每页返回的商品数量，最大值通常为 100，可根据实际需求和性能考量进行调整。

sort（排序方式）：如 “sort=sale_desc” 表示按销量从高到低排序，“sort=price_asc” 表示按价格从低到高排序等。

例如，要获取第 3 页、每页显示 50 条的女装类目商品，并按销量从高到低排序，请求参数示例如下：

params = {

"app_key": "your_app_key",

"sign": "your_generated_sign",

"timestamp": 1690704000000,

"categoryId": "500123",

"pageNo": 3,

"pageSize": 50,

"sort": "sale_desc"

}

五、发送 HTTP 请求

使用 HTTP 客户端向接口地址发送请求。常见的编程语言都有相应的 HTTP 请求库，如 Python 的 requests 库、Java 的 HttpClient 等。以 Python 的 requests 库为例，发送 GET 请求的示例代码如下：

import requests

api_url = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.list.get/"

params = {

"app_key": "your_app_key",

"sign": "your_generated_sign",

"timestamp": 1690704000000,

"categoryId": "500123",

"pageNo": 3,

"pageSize": 50,

"sort": "sale_desc"

}

response = requests.get(api_url, params=params)

在发送请求时，需注意接口地址要准确无误，根据 API 文档确定请求方法是 GET 还是 POST。若为 POST 请求，可使用 requests 库的 post 方法，并将参数放在 data 或 json 参数中传递。

六、处理响应数据

解析 JSON 响应：1688 商品列表 API 接口返回的响应通常为 JSON 格式的数据。使用编程语言对应的 JSON 解析库对响应数据进行解析。在 Python 中，可直接使用 requests 库响应对象的 json 方法，示例如下：

if response.status_code == 200:

data = response.json()

items = data.get("items", {}).get("item", ())

for item in items:

title = item.get("title", "")

price = item.get("price", "")

pic_url = item.get("pic_url", "")

detail_url = item.get("detail_url", "")

print(f"Title: {title}, Price: {price}, Pic URL: {pic_url}, Detail URL: {detail_url}")

else:

print("Request failed with status code:", response.status_code)

上述代码中，首先检查响应状态码是否为 200，若为 200 表示请求成功，然后解析 JSON 数据，提取商品的标题、价格、图片链接、详情页链接等信息并打印。

2. 处理响应状态码和错误信息：除了 200 表示请求成功外，还有其他状态码代表不同的错误情况。例如，400 表示请求参数错误，可能是参数格式不正确、缺少必要参数等；401 表示未授权，可能是 App Key、App Secret 错误或未申请接口权限；500 表示服务器内部错误，此时并非请求方的问题，而是平台服务器出现故障。当遇到错误状态码时，需根据错误信息进行相应处理，如检查请求参数、重新申请权限、等待平台修复服务器问题等。同时，建议在代码中添加日志记录功能，将错误信息及相关请求参数记录下来，便于排查问题。

3. 分页处理：由于一次 API 请求可能无法获取全部商品数据，需要进行分页处理。在响应数据中，通常会包含总商品数量（totalResults）和当前页码（pageNo）等信息。通过判断当前页码与总页数的关系，循环发送请求获取所有分页数据。示例代码如下：

all_items = []

page_no = 1

while True:

params = {

"app_key": "your_app_key",

"sign": "your_generated_sign",

"timestamp": int(time.time() * 1000),

"categoryId": "500123",

"pageNo": page_no,

"pageSize": 50,

"sort": "sale_desc"

}

response = requests.get(api_url, params=params)

if response.status_code == 200:

data = response.json()

items = data.get("items", {}).get("item", ())

all_items.extend(items)

total_results = data.get("totalResults", 0)

if len(all_items) >= total_results:

break

page_no += 1

else:

print("Request failed with status code:", response.status_code)

break

上述代码通过循环不断改变页码，获取每一页的商品数据，直到获取到所有商品数据为止。

七、注意事项

API 调用频率限制：1688 开放平台为防止接口滥用，对 API 调用频率有一定限制。不同类型的应用和接口可能有不同的限制规则，例如免费版 API 可能限制每分钟调用 5 - 10 次，企业版可申请提升至每分钟 50 次以上。开发者在使用 API 时，务必合理安排调用频率，避免触发频率限制。可以通过设置请求间隔时间，如在每次请求后使用 time.sleep () 函数暂停一段时间；或者采用缓存机制，对于频繁访问且不经常更新的数据，在本地缓存一份，减少 API 调用次数。

数据安全性：在数据传输和处理过程中，要高度重视数据安全性。首先，确保使用 HTTPS 协议进行数据传输，防止数据在网络传输过程中被窃取或篡改。其次，妥善保管 App Key 和 App Secret，避免硬编码在客户端代码中，建议将其配置在安全的服务器端环境变量中。同时，对敏感信息进行加密存储，如用户隐私数据、商业机密等，防止数据泄露带来的风险。