🤝 淘宝客API（taobao.tbk.*）获取商品列表与佣金信息实战（附Python源码）

一、前置条件（必看）

1. 注册阿里妈妈 + 创建淘宝客应用
   进入 阿里妈妈开放平台→ 创建「网站/App/微信淘宝客应用」

2. 绑定推广位 PID
   阿里妈妈后台 → 推广管理 → 获取 mm_xxx_xxx_xxx（格式 mm_站点ID_广告位ID_推广ID）

3. 申请接口权限：taobao.tbk.dg.material.optional（物料搜索）、taobao.tbk.item.info.get（商品详情）、taobao.tbk.dg.coupon.get（券）

4. AppKey / AppSecret 同淘宝TOP开放平台

⚠️ 淘宝客接口不传 session（AccessToken），用 AppKey + Sign 即可。

二、核心接口速览

三、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绑定应用 / 接口权限已申请")

四、返回关键字段说明（选品核心）

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(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。