淘宝联盟淘客订单查询接口接入指引

本文帮助新人了解订单接口，以及常遇问题和解决办法。新人必读！

本组接口分别是用来查询淘宝客促成的订单，以及查询维权和被淘宝联盟官方处罚的订单。

一、新版淘客订单特点：

2019年5月24号后，淘宝上线最新的淘宝客订单查询接口，和旧版的订单查询接口相比，有以下特点：

以下是联盟官方汇总的优化点：

1、pub/app/api报表类型、字段概念进行统一，理解成本/追溯问题成本降低

2、本次增加付款时间查询：主要解决淘客诟病，通过订单创建时间，要不断回查历史订单，容易拉不全或遗漏订单

3、增加淘宝付款时间透出：尤其解决大促时淘宝端付款和淘客付款时间对不上，以为丢单的问题

4、增加淘宝子订单编号透出：解决淘客之前用“父订单编号”，不能真正知道每个商品每笔订单的销售情况，尤其和退款订单匹配不上的问题

5、增加“提成”概念：等于之前的收入比率*分成比率，直接帮淘客算好能获得的比率，简单概念

6、pub端（指淘宝联盟官网pub.alimama.com）将”淘宝客推广明细“和”第三方服务商明细“整合到一起，解决淘客不能一次看全或下全订单的问题

7、切换底层数据表，解决之前订单明细加起来和效果统计数据对不上的问题

8、优化底层性能，解决媒体每秒获取订单受限问题(能承受度变高极多)，日常、大促批量获取订单更顺畅。

二、订单接口名词解释：

1、订单类型名词：什么是2方订单，什么是3方订单？

2方订单：就是你自己推广的订单，你自己拥有这笔订单完全佣金。

3方订单：就是你推广的客户，在领了你的淘口令或推广链接后，去下单过程中，在购物车上用了别的淘客的红包，导致订单变成别人的，而你只有这笔订单产品普通“通用佣金”的一半，而不是高佣了。

2、订单状态名词：

付款状态：这时订单已付款，等待商家发货。状态值12

订单成功：表示买家确认收货，这时状态值是14，此时一般很快就进入结算，转成状态3，并生成tk_earning_time（结算时间）值，但有的订单收完货后，联盟和商家间没有完成结算，就会导致状态值停留在14，这时返回值就没有tk_earning_time字段。

订单结算：表示在买家确认收货后，联盟和卖家结算完佣金了。这时状态是3。也就是说14状态是在3前面。

注意这时的结算不是联盟和你结算，是和卖家结算。每个月20号联盟才跟你结算佣金。

 一般买家确认收货后就变成结算状态3，少数异常情形，比如淘宝卖家帐户余额不足等，会导致一直卡在14状态值。

订单失效：表示下了单但关闭订单等情形。以及付款后全额申请退款，此时状态值13

订单维权：维权单是指付款后收到货申请部分退款，如退运费，这些订单是维权订单。维权订单依然是成功，具体参下文

3、订单接口可以查询什么样的订单？

目前订单接口不能查询“未付款”的订单，包括下了单但没付款就关闭的订单，

可以查询“已付款订单”。

三、【必知】订单的查询时间跨度：

订单查询时间跨度为“订单开始时间start_time至结束时间end_time查询时长，中间时间段跨度日常要求不超过3个小时，但如“618、双11、双12、年货节”等大促期间预估时间段不可超过20分钟（推荐使用20分钟），超过会提示错误，调用时请务必注意时间段的选择，以保证能正常调用！

当大促开始时，官方没有确定哪一天开始从日常3小时查询时间跨度改为20分钟，因此当您收到接口返回msg提示时，请及时调整，最好做一个判断，方便程序自动调整。

订单查询API最多只能查到三个月内的订单，时间超过3个月的订单获取不到。

四、联盟官方推荐的订单获取频率

 新订单api节省调用量拉取攻略

订单api支持淘客创建时间、淘客付款时间、淘客结算时间3个查询维度，下面以淘客付款时间为例说明，其它查询维度相似。
如果查询最近20分钟有哪些订单进行了付款，建议选择淘客付款时间，
首次查询时间段设置为最近20分钟（指下面参数中的start_time和end_time时间间距），则系统会按淘客付款时间倒序分页返回订单，下一次拉取时间点向后推移20分钟，
比如00:20拉取00:00～00:19之间的订单，00:40拉取00:20～00:39之间的订单，01:00拉取00:40～00:59之间的订单，
依次类推，拉取一天所有订单。其中，查询时间段越小，性能和实时性会越好。

【重要】更多查询计划建议，请参考 http://www.veapi.cn/taokelianmeng/318.html 

五、【重要】如何判断双11预售订单？

参考http://www.veapi.cn/taokelianmeng/529.html 

六、淘宝联盟订单接口如何计算佣金？

新版订单接口返回值中直接就已经有佣金计算字段了，分别是“付款预估收入pub_share_pre_fee”和“结算预估收入pub_share_fee”，分别适用于订单在结算前和结算后。

直接取这2个字段即可得到佣金计算值：

1、订单结算前：

pub_share_pre_fee 付款预估收入=付款金额*提成。

指买家付款金额为基数，预估您可能获得的收入。因买家退款等原因，可能与结算预估收入不一致

2、订单结算后：

pub_share_fee 从结算佣金中分得的收入，结算预估收入=结算金额*提成。

以买家确认收货的付款金额为基数，预估您可能获得的收入。因买家退款（维权订单，参考下文第6节）、违规推广等原因，可能与您最终收入不一致。最终收入以月结后您实际收到的为准。

如果有进行内容场景推广，还需要减去专项的技术服务费用，公式：

1、订单结算前：

pub_share_pre_fee - tk_commission_pre_fee_for_media_platform （预估专项服务费）

2、订单结算后：

pub_share_fee - tk_commission_fee_for_media_platform （结算专项服务费）

七、如何查询渠道订单？为什么订单中没有渠道id（relation_id）：

很多客户困惑于怎么查询渠道订单，或不知道为什么订单中没有渠道ID（relationId），在这里统一说明：

1、如何生成渠道订单？必须在高佣转链环节（即领券阶段）满足2个条件：A、传递relationId参数，B、PID参数必须使用渠道专属PID。

满足这2个条件的高佣转链淘口令或推广链接，下的订单才有可能是渠道订单。

渠道专属PID在哪找？

进入联盟后台，在“推广管理—>渠道管理—>渠道专属推广位”可看到专属PID，如果没有可以在这里创建

2、正常下单：首先要确保你有渠道订单，可以在淘宝联盟后台“效果报表—>渠道效果报表”那查看，如果联盟后台没有看到渠道订单，可能有2个原因：A、可能第一步转链环节参数不正确，请检查。B、客户下单过程出现异常，比如用了别人的红包，比如双11的超红。

3、请到“联盟后台——效果报表——渠道订单”项下看看是否有这笔订单。

4、查订单时加参数order_scene=2：当联盟后台效果报表看到渠道订单后，就可以查到渠道订单relationId。

5、如果订单是第三方订单，还需要加参数member_type。

6、注意时间参数，默认是订单创建时间，而联盟后台默认显示是付款时间（需要下载EXCEL会看到创建时间），当您没有查询到订单，请注意本参数类型是否正确。

总之，调试时，在保证有渠道订单的情形下，若未找到渠道订单，把所有参数都细细检查一下就可以了。

八、如何处理维权订单（维权指申请退款的订单）：

现在维权订单（维权即有退款订单）主要是靠新订单接口中refund_tag字段为1时，就多多注意这些维权订单，

暂时还没有办法通过接口来获取维权订单，订单接口不会根据维权情况变更订单金额和订单状态（也就是说，即使客户维权成功退款一部分金额，但订单接口的金额和订单状态仍然不会变化），因此暂时无法通过接口来判断订单的维权详情。目前接口只能做到返回refund_tag字段告知是维权订单。

您可以到联盟后台“效果报表—订单明细报表—维权退款订单”对照。下载EXCEL导入到你的系统进行处理。这需要你开发相应的系统解析EXCEL文件。

对于渠道维权订单，你可以用维权接口查询，参考http://www.veapi.cn/apidoc/taobaolianmeng/94   ，该接口还不能查普通维权订单。

九、如何区分饿了么订单？

订单API里有个字段 order_type 标了“饿了么”的，可以筛选出“饿了么”订单。

这里有一个饿了么从“推广—下单—查订单”的全过程演示：

http://www.veapi.cn/taokelianmeng/482.html

另外，饿了么订单号也比普通淘客订单的订单号短，比如“2100042665”，

附：新零售和餐饮订单有什么不同？

可以按照一级类目来区分。

【饿了么餐饮一级类目】快餐便当、特色菜系、全球美食、小吃夜宵、甜品饮品、香锅火锅

【饿了么新零售一级类目】商店超市、鲜花绿植、医药健康、水果、厨房生鲜

十、淘宝联盟订单查询接口的子订单号和父订单号是什么区别？怎样区分每个订单

请参考：http://www.veapi.cn/taokelianmeng/273.html 

十一、必读-重要升级：订单明细报表升级【官方通知】

https://qn.taobao.com/headline/news/10698445?spm=a211vu.12026430.0.0.1fff3929P0kYHO 

十二、其它常见问题：

1、【特别强调】为什么我的获取的订单号和联盟后台不一致？

以PHP开发为例，因为订单返回值中的订单号是长整数，有的人会发现：把接口返回值转成数组时，PHP把订单号转成科学计数法，导致最终保存的订单号和联盟上的订单一致。解决办法：

转数组时用 json_decode($resp, true , 512 , JSON_BIGINT_AS_STRING); 同时，你的数据库保存订单号字段要用varchar类型。

其它语言也存在这个问题，比如node.js，请自行百度该语言处理长整型数据。

tip: 在浏览器显示时，请使用 json-handle 插件，才能正确显示订单号，其它插件不能正确显示订单号。

2、如何判断是比价订单？

新增字段 flow_source，值为“自主推广”，就表示比价订单。

3、淘客订单接口相关参考：

《订单报表名词解释》http://www.veapi.cn/taokelianmeng/428.html

《有时淘宝联盟APP有订单而淘宝联盟PC端没有？》http://www.veapi.cn/taokelianmeng/432.html

《订单接口为什么有时获取的订单数量变少了？》http://www.veapi.cn/taokelianmeng/423.html 

《淘宝订单查询接口的返回值中，哪个是付款字段？》http://www.veapi.cn/taokelianmeng/264.html 

《如何区分订单是哪个客户下单的？如何用PID绑定订单和客户？》http://www.veapi.cn/taokelianmeng/265.html

《淘宝联盟APP中订单预估收入和详情页预估收入有误差？》http://www.veapi.cn/taokelianmeng/348.html

《淘宝客维权订单接口在退款过程状态值怎么变？》http://www.veapi.cn/taokelianmeng/373.html