🔧 避坑实录：淘宝TOP API接入最常见的6个错误（签名/权限/限流/授权）（附Python源码）

一、六大常见错误速查表

二、Python：签名自检 + 全链路排错Client

# top_troubleshoot.py
"""
淘宝TOP API 六大坑 自检工具
1. 跑 sign_debug()  → 验证签名算法
2. 跑 TopTroubleshootClient.* → 捕获具体错误分类
"""
import hashlib
import time
import requests
from typing import Dict, Optional

# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# ────────────────────────────────────────────────────────
# ① 签名自检（最常用！把你的真实参数字典粘进来）
# ────────────────────────────────────────────────────────
def sign_debug(params: Dict, app_secret: str):
    """
    打印参与签名的KV和最终sign，对比你代码中生成的sign
    params: 不含sign的所有API参数
    """
    filtered = {k: v for k, v in params.items()
                if v is not None and str(v).strip() != '' and k != 'sign'}
    sorted_items = sorted(filtered.items(), key=lambda x: x[0])
    qs = ''.join(f"{k}{v}" for k, v in sorted_items)
    sign_str = f"{app_secret}{qs}{app_secret}"
    sign = hashlib.md5(sign_str.encode()).hexdigest().upper()

    print("=" * 52)
    print("🔍 TOP Sign 调试")
    print("=" * 52)
    for k, v in sorted_items:
        print(f"  {k} = {v}")
    print(f"\n待签名串(首尾已拼AppSecret, 略): len={len(sign_str)}")
    print(f"✅ 计算 sign = {sign}")
    print("=" * 52)
    return sign

# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# ────────────────────────────────────────────────────────
# TOP Client（带错误分类提示）
# ────────────────────────────────────────────────────────
class TopTroubleshootClient:
    GW = "https://gw.api.taobao.com/router/rest"

    def __init__(self, ak, ask, sandbox=False):
        self.ak, self.ask = ak, ask
        self.gw = "https://gw.api.tbsandbox.com/router/rest" if sandbox else self.GW

    def _sign(self, p: Dict) -> str:
        filt = sorted((k, v) for k, v in p.items()
                       if v is not None and str(v).strip() != '' and k != 'sign')
        qs = ''.join(f"{k}{v}" for k, v in filt)
        return hashlib.md5(f"{self.ask}{qs}{self.ask}".encode()).hexdigest().upper()

    def _call(self, method, biz, session=None):
        p = {
            "method": method, "app_key": self.ak,
            "timestamp": str(int(time.time() * 1000)),  # ← 坑⑤ 毫秒！
            "format": "json", "v": "2.0", "sign_method": "md5"
        }
        if session: p["session"] = session
        p.update(biz)
        p["sign"] = self._sign(p)

        try:
            r = requests.post(self.gw, data=p, timeout=15)
            r.raise_for_status()
            d = r.json()
        except requests.exceptions.RequestException as e:
            raise Exception(f"网络错误: {e}")

        if "error_response" in d:
            err = d["error_response"]
            code = str(err.get("code", ""))
            sub = err.get("sub_code", "")
            msg = err.get("msg", "")

            # ── 错误分类 ──
            if "FLOW_CONTROL" in code or code == "7" or "429" in sub:
                hint = "❌ 【坑③ QPS超限】降低QPS(令牌桶)后重试，或购买资源包"
            elif "no permission" in msg or "invalid method" in msg:
                hint = "❌ 【坑② 无权限】确认:①接口已申请 ②企业应用(订单类) ③个人号不能查订单"
            elif "sign" in msg.lower() or "invalid sign" in msg.lower():
                hint = "❌ 【坑① 签名错误】运行 sign_debug() 对比; 确认毫秒时间戳 & 空值剔除"
            elif "session" in msg.lower() or "missing session" in msg.lower():
                hint = "❌ 【坑④ 缺session】订单/店铺私有接口需传 seller AccessToken(OAuth2)"
            elif "timestamp" in msg.lower() or "illegal" in sub:
                hint = "❌ 【坑⑤ 时间戳格式】必须13位毫秒 int(time.time()*1000)"
            else:
                hint = f"❌ TOP业务错误 code={code} sub={sub}"

            raise Exception(f"{hint}\n    原始: [{code}] {msg} {err.get('sub_msg','')}")

        k = [x for x in d if x != "error_response"][0]
        return d[k]

    # ── 示例调用 ─-
    def test_item_get(self, num_iid, session=None):
        return self._call(
            "taobao.item.get",
            {"num_iid": num_iid,
             "fields": "num_iid,title,price,pic_url,skus,num,approve_status"},
            session=session
        ).get("item", {})

    def test_onsale_list(self, session):
        """需企业+授权 → 验证坑②④"""
        return self._call(
            "taobao.items.onsale.get",
            {"page_no": 1, "page_size": 10,
             "fields": "num_iid,title,price,num,approve_status"},
            session=session
        )

# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# =========================================================
# 运行自检
# =========================================================
if __name__ == "__main__":
    AK = "YOUR_APP_KEY"
    ASK = "YOUR_APP_SECRET"

    # ---- ① 签名自检 ----
    print("\n>>> [自检] 签名算法验证")
    sign_debug(
        {
            "method": "taobao.item.get",
            "app_key": AK,
            "timestamp": str(int(time.time() * 1000)),
            "format": "json",
            "v": "2.0",
            "sign_method": "md5",
            "num_iid": "654321098765",
            "fields": "num_iid,title,price"
        },
        ASK
    )

    # ---- ② 接口连通性 ----
    print("\n>>> [自检] 商品详情（不需session，个人/企业均可）")
    cli = TopTroubleshootClient(AK, ASK, sandbox=False)
    try:
        item = cli.test_item_get("654321098765")   # ← 替换真实num_iid
        print(f"✅ 连通成功！标题: {item.get('title')}")
    except Exception as e:
        print(e)

    # ---- ③ 订单/店铺接口测试（需填真实token）----
    # SESSION = "SELLER_ACCESS_TOKEN"
    # try:
    #     cli.test_onsale_list(SESSION)
    #     print("✅ 店铺商品列表正常（企业+授权OK）")
    # except Exception as e:
    #     print(e)

三、六个坑的详细说明

❌ 坑① 签名错误（Invalid Signature）

• 必须：参数按 key ASCII 升序 → 拼 key+value→ 首尾 AppSecret→ MD5 → 大写

• 剔除：sign本身、值为 None或 ""

• 时间戳：int(time.time()*1000)毫秒，不是秒

• 用上面 sign_debug()直接对比

❌ 坑② 403 no permission / invalid method

• taobao.item.get需申请权限（个人也可）

• taobao.trades.sold.get/ taobao.items.onsale.get→ 必须企业应用 + 接口申请 + 卖家授权(session)

• ISV应用未经入驻不能随便用订单接口

❌ 坑③ QPS超限（code=7 / ISP_FLOW_CONTROL_LIMIT）

• 免费默认 ≈5/s（商品）≈10/s（订单部分）

• 客户端加令牌桶 QPS=4，遇限流指数退避重试（代码已分类提示）

❌ 坑④ 订单接口返回空或 403 — Missing session

• 商品公开字段可不传 session

• 订单、物流、自己店铺SKU库存、买家信息 → 必须传 session=卖家AccessToken

• AccessToken 通过 OAuth2 授权码换取（需回调URL在应用配置中）

❌ 坑⑤ timestamp invalid

# ✅ 正确
"timestamp": str(int(time.time() * 1000))
# ❌ 错误
"timestamp": str(int(time.time()))   # 秒级

❌ 坑⑥ skus / outer_id 为空

• 查别人店铺商品：公开API不返回库存/商家编码 → 正常

• 查自己店铺商品：必须传 seller session，否则同样被裁减

四、面试/排错一句话

TOP接入六坑——签名字典排序+毫秒时间戳+空值剔除；订单类接口需卖家AccessToken；QPS超限退避重试；skus空确认是否传了session且是自己店铺商品；403查接口权限与企业应用类型。