苏宁开放平台商品详情接口开发指南

2025-06-25 84 阅读1分钟

一、接口概述

苏宁商品详情接口(SN.product.detail.get)是苏宁开放平台提供的核心API，支持获取SKU级别的完整商品信息。该接口采用RESTful风格，数据格式为JSON，需通过OAuth2.0认证调用。

二、接入准备

开发者注册：
- 登录苏宁开放平台(open.suning.com)
- 完成企业实名认证
- 创建应用获取AppKey和AppSecret
权限申请：
- 需申请"商品详情读取"权限
- 每个应用默认每日10000次调用配额

三、接口参数详解

请求示例：
GET https://open.suning.com/api/http/v1/product/detail
Headers:
  Authorization: Bearer {access_token}
Params:
  skuId: 商品SKU编码（必填）
  cityCode: 城市编码（影响区域价格）
  isPromotion: 是否返回促销信息

四、响应数据结构

{
  "code": "0",
  "data": {
    "skuId": "1000001",
    "name": "iPhone 15 Pro",
    "price": {
      "original": 7999.00,
      "current": 7499.00
    },
    "stock": 150,
    "specs": [
      {"name": "颜色", "value": "钛灰色"},
      {"name": "存储", "value": "256GB"}
    ],
    "images": ["url1","url2"],
    "detailHtml": "<div>商品详情HTML</div>"
  }
}

五、开发注意事项

错误处理：
- 401错误：检查access_token有效性
- 404错误：确认SKU是否存在
- 429错误：触发限流需等待1分钟
性能优化：
- 建议使用本地缓存（TTL建议10分钟）
- 批量查询使用批量接口
数据更新机制：
- 价格库存变更通过消息队列推送
- 商品基础信息变更需重新拉取

六、最佳实践

推荐使用Spring Boot集成：

@RestController
public class ProductController {
  
  @GetMapping("/product/{skuId}")
  public ProductDetail getDetail(@PathVariable String skuId) {
    SuningClient client = new SuningClient(APP_KEY, APP_SECRET);
    return client.getProductDetail(skuId);
  }
}