1688 item_search_shop 接口参数说明与测试指南
一、接口功能
item_search_shop 是1688开放平台提供的核心API，允许开发者通过店铺ID或店铺昵称获取该店铺的所有商品信息，包括：
- 商品基础信息：标题、价格、库存、销量、品牌等。
- 多媒体信息：主图URL、详情页图片、视频链接。
- 用户互动数据：点赞数、评论数、收藏数（需申请权限）。
- 店铺信息：店铺ID、名称、链接等。
典型应用场景：
- 竞品分析：监控竞争对手的商品动态。
- 供应链管理：实时获取库存信息，优化采购策略。
- 价格比较：多店铺商品价格对比，制定定价策略。
- 数据整合：与其他电商平台数据共享，提升运营效率。
二、请求参数详解
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
app_key | String | 是 | 开发者在1688开放平台申请的App Key。 |
timestamp | String | 是 | 请求时间戳，格式为yyyy-MM-dd HH:mm:ss，防止请求被缓存或重复执行。 |
sign_method | String | 是 | 签名方法，固定为md5。 |
sign | String | 是 | 请求签名，确保安全性（生成方法见下文）。 |
v | String | 是 | API版本号，固定为2.0。 |
format | String | 是 | 返回数据格式，固定为json。 |
seller_nick | String | 是 | 店铺昵称或店铺ID（如b2b-2200733087881719de）。 |
start_price | Number | 否 | 价格下限（单位：元），用于筛选商品。 |
end_price | Number | 否 | 价格上限（单位：元），用于筛选商品。 |
q | String | 否 | 搜索关键词，用于在店铺内搜索特定商品。 |
page | Number | 否 | 当前页码，默认为1。 |
page_size | Number | 否 | 每页显示商品数量，默认为40，最大支持100。 |
sort | String | 否 | 排序方式，如： |
- price：价格从低到高 | |||
- _price：价格从高到低 | |||
- sale：销量从高到低 |
三、签名生成方法
签名是API调用的关键，确保请求未被篡改。生成步骤如下：
- 排序参数：将所有参数（除
sign外）按字母顺序排序。 - 拼接字符串：将参数名和值用
=连接，再用&拼接成字符串。 - 添加密钥：在字符串首尾加上
App Secret。 - MD5加密：对字符串进行MD5加密，生成签名。
示例代码（Python）：
python
import hashlib |
import time |
def generate_sign(params, app_secret): |
sorted_params = sorted(params.items()) |
param_str = '&'.join([f'{k}={v}' for k, v in sorted_params]) |
sign_str = f'{param_str}{app_secret}{app_secret}' |
return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper() |
# 示例参数 |
params = { |
'app_key': 'your_app_key', |
'timestamp': '2025-07-28 17:00:00', |
'v': '2.0', |
'format': 'json', |
'seller_nick': 'b2b-2200733087881719de', |
'page': '1', |
'page_size': '40' |
} |
# 生成签名 |
app_secret = 'your_app_secret' |
params['sign'] = generate_sign(params, app_secret) |
四、响应数据解析
成功响应为JSON格式，结构如下：
json
{ |
"items": { |
"page": "1", |
"real_total_results": 1900, |
"total_results": 1900, |
"page_size": 40, |
"pagecount": 48, |
"item": [ |
{ |
"num_iid": "628675986215", |
"title": "圆形服装店吊牌定做女装衣服吊卡订制800g加厚烘培礼品花卉卡片", |
"pic_url": "https://cbu01.alicdn.com/img/ibank/2020/386/208/22202802683_1873238575.search.jpg", |
"price": 138.00, |
"detail_url": "https://item.1688.com/item.htm?id=628675986215", |
"shop_name": "圆形服装店", |
"shop_url": "https://shop.1688.com/?shop_id=123456" |
} |
] |
} |
} |
关键字段说明：
num_iid：商品唯一标识符。title：商品标题。pic_url：商品主图URL。price：商品价格（单位：元）。detail_url：商品详情页链接。shop_name：店铺名称。shop_url：店铺首页链接。
五、测试与调试
- 使用官方测试工具：
- 访问1688开放平台API测试工具。
- 选择
item_search_shop接口，填写参数并测试。
- Python测试代码：
python
import requests |
url = "https://api.1688.com/router/rest" |
params = { |
'app_key': 'your_app_key', |
'method': 'item_search_shop', |
'format': 'json', |
'v': '2.0', |
'timestamp': '2025-07-28 17:00:00', |
'sign_method': 'md5', |
'seller_nick': 'b2b-2200733087881719de', |
'page': '1', |
'page_size': '40', |
'sign': '生成的签名' |
} |
response = requests.get(url, params=params) |
print(response.json()) |
- 常见错误处理：
isv.invalid-permission：检查App Key和App Secret是否正确，或申请接口权限。isv.param-error：检查参数是否完整且格式正确。- 签名失败：确认签名生成方法是否符合规范。
六、注意事项
- 调用频率限制：默认QPS为10，超出需申请提升。
- 数据安全：获取的数据仅供合法使用，不得侵犯他人权益。
- 版本更新：关注1688开放平台文档，及时适配接口变更。