淘宝卖家订单详情 API 接口是淘宝开放平台（TOP，Taobao Open Platform）为商家提供的核心接口之一，主要用于卖家获取店铺订单的完整信息（包括订单状态、买家信息、商品明细、支付详情、物流信息等），支撑店铺订单管理、ERP 系统对接、售后处理等核心业务。以下从接口特性、认证机制、数据结构、调用规范等方面深度分析，并提供 Python 实现示例。
一、接口核心特性与定位
- 官方接口定义
接口名称：
taobao.trade.fullinfo.get（获取订单详情，支持全量订单信息）所属平台：淘宝开放平台（面向商家，需店铺授权）
功能定位：提供单个订单的完整数据，包括基础信息、商品明细、支付信息、物流信息、优惠信息等，是卖家订单管理的核心接口。
与买家 / 推广者接口的区别：
- 仅对店铺卖家开放（需店铺主账号授权），个人开发者或推广者无法调用；
- 数据权限仅限当前店铺的订单，可获取买家手机号（需申请 “获取买家信息” 权限）、详细地址等敏感信息（受隐私规则限制）。
- 认证与权限要求
- 认证机制：采用
appkey + appsecret + session三重认证：appkey/appsecret：开发者在淘宝开放平台注册应用后获取；session：通过店铺主账号授权获得的访问令牌（需申请 “订单管理” 权限），代表店铺授权给应用访问订单数据。
签名规则：与淘宝其他 API 一致，通过参数 ASCII 升序排序→拼接→MD5 加密（含
appsecret）生成签名（sign）。权限门槛：
- 需完成企业开发者认证（个人开发者无法申请）；
- 需在开放平台申请 “获取订单详情”“获取买家信息” 等权限（部分敏感权限需平台审核）；
- 仅能访问授权店铺的订单，无法跨店查询。
二、请求参数与响应数据结构
- 核心请求参数
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
method |
String | 是 | 接口方法名，固定为taobao.trade.fullinfo.get |
app_key |
String | 是 | 应用 appkey |
session |
String | 是 | 店铺授权 session（通过taobao.top.auth.token.create接口获取） |
timestamp |
String | 是 | 时间戳（格式：yyyy-MM-dd HH:mm:ss，与服务器时间误差≤10 分钟） |
sign |
String | 是 | 签名（按淘宝规则生成） |
tid |
Number | 是 | 订单 ID（淘宝订单唯一标识，可从订单列表接口taobao.trades.sold.get获取） |
fields |
String | 是 | 需要返回的字段列表（逗号分隔，如tid,title,buyer_nick,payment,orders） |
- 响应数据核心结构（JSON）
响应数据以trade_fullinfo_get_response为根节点，包含订单全量信息，核心字段分类如下：
| 数据维度 | 关键字段及说明 |
|---|---|
| 订单基础信息 | tid（订单 ID）、status（订单状态：WAIT_BUYER_PAY待付款 /TRADE_SUCCESS交易成功等）、created（创建时间）、updated（更新时间） |
| 买家信息 | buyer_nick（买家昵称）、buyer_id（买家 ID）、receiver_name（收件人）、receiver_mobile（收件人手机，需权限）、receiver_address（收件地址） |
| 商品明细 | orders（商品数组）：包含oid（子订单 ID）、title（商品标题）、sku_properties_name（SKU 规格）、price（单价）、num（数量）、total_fee（小计金额） |
| 支付信息 | payment（实付金额）、total_fee（商品总金额）、discount_fee（折扣金额）、pay_time（支付时间）、payment_type（支付方式：支付宝 / 微信等） |
| 物流信息 | shipping_type（物流方式：快递 / 包邮等）、receiver_phone（收件人电话）、logistics_company（物流公司）、invoice_no（物流单号） |
| 优惠信息 | promotion_details（优惠详情）：包含promotion_id（优惠 ID）、promotion_type（优惠类型：店铺券 / 满减等）、discount_fee（优惠金额） |
响应示例（简化版）
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" }]
}
}
}
三、调用限制与错误处理- 调用限制
QPS 限制：默认单店铺 QPS 为 10（每秒最多 10 次请求），超过返回429 Too Many Requests；
每日调用量：根据店铺等级和应用权限，通常为 10 万 - 100 万次 / 天；
数据时效：支持查询近 365 天的订单，超过则返回invalid tid错误。 - 常见错误码
错误码 说明 解决方案
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://eco.taobao.com/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')}")
五、实际应用与注意事项
典型应用场景
- ERP 系统对接：同步订单信息到企业 ERP，实现订单自动处理、库存更新；
- 订单状态跟踪：实时监控订单状态（如待付款→已付款→已发货），触发相应业务流程（如催付、发货提醒）；
- 售后管理：结合订单详情处理退款、退货申请，提取商品 SKU、支付金额等关键信息；
- 数据分析：统计订单来源、客单价、优惠使用情况等，辅助店铺运营决策。
关键注意事项
- 权限合规：
- 获取买家手机号、地址等敏感信息需严格遵守《个人信息保护法》，仅用于订单履约，不得外泄；
- 权限申请需提供合理用途说明，避免滥用导致权限被收回。
- 性能优化：
- 批量获取订单时，建议通过
taobao.trades.sold.get先获取订单 ID 列表，再分批调用详情接口（控制 QPS）； - 按需指定
fields参数，避免返回冗余字段（减少数据传输量）。 - 数据一致性：
- 订单状态可能实时更新（如付款、发货），建议通过
updated字段判断是否需要重新获取最新数据； - 敏感操作（如发货、退款）需以平台最新数据为准，避免依赖本地缓存。
总结taobao.trade.fullinfo.get是淘宝卖家订单管理的核心接口，提供全量订单数据支撑，但需严格遵守权限规范和调用限制。实际使用中，需结合店铺业务场景合理设计调用逻辑，确保数据安全与系统稳定性。如需扩展功能，可结合订单列表接口（taobao.trades.sold.get）、物流接口（taobao.logistics.online.send）等形成完整的订单管理链路。
