当当平台商品详情接口设计与调用指南

news2025/4/13 10:55:47

当当平台商品详情接口设计与调用指南
接口名称

GET /api/product/detail
图书商品核心信息查询接口

请求参数说明
参数名称    类型    是否必填    说明
isbn    string    是    国际标准书号(支持13位/10位)
product_id    string    否    平台内部商品编号（与ISBN二选一）
need_stock    bool    否    是否返回库存数据（默认false）
detail_level    int    否    详情级别(1基础/2扩展/3完整)
认证鉴权机制
python
Copy Code
import requests
import hmac
from urllib.parse import urlencode

def generate_sign(secret, params):
    """HMAC-SHA256签名生成器"""
    query = urlencode(sorted(params.items()))
    return hmac.new(secret.encode(), query.encode(), 'sha256').hexdigest()

# 开发者凭证
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_SECRET_KEY"

点击获取key和secret

# 构造请求示例
params = {
    "isbn": "9787108009821",
    "need_stock": "true",
    "timestamp": str(int(time.time())),
    "nonce": "a3d8f7" # 6位随机字符串
}

# 生成签名
signature = generate_sign(CLIENT_SECRET, params)

# 添加认证头
headers = {
"X-Client-Id": CLIENT_ID,
"X-Auth-Sign": signature
}

响应数据结构（JSON）
json
Copy Code
{
"code": 200,
"data": {
    "base_info": {
      "product_id": "21068943",
      "isbn": "9787108009821",
      "title": "中国历代政治得失",
      "author": "钱穆",
      "press": "生活·读书·新知三联书店",
      "edition": "第2版",
      "page_count": 188,
      "paper_type": "胶版纸"
    },
    "price_info": {
      "retail_price": 38.00,
      "dangdang_price": 26.60,
      "vip_price": 24.80,
      "stock_status": 3 // 1-充足 2-紧张 3-预售
    },
    "content_info": {
      "catalog": "第一章汉代...",
      "abstract": "本书为作者的专题演讲合集...",
      "preview_pages": [
        "https://img.example.com/preview/page1.jpg",
        "https://img.example.com/preview/page2.jpg"
      ]
    },
    "media_info": {
      "cover_image": "https://img.example.com/cover.jpg",
      "audio_preview": "https://audio.example.com/chapter1.mp3",
      "video_intro": "https://video.example.com/trailer.mp4"
    }
}
}

典型错误场景
400 错误类
json
Copy Code
{
"code": 40012,
"message": "ISBN格式校验失败",
"solution": "请检查ISBN编号是否符合规范"
}

403 错误类
json
Copy Code
{
"code": 40309,
"message": "签名验证未通过",
"documentation": "https://open.dangdang.com/docs/signature"
}

404 错误类
json
Copy Code
{
"code": 40401,
"message": "指定商品不存在",
"retry": false
}

代码调用示例（Python）
python
Copy Code
def get_book_detail(isbn):
    API_ENDPOINT = "https://api.open.dangdang.com/product/detail"

    params = {
        "isbn": isbn,
        "timestamp": str(int(time.time())),
        "nonce": secrets.token_hex(3)
    }

    # 签名生成
    params["sign"] = generate_sign(CLIENT_SECRET, params)

    try:
        response = requests.get(
            API_ENDPOINT,
            params=params,
            headers={"X-Client-Id": CLIENT_ID},
            timeout=5
        )
        response.raise_for_status()

        # 处理多版本数据
        if response.json().get('data', {}).get('ebook'):
            return process_ebook_data(response.json())
        else:
            return process_paperbook_data(response.json())

    except requests.exceptions.HTTPError as err:
        handle_api_error(err.response.json())
    except requests.exceptions.Timeout:
        logging.error("API请求超时")