孔夫子旧书网 item_get（官方标准名称为 kfz.item_get）是通过商品 ID 获取二手书、古籍、期刊等商品全量结构化数据的核心接口，覆盖标题、价格、品相、库存、属性、店铺与售后等字段，适配商品展示、价格监控、古籍数字化、二手书估价等场景。该接口采用 HTTPS+API Key/Secret 签名认证，支持 JSON/XML 返回，具备二手书特色字段完整、数据合规、权限分级的特点。本攻略从接口认知、权限获取、实操对接、调试排错到生产级优化，提供全链路结构化指导，兼顾入门易用性与企业级稳定性。
一、接口核心认知：功能与适配场景

接口定位与核心价值
核心功能：输入商品 ID（num_iid），返回商品基础信息、价格体系、品相描述、库存状态、多媒体数据、店铺信息、商品属性等结构化数据；支持按需返回库存、品相级别分级，适配二手书、古籍、期刊等多商品类型。
孔夫子数据特性
合规权威：数据源自孔夫子商品数据库，符合平台数据使用协议，支持商用场景；
特色字段完整：覆盖商品 ID、书名、作者 / 出版社、原价 / 售价、品相、出版年代、页数、装订方式、库存、店铺名称、店铺评分等核心字段，适配二手书 / 古籍场景；
更新实时：价格、库存、品相状态等动态数据实时同步，基础信息缓存 15 分钟；
权限分级：基础信息开放度高，敏感数据（如店铺联系方式、区域库存）需企业授权或高级权限。
典型应用场景
二手书电商展示：获取商品标题、价格、品相、图片等信息，快速搭建商品详情页；
古籍数字化存档：获取古籍版本、出版年代、品相描述等信息，构建古籍数字档案库；
价格监控与估价：实时获取商品售价、品相，对比历史价格，辅助二手书估价与定价；
店铺合作筛选：获取商品关联店铺信息，筛选优质店铺进行合作。
核心参数与返回字段
（1）请求参数（GET/POST 提交，需签名认证）
参数类型参数名称类型是否必填说明应用示例
公共参数 key string 是调用 key（开发者平台获取） 12345678
secret string 是调用密钥（开发者平台获取） abcdef123456
api_name string 是接口名称，固定为 item_get item_get
result_type string 否响应格式，支持 json/xml，默认 json json
cache string 否是否缓存，yes/no，默认 yes yes
业务参数 num_iid string 是商品 ID（孔夫子内部唯一标识） 1234567
need_stock bool 否是否返回库存数据（true = 是，false = 否，默认 false） true
detail_level int 否详情级别（1 = 基础，2 = 扩展，3 = 完整，默认 1） 3
注意事项
num_iid 为必填参数，需从孔夫子商品页面获取或通过 item_search 接口获取；
签名生成需将所有非空参数按 ASCII 升序排序，拼接 Secret 后 MD5 加密，确保参数无遗漏；
接口支持 GET/POST 请求，GET 参数拼接在 URL 中，POST 参数放在请求体，签名需包含所有参数。
（2）返回核心字段（按业务场景分类）
字段分类核心字段说明
基础商品信息 num_iid 商品唯一 ID
title 商品主标题
author 作者
publisher 出版社
publish_year 出版年代
category 所属分类（多级）
binding 装订方式（平装 / 精装 / 线装等）
page_count 页数
价格与品相 current_price 当前售价（元）
original_price 原价（元）
condition 品相描述（全新 / 九品 / 八品等）
condition_level 品相等级（1-10 级，10 为全新）
库存与物流 stock 实时库存量
delivery_type 配送方式（快递 / 自提等）
shipping_fee 运费（元）
多媒体数据 cover_url 封面图 URL
detail_urls 详情图 URL 列表
店铺信息 shop_name 店铺名称
shop_score 店铺评分
shop_url 店铺链接
销售数据 sales_volume 累计销量
comment_count 评论数
提示：detail_level=3 会返回完整商品描述、属性等大字段，响应体积较大，非必要不开启，避免影响接口性能。
接口限制与注意事项
权限类型日调用上限调用频率适用场景
个人测试权限 100 次 / 天 2 次 / 秒功能调试、个人研究
企业基础权限 1000 次 / 天 5 次 / 秒中小型电商商品展示、市场调研
企业高级权限 10000 次 / 天 20 次 / 秒大型电商平台、价格监控系统、古籍数字化项目
数据缓存规则：基础信息缓存 15 分钟，价格、库存、品相状态等动态数据实时同步；
内容限制：下架、删除商品不返回数据，敏感数据（如店铺联系方式、区域库存）需企业授权；
合规要求：数据仅用于合规电商运营、市场调研、古籍数字化等业务，遵守孔夫子开放平台协议，严禁转售、泄露或用于非法用途。
二、对接前准备：权限与环境搭建
获取接口权限（官方唯一合规路径）
孔夫子 item_get 接口由孔夫子开放平台提供，接入步骤如下：
登录孔夫子开放平台（https://open.kongfz.com），注册企业 / 个人开发者账号；
提交资质审核：企业账号上传营业执照、法人身份证，个人账号上传身份证，填写应用用途说明；
创建应用，选择应用类型为 “电商服务”，填写应用名称、服务器 IP 白名单、数据用途，提交审核；
审核通过后，获取 key 和 secret（接口调用核心凭证），配置 IP 白名单；
申请 kfz.item_get 接口权限，根据业务需求选择权限等级（基础 / 进阶 / 高级）。
风险提示：严禁使用非合规爬虫、第三方代理接口抓取数据，违反平台协议，会导致账号封禁、法律追责。
技术环境准备
（1）支持语言与协议
协议：HTTPS（强制，HTTP 请求会被直接拦截）；
开发语言：Python、Java、PHP、Go 等主流语言，推荐 Python（适配签名生成、异步并发与数据解析）。
（2）必备工具与依赖
工具类型推荐工具用途
调试工具孔夫子开放平台调试工具自动生成签名，验证参数与响应结果
Postman 模拟 GET/POST 请求，排查代码逻辑问题
时间戳生成器获取秒级时间戳，确保签名参数正确
开发依赖 requests 发送 HTTPS 请求
hashlib 生成 MD5 签名，确保接口安全
jsonpath-ng 快速解析嵌套 JSON 响应数据
pandas 批量整理商品详情数据，生成 Excel 报告
辅助工具 Redis 缓存商品详情，减少接口调用次数
logging 记录接口调用日志，便于审计与问题追溯
三、实操步骤：接口对接全流程（Python 示例）
步骤 1：理解签名认证规则（核心，必掌握）
孔夫子接口采用 key+secret 签名认证机制，签名生成步骤如下：
收集所有非空请求参数（含公共参数与业务参数）；
按参数名 ASCII 升序排序；
拼接参数为 key1value1key2value2... 格式；
拼接 secret，生成字符串；
对字符串进行 MD5 加密，得到签名（sign）；
将签名添加到请求参数中，发送请求。
步骤 2：完整代码实现（含签名生成 + 调用 + 数据标准化）
（1）依赖安装
bash
运行
pip install requests hashlib jsonpath-ng pandas
（2）Python 代码实现
import requests
import hashlib
import time
import logging
import pandas as pd
from urllib.parse import urlencode

日志配置

logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s",
handlers=[logging.FileHandler("kongfz_item_get.log"), logging.StreamHandler()]
)

配置信息（替换为你的孔夫子开放平台信息）

CONFIG = {
"key": "你的key",
"secret": "你的secret",
"api_url": "https://api-gw.onebound.cn/kfz/item_get",
"result_type": "json",
"cache": "yes"
}

def generate_sign(params: dict, secret: str) -> str:
"""生成孔夫子接口签名（MD5加密）"""

# 1. 按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接参数为key1value1key2value2...格式
param_str = "".join([f"{k}{v}" for k, v in sorted_params])
# 3. 拼接secret
sign_str = param_str + secret
# 4. MD5加密，转为小写
sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().lower()
return sign

def standardize_product_data(raw_product: dict) -> dict:
"""标准化孔夫子商品详情数据，统一输出格式"""
base_info = raw_product.get("base_info", {})
price_info = raw_product.get("price_info", {})
condition_info = raw_product.get("condition_info", {})
stock_info = raw_product.get("stock_info", {})
media_info = raw_product.get("media_info", {})
shop_info = raw_product.get("shop_info", {})
attr_info = raw_product.get("attr_info", {})

return {
    "商品ID": base_info.get("num_iid", ""),
    "商品标题": base_info.get("title", ""),
    "作者": base_info.get("author", ""),
    "出版社": base_info.get("publisher", ""),
    "出版年代": base_info.get("publish_year", ""),
    "所属分类": "/".join(base_info.get("category", [])),
    "装订方式": attr_info.get("binding", ""),
    "页数": attr_info.get("page_count", 0),
    "当前售价(元)": price_info.get("current_price", 0.0),
    "原价(元)": price_info.get("original_price", 0.0),
    "品相描述": condition_info.get("condition", ""),
    "品相等级": condition_info.get("condition_level", 0),
    "库存": stock_info.get("stock", 0),
    "配送方式": stock_info.get("delivery_type", ""),
    "运费(元)": stock_info.get("shipping_fee", 0.0),
    "封面图URL": media_info.get("cover_url", ""),
    "详情图URL列表": ",".join(media_info.get("detail_urls", [])),
    "店铺名称": shop_info.get("shop_name", ""),
    "店铺评分": shop_info.get("shop_score", 0.0),
    "店铺链接": shop_info.get("shop_url", ""),
    "累计销量": base_info.get("sales_volume", 0),
    "评论数": base_info.get("comment_count", 0),
    "请求时间": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
}

def kongfz_item_get(
num_iid: str,
need_stock: bool = False,
detail_level: int = 1
) -> dict:
"""调用孔夫子item_get接口获取商品详情"""

# 1. 校验必填参数
if not num_iid:
    return {"success": False, "error_msg": "num_iid不能为空", "data": {}}

# 2. 构建公共参数
params = {
    "key": CONFIG["key"],
    "api_name": "item_get",
    "result_type": CONFIG["result_type"],
    "cache": CONFIG["cache"],
    "detail_level": detail_level,
    "need_stock": str(need_stock).lower(),
    "num_iid": num_iid
}

# 3. 生成签名
sign = generate_sign(params, CONFIG["secret"])
params["sign"] = sign

try:
    # 4. 发送GET请求
    response = requests.get(
        url=CONFIG["api_url"],
        params=params,
        timeout=10,
        verify=True
    )
    response.raise_for_status()
    result = response.json()

    # 5. 解析响应结果
    if result.get("error_response"):
        error = result["error_response"]
        error_msg = f"{error.get('code', '')}: {error.get('msg', '')}"
        logging.error(f"接口调用失败：{error_msg}")
        return {"success": False, "error_msg": error_msg, "data": {}}

    raw_product = result.get("item_get_response", {}).get("product", {})
    if not raw_product:
        logging.warning(f"无商品数据返回（商品ID：{num_iid}）")
        return {"success": False, "error_msg": "无商品数据", "data": {}}

    # 6. 标准化数据
    standard_data = standardize_product_data(raw_product)
    return {
        "success": True,
        "data": standard_data,
        "error_msg": ""
    }
except requests.exceptions.RequestException as e:
    logging.error(f"网络请求异常：{str(e)}")
    return {"success": False, "error_msg": f"网络异常：{str(e)}", "data": {}}
except Exception as e:
    logging.error(f"数据解析异常：{str(e)}")
    return {"success": False, "error_msg": f"解析异常：{str(e)}", "data": {}}

调用示例

if name == "main":
num_iid = "1234567" # 替换为目标商品ID
need_stock = True
detail_level = 2

result = kongfz_item_get(
    num_iid=num_iid,
    need_stock=need_stock,
    detail_level=detail_level
)
if result["success"]:
    print("孔夫子商品详情：")
    for k, v in result["data"].items():
        print(f"{k}: {v}")
    # 保存为Excel
    df = pd.DataFrame([result["data"]])
    df.to_excel(f"kongfz_product_detail_{num_iid}.xlsx", index=False)
else:
    print(f"获取失败：{result['error_msg']}")

四、调试与问题排查：快速解决对接异常

优先用官方工具调试（排除签名与参数问题）
登录孔夫子开放平台调试工具，选择 kfz.item_get 接口；
输入商品 ID、need_stock、detail_level 等参数，工具自动生成签名并发送请求；
若官方工具调用成功，说明代码的签名生成或参数拼接逻辑有误；若失败，检查权限或参数有效性。
高频问题排查表
问题现象常见原因解决方案
签名验证失败（401） 1. key/secret 错误；
签名生成规则错误；
缓存参数与签名不匹配 1. 核对开放平台应用信息；
严格按 ASCII 升序排序参数，拼接 secret 后 MD5 加密；
确保缓存参数（cache）包含在签名生成中
权限不足（403） 1. 未申请 kfz.item_get 接口权限；
IP 不在白名单；
权限等级不足（如请求店铺联系方式） 1. 在开放平台申请对应权限；
添加服务器 IP 到白名单；
升级权限等级，申请敏感数据访问权限
参数错误（400） 1. num_iid 为空；
detail_level 值非法（非 1/2/3）；
need_stock 格式错误（非 bool） 1. 确保 num_iid 非空；
detail_level 设置为 1/2/3；
need_stock 转为小写字符串（true/false）
无商品数据返回 1. 商品 ID 错误；
商品已下架 / 删除；
商品为敏感类型（如禁售品） 1. 核对商品 ID 是否准确；
在孔夫子官网搜索商品，确认商品状态；
调整商品类型，选择合规商品
响应超时（504） 1. 网络波动；
detail_level=3 导致响应体积过大；
高峰期调用 1. 添加重试机制；
降低 detail_level（如改为 1）；
避开高峰期（如工作日 10:00-12:00）
五、进阶优化：生产级稳定性提升
性能与配额优化
批量调用优化：多商品查询时采用异步并发（aiohttp），控制并发数≤权限允许的频率上限（如企业基础权限 5 次 / 秒）；
智能缓存策略：用 Redis 缓存商品详情，缓存 key 为 kongfzproduct商品ID_need_stock_detail_level，动态数据（价格、库存）缓存 5 分钟，基础信息缓存 15 分钟，减少重复调用；
字段精简：通过 detail_level 参数只返回业务必需字段，如仅获取商品 ID、标题、价格、品相，减少响应体积与耗时。
数据质量优化
数据去重：按商品 ID 去重，避免同一商品重复出现；
异常值过滤：过滤售价≤0、库存≤0 的商品（根据业务需求调整）；
商品 ID 校验：调用前校验商品 ID 有效性，减少无效请求。
合规与安全
密钥管理：生产环境将 key/secret 存储在配置中心（如 Nacos、Apollo），禁止硬编码；定期轮换密钥（每 3 个月一次）；
重试机制：对 403（频率超限）、504（超时）等错误添加指数退避重试策略，首次重试间隔 1 秒，之后间隔翻倍，最多重试 3 次；
日志审计：记录每次调用的商品 ID、筛选条件、响应状态、数据条数，保留至少 30 天日志，满足合规审计要求。
六、扩展场景：接口联动与功能升级
联动 item_search 接口：通过 item_search 获取商品 ID 列表，批量调用 item_get 获取商品详情，实现 “搜索 - 详情” 全链路数据采集；
古籍数字化系统：定时调用 item_get 获取古籍商品详情，提取版本、出版年代、品相描述等信息，构建古籍数字档案库；
二手书估价工具：基于商品品相、出版年代、作者、出版社等数据，构建二手书估价模型，提升估价准确性。

孔夫子 item_get - 商品详情接口对接全攻略：从入门到精通

日志配置

配置信息（替换为你的孔夫子开放平台信息）

调用示例

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

孔夫子 item_get - 商品详情接口对接全攻略：从入门到精通

日志配置

配置信息（替换为你的孔夫子开放平台信息）

调用示例

热门文章

最新文章

相关电子书