阿里妈妈作为阿里巴巴旗下的营销推广平台（核心业务包括淘宝联盟、直通车、钻展等），其item_get接口是获取推广商品详情的核心工具，主要服务于淘宝客、联盟推广者、电商营销平台等场景。该接口可获取商品的推广信息（如佣金比例、优惠券、推广链接）、基础信息（价格、标题、规格）及交易数据（销量、评价），是构建推广选品、佣金监控、自动推广系统的关键。本文将系统讲解接口对接流程、认证机制、代码实现及最佳实践，帮助开发者从入门到精通。
一、接口基础认知（核心功能与场景）
二、对接前置准备（账号与环境）
三、接口调用流程（官方标准）
四、代码实现示例（Python）
import requests
import time
import hmac
import hashlib
import json
from urllib.parse import urlencode
class AlimamaItemApi:
def __init__(self, app_key, app_secret, sandbox=False):
self.app_key = app_key
self.app_secret = app_secret
self.sandbox = sandbox # 是否使用沙箱环境
self.base_url = "https://gw-api.tbsandbox.com/router/rest" if sandbox else "https://eco.taobao.com/router/rest"
self.format = "json"
self.version = "2.0"
self.method = "taobao.tbk.item.info.get" # item_get对应官方接口名
def generate_sign(self, params):
"""生成HMAC-MD5签名"""
# 1. 按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接为key=value字符串
sign_str = urlencode(sorted_params)
# 3. 拼接app_secret并加密
sign = hmac.new(
self.app_secret.encode(),
sign_str.encode(),
hashlib.md5
).hexdigest().lower()
return sign
def item_get(self, num_iid, platform=1, ip=None):
"""
获取商品详情
:param num_iid: 商品ID（item_id）
:param platform: 平台类型（1-淘宝，2-天猫）
:param ip: 客户端IP（可选）
:return: 标准化商品数据
"""
try:
# 1. 组装公共参数
public_params = {
"app_key": self.app_key,
"method": self.method,
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
"format": self.format,
"v": self.version
}
# 2. 组装业务参数
biz_params = {
"num_iid": num_iid,
"platform": platform
}
if ip:
biz_params["ip"] = ip
# 3. 合并参数并生成签名
all_params = {**public_params,** biz_params}
all_params["sign"] = self.generate_sign(all_params)
# 4. 发送POST请求
response = requests.post(
url=self.base_url,
data=all_params,
timeout=10
)
response.raise_for_status()
result = response.json()
# 5. 处理响应
if "error_response" in result:
error = result["error_response"]
return {
"success": False,
"error_code": error["code"],
"error_msg": error["msg"],
"sub_msg": error.get("sub_msg", "")
}
# 6. 提取并标准化数据
item = result.get("tbk_item_info_get_response", {}).get("results", {}).get("n_tbk_item", [])[0]
if not item:
return {"success": False, "error_msg": "未找到商品数据"}
standardized = {
"item_id": item.get("num_iid"),
"title": item.get("title"),
"main_image": item.get("pict_url"),
"url": item.get("item_url"), # 商品详情页URL
"price": {
"original": float(item.get("reserve_price", 0)), # 原价
"final": float(item.get("zk_final_price", 0)), # 券后价
"currency": "CNY"
},
"promotion": {
"commission_rate": float(item.get("commission_rate", 0)) / 100, # 转为小数（如20%→0.2）
"commission": float(item.get("commission", 0)), # 佣金金额
"coupon_info": item.get("coupon_info", ""), # 优惠券信息
"coupon_url": item.get("coupon_click_url", "") # 优惠券领取链接
},
"sales": {
"volume_30d": int(item.get("volume", 0)), # 30天销量
"comment_count": int(item.get("comment_count", 0)) # 评价数
},
"seller": {
"nick": item.get("seller_nick"), # 卖家昵称
"shop_title": item.get("shop_title") # 店铺名称
},
"推广": {
"click_url": item.get("click_url"), # 推广链接
"short_url": item.get("short_url") # 短链接
}
}
return {"success": True, "data": standardized}
except requests.exceptions.HTTPError as e:
return {"success": False, "error_msg": f"HTTP错误: {str(e)}"}
except Exception as e:
return {"success": False, "error_msg": f"获取失败: {str(e)}"}
# 使用示例
if __name__ == "__main__":
# 替换为实际参数（沙箱环境可使用测试appkey）
APP_KEY = "your_app_key"
APP_SECRET = "your_app_secret"
ITEM_ID = "678901234567" # 示例商品ID（淘宝/天猫商品ID）
# 初始化API客户端（sandbox=True为测试环境，False为正式环境）
api = AlimamaItemApi(APP_KEY, APP_SECRET, sandbox=False)
# 调用接口获取商品详情
result = api.item_get(num_iid=ITEM_ID, platform=2) # platform=2表示天猫
if result["success"]:
data = result["data"]
print(f"商品标题: {data['title']}")
print(f"原价: {data['price']['original']}元 | 券后价: {data['price']['final']}元")
print(f"佣金比例: {data['promotion']['commission_rate']*100}% | 佣金金额: {data['promotion']['commission']}元")
print(f"30天销量: {data['sales']['volume_30d']}件 | 评价数: {data['sales']['comment_count']}")
print(f"推广链接: {data['推广']['click_url']}")
if data['promotion']['coupon_info']:
print(f"优惠券: {data['promotion']['coupon_info']} | 领取链接: {data['promotion']['coupon_url']}")
else:
print(f"获取失败: {result['error_msg']}（错误码: {result.get('error_code')}）")