以下以日本乐天市场（Rakuten Ichiba）商品搜索 API为例（乐天不同地区的电商 API 略有差异，韩国乐天需参考其开放平台文档），提供具体调用示例，包含请求参数构造、签名生成、代码实现（Python）及返回结果解析。
一、前提条件
已在乐天开发者平台（日本）注册账号，创建应用并获取：
Application ID（API Key）
Secret Key（部分接口需签名时使用，商品搜索 API 基础版可仅用 Application ID）
参考乐天官方文档：商品搜索 API
二、API 基础信息
接口名称：商品搜索（IchibaItemSearch）
请求方式：GET
请求地址：https://app.rakuten.co.jp/services/api/IchibaItemSearch/20220601
核心参数：
参数名 类型 必填 说明
applicationId string 是 开发者的 Application ID
keyword string 否 搜索关键词（如 “智能手机”）
genreId string 否 分类 ID（可通过分类 API 获取）
page int 否 页码，默认 1，最大 100
hits int 否 每页条数，默认 30，最大 30
format string 否 返回格式，支持json/xml，默认json
三、调用示例
1. 简单 curl 调用（无需签名）
bash
运行
curl "https://app.rakuten.co.jp/services/api/IchibaItemSearch/20220601?applicationId=你的ApplicationID&keyword=iPhone&hits=10&format=json"
AI写代码
2. Python 代码实现（含签名，若接口要求）
部分乐天 API（如高级接口）需对请求参数进行 HMAC-SHA256 签名，以下示例包含参数排序、签名生成、请求发送完整流程：
python
运行
import requests
import hashlib
import hmac
import time
from urllib.parse import urlencode, quote_plus
# 配置信息
APPLICATION_ID = "你的ApplicationID"
SECRET_KEY = "你的SecretKey"
API_URL = "https://app.rakuten.co.jp/services/api/IchibaItemSearch/20220601"
# 构造请求参数
params = {
"applicationId": APPLICATION_ID,
"keyword": "iPhone 15",
"hits": 5,
"page": 1,
"format": "json",
"timestamp": str(int(time.time())) # 部分接口需时间戳防重放
}
# 步骤1：按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 步骤2：拼接参数为"key=value&key=value"格式（值需URL编码）
param_string = "&".join([f"{k}={quote_plus(str(v))}" for k, v in sorted_params])
# 步骤3：生成签名（HMAC-SHA256）
signature = hmac.new(
SECRET_KEY.encode("utf-8"),
param_string.encode("utf-8"),
hashlib.sha256
).hexdigest()
# 步骤4：添加签名到参数
params["signature"] = signature
# 发送请求
response = requests.get(API_URL, params=params)
result = response.json()
# 打印结果
print("请求URL:", response.url)
print("\n返回数据：")
for item in result.get("Items", []):
item_info = item["Item"]
print(f"商品名称：{item_info['itemName']}")
print(f"价格：{item_info['itemPrice']}日元")
print(f"商品链接：{item_info['itemUrl']}\n")
AI写代码
四、返回结果解析（JSON 示例）
json
{
"Items": [
{
"Item": {
"itemCode": "123456789",
"itemName": "iPhone 15 256GB ブルー SIMフリー",
"itemPrice": 128000,
"itemUrl": "https://item.rakuten.co.jp/shop/iphone15/",
"shopName": "乐天官方旗舰店",
"stock": true,
"imageUrl": "https://thumbnail.image.rakuten.co.jp/..."
}
}
],
"count": 1,
"page": 1,
"hits": 5,
"totalCount": 1200
}
AI写代码
关键字段说明：
Items：商品列表数组
itemName：商品名称（含规格）
itemPrice：商品价格（日元，韩国乐天为韩元）
itemUrl：商品详情页链接
stock：库存状态（true为有货）
五、常见错误及解决
错误码 原因 解决方法
401 Application ID 无效 检查开发者后台的应用 ID 是否正确
403 权限不足 / 签名错误 确认 API 权限已开通，或签名生成逻辑有误
429 调用频率超限 降低请求频次，或申请提升配额
500 服务器内部错误 稍后重试，或联系乐天开发者支持
注意事项
乐天日本 / 韩国 / 全球版 API 的端点和参数略有差异，需以对应地区的开放平台文档为准；
商品价格、库存等数据为实时动态，需定期调用更新；
商用场景需遵守乐天 API 的使用条款（如禁止爬虫批量抓取、数据商用授权）。
如有疑问请联系我或评论。
