通过1688开放平台API根据商品ID获取商品详情

​

摘要：本文将详细介绍如何调用1688开放平台提供的API接口，通过商品ID精确获取商品的详细信息。内容包括接口概述、请求方式、参数说明、返回数据结构解析以及调用示例。

1. 接口概述

1688开放平台提供了 获取商品详情 接口，允许开发者通过传入商品ID来查询该商品的详细信息。该接口返回的数据结构包含了商品的基础属性、价格、库存、图片、规格等关键信息。

2. 请求方式

接口名称：获取商品详情

请求方法：HTTP POST

请求地址：https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get

数据格式：application/x-www-form-urlencoded

3. 请求参数

调用该接口需要传递以下关键参数：

access_token：String 类型。调用API的身份授权令牌，需通过1688开放平台的OAuth2.0授权流程获取。必须。

productId：Long 类型。目标商品的唯一ID。必须。

fields (可选)：String 类型。用于指定需要返回的字段列表，多个字段用英文逗号分隔。若不指定，默认返回所有字段。

示例：fields=subject,priceRanges,imageUrl,skuInfo

4. 返回数据结构解析

接口成功调用后，会返回一个结构化的JSON数据。核心字段包括：

{
  "result": {
    "productId": 123456789012345, // 商品ID
    "subject": "商品标题", // 商品标题
    "priceRanges": [ // 价格区间
      {
        "startQuantity": 1, // 起批量
        "price": 99.99 // 价格
      },
      // ... 其他价格区间
    ],
    "imageUrl": "https://example.com/image.jpg", // 主图URL
    "detailPage": "https://detail.1688.com/offer/123456789012345.html", // 详情页URL
    "skuInfo": { // SKU信息
      "skuMap": { // SKU属性映射
        "颜色;尺寸": {
          "skuId": "sku123", // SKU ID
          "specId": "spec123", // 规格ID
          "price": 99.99, // SKU价格
          "stock": 100 // SKU库存
        }
        // ... 其他SKU组合
      },
      "specs": [ // 规格定义
        {
          "specId": "spec123", // 规格ID
          "name": "颜色", // 规格名称
          "values": [ // 规格值
            {
              "valueId": "value1",
              "name": "红色"
            },
            {
              "valueId": "value2",
              "name": "蓝色"
            }
          ]
        },
        // ... 其他规格
      ]
    },
    "status": "published", // 商品状态 (published, deleted等)
    // ... 其他字段 (如物流信息、服务承诺、描述信息等)
  },
  "success": true, // 请求是否成功
  "errorCode": "0", // 错误码 (0表示成功)
  "errorMsg": null // 错误信息
}

5. 调用示例 (Python)

import requests

# 你的AppKey、AppSecret、AccessToken (实际应用中需安全存储)
app_key = 'YOUR_APP_KEY'
app_secret = 'YOUR_APP_SECRET'
access_token = 'YOUR_ACCESS_TOKEN'

# 目标商品ID
product_id = 123456789012345  # 替换为实际商品ID

# API请求地址
url = 'https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get'

# 构建请求参数
params = {
    'access_token': access_token,
    'productId': product_id,
    # 'fields': 'subject,priceRanges,imageUrl,skuInfo'  # 可选，按需指定字段
}

# 发送POST请求
response = requests.post(url, data=params)

# 处理响应
if response.status_code == 200:
    data = response.json()
    if data.get('success'):
        product_info = data['result']
        print("商品标题:", product_info['subject'])
        print("主图URL:", product_info['imageUrl'])
        # 解析价格区间、SKU等信息...
    else:
        print("API调用失败:", data.get('errorMsg', '未知错误'))
else:
    print("HTTP请求失败，状态码:", response.status_code)

注意事项：

确保 access_token 有效且具有足够的权限。

productId 必须是有效的1688商品ID (长整型)。

根据业务需求合理使用 fields 参数，避免请求过多不必要的数据。

注意接口调用频率限制，避免触发流控。

处理可能的错误码 (如 isv.invalid-parameter, isp.permission-denied 等)。

6. 常见问题

Q：如何获取 access_token？ A：需要通过1688开放平台的OAuth2.0授权流程获取。开发者需在开放平台创建应用，引导用户授权后获取授权码(code)，再换取访问令牌(access_token)。

Q：返回的图片URL是完整的吗？ A：通常返回的是图片的相对路径或包含域名的主路径。建议拼接1688的图片域名前缀 (如 https://cbu01.alicdn.com/) 或直接使用返回的完整URL。

Q：如何获取实时库存？ A：此接口返回的库存信息 (stock) 可能不是实时更新的。对于需要实时库存的场景，建议使用 获取单个商品库存 等更专业的库存API。

Q：接口返回为空或错误怎么办？ A：首先检查 errorCode 和 errorMsg。常见原因包括：商品ID无效、商品已删除、access_token 失效或权限不足、调用频率超限等。对照错误码排查问题。

7. 总结

通过 获取商品详情 API，开发者可以高效地根据商品ID获取1688平台上商品的丰富信息。合理利用此接口，可以构建商品展示、比价、库存监控等多种应用场景。调用时需严格遵守接口规范，关注授权、参数有效性及错误处理。

建议：在正式集成前，务必仔细阅读1688开放平台官方文档中关于该接口的最新说明，并利用API测试工具进行调试。

​
审核编辑 黄宇