一、接口统一返回格式
接口整体返回标准 JSON 结构，分为三层内容：顶层通用状态字段、业务核心 data 数据、异常报错信息，适用于淘客工具、货源监控、比价系统，可解密淘口令并提取纯净商品链接，搭配商品详情接口获取 SKU 价格库存。
成功返回完整示例
{"code":200,"msg":"解析成功","cache":"no","execution_time":128,"server_time":"1772345612000","data":{"pwd_content":"￥abc123xyz￥","origin_url":"https://item.taobao.com/item.htm?id=712345678901","native_url":"taobao://item.taobao.com/item.htm?id=712345678901","num_iid":"712345678901","title":"2026夏季新款纯棉短袖T恤","price":"59.90","pic_url":"https://img.alicdn.com/xxx.jpg","user_type":0,"coupon_info":"满50减10","click_url":"https://s.click.taobao.com/xxx"}}二、顶层通用返回字段（每次请求都会返回）
code：数字类型状态码，200 代表解析成功；4 开头为参数或口令错误；5 开头为服务端异常。
msg：文字描述，简单说明当前请求结果，打印日志、前端提示都可以直接使用。
cache：取值 yes 或 no，标记本次数据是否取自缓存，需要实时商品链接建议传参关闭缓存。
execution_time：数字，单位毫秒，记录接口处理耗时，用于排查接口性能问题。
server_time：服务器时间戳，用于请求日志追溯、防重放校验。
三、核心 data 业务字段（仅解析成功时存在）
链接相关核心字段（接口核心输出）
origin_url：淘口令解密后的纯净商品详情链接，不带任何淘客推广参数，是调用商品详情 API、监控价格库存的标准链接，也是接口最关键字段。
native_url：淘宝 App 唤起协议链接，可直接用于移动端跳转打开商品页面。
click_url：淘客推广短链接，携带佣金、推广渠道参数，不建议用于商品数据采集。
pwd_content：清洗处理后的标准淘口令，自动去除多余空格、换行、特殊符号。
商品基础标识字段
num_iid：商品唯一数字 ID，拿到后可直接传入 taobao.item.get 详情接口，查询 SKU 规格、实时批发价与库存。
user_type：数字标识店铺类型，0 为淘宝普通店铺，1 为天猫店，3 为淘特商品，可用于业务分类筛选。
title：完整商品标题，用于页面展示、关键词筛选、货品归类。
pic_url：商品主图高清地址，配套缩略图字段 thumb_pic_url。
price：商品当前券后到手价，reserve_price 为商品原价、吊牌价。
优惠券拓展字段（有优惠券商品才会返回）
coupon_info 展示优惠文案，例如满 80 减 20；coupon_start_time、coupon_end_time 分别是优惠券生效与过期时间；coupon_remain_count 代表剩余可领取券数量。
四、异常报错返回结构
解析失败时 data 字段固定为 null，额外增加 error_reason 字段标注详细失败原因，示例：
{"code":4001,"msg":"淘口令格式错误，无法解析","error_reason":"口令缺失￥包裹符号","data":null}code：错误码，区分各类故障场景；
msg：简短错误提示文案；
error_reason：详细故障原因，方便开发定位问题；
data：解析失败统一为空，读取字段前必须做空值判断。
常见错误码说明
4001 代表淘口令格式非法、缺少￥符号、内容为空；
4002 代表淘口令过期、商品下架删除，无对应商品链接；
4003 代表口令属于店铺、会场活动类口令，无商品详情页；
429 代表调用频次过高，触发接口限流；
5001 代表服务解析临时异常，间隔几秒重试即可恢复。
五、业务开发使用注意事项
业务采集监控优先使用 origin_url，不要使用 click_url，推广链接附带大量参数，容易导致商品详情接口数据异常；
提取 num_iid 后可直接对接淘宝商品详情 API，批量拉取 SKU 实时价格、库存数据；
实时监控场景请求参数携带 cache=no，避免缓存造成链接、商品信息延迟；
通过 user_type 区分淘宝、天猫商品，自定义不同筛选、统计逻辑；
代码中增加 data 空值判断，解析失败时直接跳过，避免读取子字段触发空指针报错。
六、简易 Python 调用示例
importrequests# 接口配置信息api_key="你的接口密钥"api_gateway="接口网关地址"# 待解析淘口令tao_pwd="￥abc123xyz￥"defparse_taokouling(pwd,cache="no"):params={"key":api_key,"api_name":"tpwd_parse","pwd":pwd,"cache":cache}try:res=requests.get(api_gateway,params=params,timeout=15)returnres.json()exceptExceptionase:return{"code":500,"msg":f"请求异常：{str(e)}","data":None}if__name__=="__main__":result=parse_taokouling(tao_pwd,cache="no")ifresult["code"]==200:data=result["data"]print("真实商品链接：",data["origin_url"])print("商品ID：",data["num_iid"])print("商品标题：",data["title"])else:print("解析失败：",result["msg"])
