🤝 淘宝客API（taobao.tbk.*）获取商品列表与佣金信息实战（附Python源码）
淘宝客（TbK/Taobao Ke / 鹊桥）API 是阿里妈妈开放平台接口，用来按关键词搜爆款、获取佣金比例、生成推广链接、查订单。与个人店铺API不同——它不需要卖家店铺授权，但需要备案淘宝客应用 + 绑定阿里妈妈PID。
一、前置条件（必看）
- 注册阿里妈妈 + 创建淘宝客应用
进入 https://open.taobao.com → 创建「网站/App/微信淘宝客应用」 - 绑定推广位 PID
阿里妈妈后台 → 推广管理 → 获取 mm_xxx_xxxxxx（格式 mm站点ID广告位ID推广ID） - 申请接口权限：taobao.tbk.dg.material.optional（物料搜索）、taobao.tbk.item.info.get（商品详情）、taobao.tbk.dg.coupon.get（券）
- AppKey / AppSecret 同淘宝TOP开放平台
⚠️ 淘宝客接口不传 session（AccessToken），用 AppKey + Sign 即可。
二、核心接口速览
接口 用途
taobao.tbk.dg.material.optional 首选 关键词/类目搜商品（含券后价、佣金率、券面额）
taobao.tbk.item.info.get 按 num_iid 查商品详情（补充字段）
taobao.tbk.dg.coupon.get 查商品可用优惠券
taobao.tbk.dg.generate.shorten.tpwd 生成长链/短链/淘口令
taobao.tbk.dg.newuser.order.get 订单明细（结算后）
三、Python：淘宝客商品搜索 + 佣金解析
top_tbk_client.py
"""
淘宝客(Taobao Ke) API Client
依赖: top_api_client.TaobaoTopClient (签名/调用复用TOP网关)
"""
import time
from typing import Dict, List
from top_api_client import TaobaoTopClient
封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
class TbkClient(TaobaoTopClient):
"""
淘宝客接口继承TOP标准Client（网关/签名完全一致）
区别：淘宝客接口一般不需要 session
"""
# ────────────────────────────────────────────────
# ① 物料搜索（推荐接口）
# ────────────────────────────────────────────────
def search_material(self,
keyword: str,
adzone_id: int,
page_no: int = 1,
page_size: int = 20,
sort: str = "total_sales_des") -> Dict:
"""
adzone_id: 推广位ID（取 PID 最后一段，如 mm_123_456_789 → adzone_id=789）
sort:
total_sales_des 销量↓
price_asc / price_des
commission_rate_des 佣金比率↓
"""
biz = {
"adzone_id": adzone_id,
"q": keyword,
"page_no": page_no,
"page_size": min(page_size, 100),
"sort": sort,
"has_coupon": "true", # 只返回有券商品（可选）
"need_free_shipment": "true",
"need_prepay": "true"
}
return self.call(
"taobao.tbk.dg.material.optional",
biz_params=biz,
session=None # ← 淘宝客不需session
)
# ────────────────────────────────────────────────
# ② 按 num_iid 查商品详情（含佣金）
# ────────────────────────────────────────────────
def get_item_info(self, num_iids: List[str], platform=2) -> Dict:
"""
num_iids: 最多40个ID，逗号分隔字符串也可
platform: 1=PC 2=无线
"""
biz = {
"num_iids": ",".join(num_iids),
"platform": platform
}
return self.call(
"taobao.tbk.item.info.get",
biz_params=biz
)
# ────────────────────────────────────────────────
# ③ 解析搜索结果 → 扁平化列表
# ────────────────────────────────────────────────
def parse_results(self, material_resp: Dict) -> List[Dict]:
"""
返回平铺商品列表含关键字段:
num_iid, title, pict_url, zk_final_price,
coupon_amount, coupon_start_fee,
commission_rate (万分之), commission_money,
volume(月销), shop_title, category_id
"""
root = material_resp.get("tbk_dg_material_optional_response", {})
items = root.get("result_list", {}).get("map_data", []) or []
parsed = []
for it in items:
final_price = float(it.get("zk_final_price", 0) or 0)
coupon = float(it.get("coupon_amount", 0) or 0)
commission_rate = int(it.get("commission_rate", 0) or 0) # 万分之
sold_price = final_price - coupon
# 估算佣金金额 = 券后价 × 佣金率/10000
est_commission = round(sold_price * commission_rate / 10000, 2)
parsed.append({
"num_iid": str(it.get("num_iid")),
"title": it.get("title"),
"pic_url": it.get("pict_url"),
"original_price": final_price + coupon,
"final_price": final_price,
"coupon_amount": coupon,
"coupon_start_fee": float(it.get("coupon_start_fee", 0) or 0),
"commission_rate_wan": commission_rate,
"est_commission": est_commission,
"volume": it.get("volume"), # 月销量
"shop_title": it.get("shop_title"),
"category_id": it.get("category_id"),
"item_url": it.get("item_url"),
"coupon_click_url": it.get("coupon_click_url")
})
return parsed
=========================================================
使用示例
=========================================================
if name == "main":
# PID 示例: mm_12345678_87654321_100001 → adzone_id = 100001
PID = "mm_YOUR_SITEID_YOUR_ADZONEID_YOUR_PROMOTIONID"
ADZONE_ID = 100001 # ← 替换成你的 adzone_id（PID最后一段数字）
tbk = TbkClient(
app_key="YOUR_TOP_APP_KEY",
app_secret="YOUR_TOP_APP_SECRET",
sandbox=False # 淘宝客沙箱支持有限，建议直连生产
)
try:
resp = tbk.search_material(
keyword="不锈钢保温杯 定制",
adzone_id=ADZONE_ID,
page_no=1,
page_size=10,
sort="total_sales_des"
)
items = tbk.parse_results(resp)
print(f"✅ 找到 {len(items)} 个带券商品")
for g in items[:3]:
print(f"\n• {g['title'][:30]}")
print(f" 原价:¥{g['original_price']} 券后:¥{g['final_price']} "
f"券¥{g['coupon_amount']}(满{g['coupon_start_fee']}可用)")
print(f" 佣金率:{g['commission_rate_wan']/100:.2f}% "
f"预估佣金:¥{g['est_commission']} 月销:{g['volume']}")
except Exception as e:
print("❌", e)
print("→ 确认: AppKey正确 / PID绑定应用 / 接口权限已申请")
四、返回关键字段说明（选品核心）
TOP返回字段 含义 说明
num_iid 商品ID 可用于跳转或查详情
zk_final_price 券后价（字符串） 已是减去优惠券后价格
coupon_amount 券面额 0=无券
coupon_start_fee 券使用门槛 满X元可用
commission_rate 佣金比率（万分之） 例 5000 = 5%
volume 月销量 选爆款参考
shop_title 店铺名 —
coupon_click_url 领券推广链接 带pid可跳转领券
category_id 叶子类目 类目过滤
估算佣金公式：
est_commission = (zk_final_price - coupon_amount) * commission_rate / 10000
五、生成淘口令（推广链接）
def create_tpwd(self, text: str, url: str, logo: str = None) -> str:
"""生成淘口令(短链)"""
biz = {"text": text, "url": url}
if logo: biz["logo"] = logo
res = self.call("taobao.tbk.dg.generate.shorten.tpwd", biz_params=biz)
return res.get("tbk_dg_generate_shorten_tpwd_response", {}
).get("model", {}).get("password_simple", "")
六、高频避坑
坑 现象 解决
PID未绑定应用 返回 miss pid / 无结果 阿里妈妈后台→推广位管理→确认PID所属站点=应用绑定的网站ID
adzone_id错 空结果 PID三段 mm_site_adzone_promotion → adzone_id=第三段
沙箱调淘宝客 无数据/403 淘宝客建议直连生产网关
has_coupon=true无返回 该类目无券商品 去掉 has_coupon 再试
commission_rate=0 部分商品不分佣 正常现象（平台商品/部分特殊类目）
七、面试/方案一句话
淘宝客选品 = 备案淘宝客应用 → 绑定PID(adzone_id) → 调 taobao.tbk.dg.material.optional(q, adzone_id, has_coupon=true) 取 zk_final_price/coupon_amount/commission_rate → 按 commission_rate/10000 × 券后价 估算佣金，生成推广链接用 taobao.tbk.dg.generate.shorten.tpwd。
需要我补 淘宝客订单回调(taobao.tbk.dg.order.get) 对账脚本 或 与1688货源比价联动选品逻辑 吗？
