前言 大部分教程只演示简单调用获取商品基础信息，很少关注拉美多站点差异、多语言属性、附属描述接口分离、token
过期重试这些生产环境痛点。美客多不同国家站点（墨西哥 MLM、阿根廷 MLA、巴西
MLB）返回的字段存在细微差异，直接解析极易出现键不存在报错。本文从业务集成角度，实现具备异常捕获、字段兼容、描述接口联动的调用封装，适合用于商品监控、数据同步场景。 接口基础说明 商品详情核心接口 常见状态码 200：正常返回 401：token 失效，需要刷新令牌 404：商品下架、ID 错误、站点不匹配 429：触发接口限流，需降低请求频率 Python 核心封装代码 代码关键点解析 将商品详情与描述拆分为两个独立请求，业务上合并输出，避免主接口拿不到详情文本的问题。 对 401、404 业务状态单独拦截，方便上层业务做重试、跳过下架商品逻辑。 生产环境踩坑总结 货币单位陷阱：墨西哥货币 MXN 符号同样是 限流策略：授权后接口峰值约 2 万次每小时，批量拉取建议加入延时，大量请求务必做好 429 捕获和退避。 跨站点查询：不要拿 MLM 的商品 ID 去请求 MLA 站点接口，一定会返回 404，ID 自带站点前缀，调用前校验前缀。 属性字段异构：不同类目GET /items/{item_id}，基于 OAuth2.0 鉴权，必须携带 Bearer 令牌。注意商品 ID 前缀代表站点，MLM 为墨西哥、MLA 阿根廷、MLB 巴西，ID 与站点不匹配直接返回 404。商品长描述不在主接口返回，需要额外调用 /items/{item_id}/description 单独获取，这是很多开发者容易遗漏的点MercadoLib...。
python
import requests
import time
class MeliItemClient:
def __init__(self, access_token):
self.token = access_token
self.base_url = "https://api.mercadolibre.com"
self.headers = {"Authorization": f"Bearer {self.token}"}
def get_item_detail(self, item_id):
"""获取商品基础详情，兼容多站点字段缺失"""
url = f"{self.base_url}/items/{item_id}"
try:
resp = requests.get(url, headers=self.headers, timeout=20)
if resp.status_code == 401:
return {"error": "token_invalid", "msg":"令牌过期，请刷新"}
if resp.status_code == 404:
return {"error": "item_not_found", "msg":"商品不存在或已下架"}
resp.raise_for_status()
return resp.json()
except Exception as e:
return {"error":"request_fail", "msg":str(e)}
def get_item_desc(self, item_id):
"""单独获取商品长描述"""
url = f"{self.base_url}/items/{item_id}/description"
resp = requests.get(url, headers=self.headers, timeout=20)
if resp.status_code ==200:
return resp.json().get("plain_text","")
return ""
def parse_normalize(self, raw_data):
"""字段归一化，屏蔽不同站点字段差异"""
if "error" in raw_data:
return raw_data
res = {
"item_id": raw_data.get("id"),
"title": raw_data.get("title",""),
"price": raw_data.get("price"),
"currency": raw_data.get("currency_id",""),
"stock": raw_data.get("available_quantity",0),
"condition": raw_data.get("condition",""),
"site_id": raw_data.get("site_id",""),
"seller_id": raw_data.get("seller",{}).get("id"),
"pic_list": [p.get("url") for p in raw_data.get("pictures",[])],
"attributes": raw_data.get("attributes",[])
}
return res
if __name__ == "__main__":
token = "your_access_token"
client = MeliItemClient(token)
item = client.get_item_detail("MLM123456789")
detail = client.parse_normalize(item)
desc_text = client.get_item_desc("MLM123456789")
detail["description"] = desc_text
print(detail)parse_normalize归一化函数，全部使用.get()取值，防止某站点缺失字段直接抛出 KeyError 导致程序中断。$，不能只看符号，必须保存currency_id字段区分币种，否则价格统计错乱。attributes内部 key 不统一，不能硬编码下标读取，需要循环匹配 name 取值。
