前言 很多网上乐天接口示例只做简单请求打印原始
JSON，忽略跨境业务最头疼的两个问题：日本 JST 时区转换、日元价格字段异构。直接拿原始返回数据存入国内 ERP，会出现时间差 9
小时、多规格价格错位等隐性 bug。本文基于乐天官方 IchibaItem
详情接口，封装一套带业务层归一化的调用代码，把原始接口输出转为可直接入库的标准化结构体，适合对日选品、商品同步业务场景博客园。 前置准备 在乐天开发者后台创建应用，获取 依赖库： python 代码核心逻辑解析 1. 会话复用：使用 对接踩坑总结 1.itemCode 格式严格是applicationId，开通 Ichiba 商品读取权限。接口采用 GET 请求，商品唯一标识 itemCode 格式为店铺ID:商品ID，单独传入商品 ID 会返回 404。接口存在 QPS 限制，免费开发者需要做好限流处理，避免触发 429 超限错误博客园。requests，执行pip install requests安装。
import requests
import time
from datetime import datetime, timedelta
class RakutenItemDetailClient:
def __init__(self, app_id):
self.app_id = app_id
self.base_url = "https://app.rakuten.co.jp/services/api/IchibaItem/Item/20170426"
self.session = requests.Session()
def get_normalized_detail(self, item_code):
params = {
"applicationId": self.app_id,
"itemCode": item_code,
"format": "json",
"formatVersion": 2
}
try:
resp = self.session.get(self.base_url, params=params, timeout=10)
if resp.status_code == 429:
time.sleep(3)
resp = self.session.get(self.base_url, params=params, timeout=10)
resp.raise_for_status()
raw = resp.json().get("Item", {})
except requests.exceptions.RequestException as e:
return {"error": str(e), "success": False}
# 时区转换：JST(+9)转UTC+8北京时间
jst_str = raw.get("updateTime", "")
try:
jst_dt = datetime.fromisoformat(jst_str)
cn_dt = jst_dt - timedelta(hours=1)
update_cn = cn_dt.strftime("%Y-%m-%d %H:%M:%S")
except Exception:
update_cn = None
result = {
"success": True,
"item_code": item_code,
"item_name": raw.get("itemName",""),
"shop_name": raw.get("shopName",""),
"price_jpy": raw.get("itemPrice",0),
"item_url": raw.get("itemUrl",""),
"image_urls": raw.get("mediumImageUrls",[]),
"review_avg": raw.get("reviewAverage",0),
"review_count": raw.get("reviewCount",0),
"update_time_cn": update_cn,
"availability": raw.get("availability",0)
}
return result
if __name__ == "__main__":
client = RakutenItemDetailClient(app_id="你的applicationId")
res = client.get_normalized_detail(item_code="shopxxxx:itemxxxx")
print(res)Session保持 http 连接，批量拉取详情时降低网络开销；捕获 429 限流后延时重试，保护开发者配额。
2. 时区归一化：接口返回时间为日本 JST 时区，代码自动换算为国内常用东八区时间，解决直接存库时间错位问题。
3. 字段裁剪：过滤接口返回大量无用扩展字段，只保留选品、ERP 同步需要的核心字段。
4. 异常隔离：网络超时、JSON 解析失败全部封装进 error 字段，业务代码不需要写多层 try‑except。shopId:itemId，缺少店铺 ID 参数直接返回未找到商品，这是高频错误点博客园。
2.formatVersion 必须设置为 2，V1 版本 JSON 嵌套层级混乱，解析容易出错。
3.availability 字段代表现货状态，等于 1 代表在售，0 代表下架，业务同步要做状态过滤。
4. 免费版接口有日调用上限，批量同步建议控制单线程间隔，不要并发轰炸接口。
