一、基础调用规范

• 统一网关： https://gw.api.taobao.com/router/rest

• 请求方式：POST，响应格式支持 JSON/XML

• 接口版本：固定 v2.0

• 核心公共参数（全部必传，缺失直接拦截）：

直接访问网关且未携带 method 参数时，会返回错误码 21 Missing method，需在请求体中指定目标接口方法名。

二、MD5 签名算法

签名规则

1. 剔除参数中的 sign 字段与所有空值参数；

2. 按参数名 ASCII 码升序排序；

3. 拼接为 key=value 无分隔符字符串；

4. 字符串首尾拼接 APP_SECRET；

5. 做 MD5 加密，输出 32 位小写十六进制结果。

Python 签名工具类

import hashlib
import time
from urllib.parse import quote_plus
APP_KEY = "你的APP_KEY"
APP_SECRET = "你的APP_SECRET"
GATEWAY_URL = "https://gw.api.taobao.com/router/rest"
def generate_sign(params: dict) -> str:
    # 过滤空值与签名字段
    filter_params = {k: v for k, v in params.items() if v and k not in ["sign", "sign_method"]}
    # ASCII升序排序
    sorted_params = sorted(filter_params.items(), key=lambda x: x[0])
    # 拼接签名字符串
    sign_str = APP_SECRET
    for k, v in sorted_params:
        sign_str += f"{k}={quote_plus(str(v))}"
    sign_str += APP_SECRET
    # MD5加密返回小写
    return hashlib.md5(sign_str.encode("utf-8")).hexdigest().lower()
def get_common_params(method: str) -> dict:
    return {
        "app_key": APP_KEY,
        "method": method,
        "format": "json",
        "v": "2.0",
        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S")
    }

三、接口调用代码示例

1. 商品详情查询（taobao.item.get）

公开数据接口，无需用户授权。

import requests
def taobao_item_get(num_iid: str) -> dict:
    method = "taobao.item.get"
    params = get_common_params(method)
    # 业务参数：按需指定返回字段
    params["fields"] = "num_iid,title,price,pic_url,stock,detail_url,seller_nick"
    params["num_iid"] = num_iid
    # 生成签名
    params["sign"] = generate_sign(params)
    try:
        response = requests.post(GATEWAY_URL, data=params, timeout=10)
        result = response.json()
    except Exception as e:
        return {"code": -1, "msg": f"请求异常: {str(e)}", "data": None}
    if "error_response" in result:
        err = result["error_response"]
        return {"code": err["code"], "msg": err["msg"], "data": None}
    
    return {"code": 0, "msg": "success", "data": result["item_get_response"]["item"]}
# 调用示例# print(taobao_item_get("目标商品ID"))

2. 订单详情查询（taobao.trade.fullinfo.get）

敏感数据接口，需传入用户授权 session。

def taobao_trade_get(tid: str, session_key: str) -> dict:
    method = "taobao.trade.fullinfo.get"
    params = get_common_params(method)
    params["tid"] = tid
    params["session"] = session_key
    params["fields"] = "tid,status,payment,create_time,pay_time,orders"
    params["sign"] = generate_sign(params)
    try:
        resp = requests.post(GATEWAY_URL, data=params, timeout=10)
        result = resp.json()
    except Exception as e:
        return {"code": -1, "msg": f"请求异常: {str(e)}", "data": None}
    if "error_response" in result:
        err = result["error_response"]
        return {"code": err["code"], "msg": err["msg"], "data": None}
    
    return {"code": 0, "msg": "success", "data": result["trade_fullinfo_get_response"]["trade"]}

四、核心错误码对照表

五、工程化优化要点

1. 字段裁剪： fields 参数仅传业务必需字段，压缩响应体积；

2. 本地缓存：商品静态数据缓存 1~24 小时，避免重复调用；

3. 超时重试：设置 10s 请求超时，网络异常自动重试 2 次；

4. 安全合规： APP_SECRET 仅后端存储，禁止前端硬编码；日志脱敏敏感参数。