日本乐天商品详情API接口的请求构造与参数说明

日本乐天商品详情核心通过IchibaItem/Search（市场商品搜索） 与IchibaItem/Item（商品详情） 两个 API 获取，均为 RESTful 风格的 GET 请求，需携带 Application ID 等认证参数，参数配置直接影响数据准确性与配额消耗Rakuten WS。以下是完整的请求构造、参数说明及 Python 实战示例，适配跨境选品与数据采集场景。

---

一、 核心 API 基础信息

接口名称	接口路径	功能	请求方式	版本	核心认证
商品搜索	IchibaItem/Search/20220601	批量获取商品列表与基础详情	GET	20220601	Application ID
商品详情	IchibaItem/Item/20170426	通过商品 ID 获取单条完整详情	GET	20170426	Application ID

请求基础 URL ：[接口路径]响应格式：默认 JSON，支持 XML（通过 format 参数指定）

---

二、 认证与权限准备

1. 申请 Application ID
   • 关注博主创建应用并获取 Application ID（必填）；
   • 部分接口（如高频率调用）需额外申请权限，遵循 API 使用规范。
2. 认证参数
   • 核心参数：applicationId（所有请求必填）；
   • 可选参数：affiliateId（用于推广佣金追踪）、formatVersion（响应格式版本，默认 2）。

---

三、 商品详情 API（IchibaItem/Item）核心参数说明

通过商品 ID（itemCode）精准获取商品详情，参数分为必填、核心可选、高级可选三类Rakuten WS：

参数类别	参数名	类型	必填	说明	示例值
必填参数	applicationId	String	是	开发者应用 ID	1234567890abcdef1234567890abcdef
	itemCode	String	是	商品唯一编码（格式：店铺代码：商品 ID）	shop001:item123456
核心可选	affiliateId	String	否	推广 ID，用于佣金结算	affiliate_123
	format	String	否	响应格式（json/xml）	json
	formatVersion	Integer	否	响应版本（1/2），默认 2	2
高级可选	elements	String	否	指定返回字段，用逗号分隔	itemName,itemPrice,availability
	imageType	String	否	图片类型（small/medium/large）	large
	callback	String	否	JSONP 回调函数名	handleResponse

---

四、 商品搜索 API（IchibaItem/Search）核心参数说明

用于批量获取商品列表，支持多条件筛选，核心参数如下：

参数类别	参数名	类型	必填	说明	示例值
必填参数	applicationId	String	是	开发者应用 ID	1234567890abcdef1234567890abcdef
条件参数（至少一个）	keyword	String	否	搜索关键词	ワイヤレスイヤホン
	genreId	Integer	否	商品分类 ID（通过分类 API 获取）	555086
	itemCode	String	否	商品编码，支持多个用逗号分隔	shop001:item123456,shop002:item654321
分页参数	page	Integer	否	页码，默认 1，最大 100	1
	hits	Integer	否	每页结果数，1-100	20
筛选参数	minPrice	Integer	否	最低价格	1000
	maxPrice	Integer	否	最高价格	50000
	sort	String	否	排序方式（+price 升序 /-price 降序）	-itemPrice
	availability	Integer	否	库存状态（0 无货 / 1 有货）	1

---

五、 请求构造实战（Python 代码示例）

以下是通过 Python 构造请求的完整流程，包含认证、参数拼接、响应解析、异常处理：

1. 商品详情 API 请求示例

python

运行

import requests
import json

def get_rakuten_item_detail(application_id, item_code, affiliate_id=None):
    """
    调用乐天商品详情API
    :param application_id: 应用ID
    :param item_code: 商品编码（店铺代码:商品ID）
    :param affiliate_id: 推广ID
    :return: 商品详情字典
    """
    base_url = "https://app.rakuten.co.jp/services/api/IchibaItem/Item/20170426"
    params = {
        "applicationId": application_id,
        "itemCode": item_code,
        "format": "json",
        "formatVersion": 2
    }
    if affiliate_id:
        params["affiliateId"] = affiliate_id
    
    try:
        response = requests.get(base_url, params=params, timeout=10)
        response.raise_for_status()  # 抛出HTTP错误
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"请求失败：{e}")
        return None

# 调用示例
APP_ID = "你的应用ID"
ITEM_CODE = "shop001:item123456"
item_detail = get_rakuten_item_detail(APP_ID, ITEM_CODE)
if item_detail:
    print(json.dumps(item_detail, ensure_ascii=False, indent=2))

2. 商品搜索 API 请求示例

python

运行

def search_rakuten_items(application_id, keyword, genre_id=None, page=1, hits=20):
    """
    调用乐天商品搜索API
    :param application_id: 应用ID
    :param keyword: 搜索关键词
    :param genre_id: 分类ID
    :param page: 页码
    :param hits: 每页结果数
    :return: 搜索结果字典
    """
    base_url = "https://app.rakuten.co.jp/services/api/IchibaItem/Search/20220601"
    params = {
        "applicationId": application_id,
        "keyword": keyword,
        "page": page,
        "hits": hits,
        "sort": "-itemPrice",  # 价格降序
        "format": "json"
    }
    if genre_id:
        params["genreId"] = genre_id
    
    try:
        response = requests.get(base_url, params=params, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"搜索失败：{e}")
        return None

# 调用示例
SEARCH_KEYWORD = "ワイヤレスイヤホン"
search_result = search_rakuten_items(APP_ID, SEARCH_KEYWORD, page=1, hits=10)
if search_result:
    print(f"找到 {search_result['count']} 个商品")
    for item in search_result.get("Items", []):
        print(f"商品名：{item['Item']['itemName']}，价格：{item['Item']['itemPrice']}日元")

---

五、 请求构造注意事项

1. 参数编码：URL 参数需进行 URL 编码，特别是中文 / 日文关键词，requests 库会自动处理。
2. 配额管理：乐天 API 有调用频率限制（免费版 QPS 约 10，日调用量约 10000），超限额会返回 429 错误，需添加重试机制与限流控制。
3. 异常处理：针对 404（商品不存在）、403（权限不足）、503（服务不可用）等错误，需捕获并处理。
4. 响应解析：formatVersion=2 时，响应结构更清晰，推荐使用。通过 elements 参数指定返回字段，减少数据传输量。

---

六、 常见错误码与解决方案

错误码	说明	解决方案
400	参数错误	检查必填参数是否缺失，格式是否正确
401	未授权	确认 applicationId 有效
403	权限不足	申请对应 API 的访问权限
404	商品不存在	核对 itemCode 是否正确
429	超出配额	降低调用频率，申请提升配额
503	服务不可用	稍后重试，添加重试机制

---

需要我根据你的应用 ID 与目标商品编码 ，生成可直接运行的 Python 请求代码，并添加配额监控与自动重试逻辑吗？