淘宝REST API 技术手册（精简版）

一、基础调用规范

• 统一网关：https://gw.api.taobao.com/router/rest
• 请求方式：POST，响应格式支持 JSON/XML
• 接口版本：固定 v2.0
• 核心公共参数（全部必传，缺失直接拦截）：

参数名	说明
app_key	淘宝开放平台应用唯一标识
method	接口方法名（如 taobao.item.get）
timestamp	时间戳，格式 yyyy-MM-dd HH:mm:ss，超时15分钟拒绝
format	返回格式，推荐 json
v	版本号，固定 2.0
sign	MD5 参数签名，安全校验核心
session	用户授权令牌，订单/隐私类接口必填

直接访问网关且未携带 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"]}

四、核心错误码对照表

错误码	错误描述	排查方向
21	Missing method	请求缺少 method 参数，补充对应接口方法名
40001	app_key 不存在	核对应用密钥，确认应用状态正常
40002	签名错误	检查参数排序、SECRET 匹配、特殊字符编码、时间戳
40015	接口方法不存在	核对 method 拼写，确认应用已开通该接口权限
41001	session 缺失/失效	重新获取用户授权令牌
42002	请求频率超限	降低调用频次，增加本地缓存

五、工程化优化要点

1. 字段裁剪：fields 参数仅传业务必需字段，压缩响应体积；
2. 本地缓存：商品静态数据缓存 1~24 小时，避免重复调用；
3. 超时重试：设置 10s 请求超时，网络异常自动重试 2 次；
4. 安全合规：APP_SECRET 仅后端存储，禁止前端硬编码；日志脱敏敏感参数。