淘宝卖家订单详情 API 接口是淘宝开放平台（TOP，Taobao Open Platform）为商家提供的核心接口之一，主要用于卖家获取店铺订单的完整信息（包括订单状态、买家信息、商品明细、支付详情、物流信息等），支撑店铺订单管理、ERP 系统对接、售后处理等核心业务。以下从接口特性、认证机制、数据结构、调用规范等方面深度分析，并提供 Python 实现示例。
一、接口核心特性与定位
1. 官方接口定义
- **接口名称**：`taobao.trade.fullinfo.get`（获取订单详情，支持全量订单信息）
- **所属平台**：淘宝开放平台（面向商家，需店铺授权）
- **功能定位**：提供单个订单的完整数据，包括基础信息、商品明细、支付信息、物流信息、优惠信息等，是卖家订单管理的核心接口。
- **与买家 / 推广者接口的区别**：
- 仅对**店铺卖家**开放（需店铺主账号授权），个人开发者或推广者无法调用；
- 数据权限仅限当前店铺的订单，可获取买家手机号（需申请 “获取买家信息” 权限）、详细地址等敏感信息（受隐私规则限制）。
2. 认证与权限要求
- **认证机制**：采用`appkey + appsecret + session`三重认证：
- `appkey`/`appsecret`：开发者在淘宝开放平台注册应用后获取；
- `session`：通过店铺主账号授权获得的访问令牌（需申请 “订单管理” 权限），代表店铺授权给应用访问订单数据。
- **签名规则**：与淘宝其他 API 一致，通过参数 ASCII 升序排序→拼接→MD5 加密（含`appsecret`）生成签名（`sign`）。
- **权限门槛**：
- 需完成企业开发者认证（个人开发者无法申请）；
- 需在开放平台申请 “获取订单详情”“获取买家信息” 等权限（部分敏感权限需平台审核）；
- 仅能访问授权店铺的订单，无法跨店查询。
二、请求参数与响应数据结构
1. 核心请求参数
| 参数名 | 类型 | 是否必填 | 说明 |
| ----------- | ------ | ---- | ------------------------------------------------------ |
| `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`） |
2. 响应数据核心结构（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`（优惠金额） |
3. 响应示例（简化版）
三、调用限制与错误处理
1. 调用限制
2. 常见错误码
四、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')}")
五、实际应用与注意事项
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`）等形成完整的订单管理链路。
