维易淘客联盟接口开发文档:新版淘客订单API

新版淘客订单API-淘宝联盟返利订单查询接口

新版淘客订单API是2019年5月24号上线最新的淘宝客订单查询接口,对新版订单接口有问题可以反馈到群里。

和旧版的订单查询接口(http://wsd.591hufu.com/doc/dingdanchaxunxiazai)相比,有以下特点:

(以下pub端是指淘宝联盟官网pub.alimama.com)

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

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

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

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

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

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

6、pub端将”淘宝客推广明细“和”第三方服务商明细“整合到一起,解决淘客不能一次看全或下全订单的问题

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

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


订单接口名词解释:

1、订单类型名词:什么是2方订单,什么是3方订单?

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

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


2、订单状态名词:

订单成功:表示买家确认收货,这时状态值是14.

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

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

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

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

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


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

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

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


一、新订单查询接口调用方法:

【调用权限】核心全能接口和订单接口会员卡
【调用接口】

http://api.vephp.com/orderdetails?vekey=xx&start_time=...&end_time=.....

【参数详解】

具体参数可以参考官方文档:https://open.taobao.com/api.htm?docId=43755&docType=2&scopeId=16322

本文档和淘宝联盟官方文档在参数名及其大小写上保持一致。


【必知】订单的查询时间跨度:

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

订单查询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之间的订单,
依次类推,拉取一天所有订单。其中,查询时间段越小,性能和实时性会越好。


以下是订单接口参数说明:

start_time 必需参数,订单查询开始时间。需2019-04-23之后的时间点,并且必须小于end_time时间。

                  示例:2019-04-05 12:18:22

end_time 必须参数:订单查询结束时间。需2019-04-23之后的时间点,且必须大于start_time时间。它和start_time时间间距为20分钟或3小时,参考上面说明。

query_type 可选参数(默认值为1):指查询时间类型,可选值:1-按照订单淘客创建时间查询,2-按照订单淘客付款时间查询,3-按照订单淘客结算时间查询。

position_index 可选参数(默认值为空):位点,除第1页之外,其它页都需要传递本参数。用法:本参数把第一页调用的返回值position_index,做为第2页的入参即可。同样,第2页的position_index返回值,做为第3页的入参。

page_no 可选参数(默认值1):页码

page_size 可选参数(默认值20,最大值100):每页返回的订单最大笔数

member_type 可选参数(默认值为空,表示所有角色):推广者角色类型,2:二方,3:三方,不传则表示所有角色。

tk_status 可选参数(默认值为空,表示所有状态):淘客订单状态:12-付款,13-关闭,14-确认收货,3-结算成功;不传,表示所有状态。注意:如果一个订单全额退款,这时订单是失效关闭状态,虽然它付款过,但此时关闭状态,你用tk_status=12是查不到的,必须用tk_status=13或不用这个参数才能查的到。

jump_type 可选参数(默认值1):跳转类型,当向前或者向后翻页必须提供,-1: 向前翻页,1:向后翻页

order_scene 可选参数(默认值1):场景订单场景类型,1:常规订单,2:渠道订单,3:会员运营订单,默认为1

sessionkey:多用户专用。如果您的会员卡是多用户版订单查询接口,若要查不同的帐号,请提供该帐号授权的sessionkey值,

【特别提示】

order_scene默认值1是查常规订单,如果您想查渠道订单,务必设置order_scene=2,

同理,查会员订单order_scene=3。

否则不会返回relation_id和special_id值。



二、订单查询接口调用频率:

【重要】在调用订单接口前,请了解一下 要如何安排订单查询频率?


三、新订单接口返回值:

返回值字段类型参考官方文档:https://open.taobao.com/api.htm?docId=43755&docType=2&scopeId=16322   

注意新旧订单接口部分订单字段名有变动。

接口返回的订单默认是按订单创建时间倒序

关于订单佣金如何计算,参考下文第4节。


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

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

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

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

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


【订单返回值】

字段含义参考官方文档 https://open.taobao.com/api.htm?docId=43755&docType=2&scopeId=16322

双11时注意这几个字段:

tk_deposit_time 预售时期,用户对预售商品支付定金的付款时间,可能略晚于在淘宝付定金时间

tb_deposit_time 预售时期,用户对预售商品支付定金的付款时间

deposit_price 预售时期,用户对预售商品支付的定金金额

返回值字段变动官方公告:

淘宝客私域用户管理产品上线渠道专项服务费后,订单API在5月22日进行相关字段更新。变更信息如下:

①新增“渠道专项服务费”、“渠道专项服务费率”字段;

②原“专项服务费”、“专项服务费率”字段名称更新成“内容专项服务费”、“内容专项服务费率”



附1:

[新返回值]:新增字段 flow_source,值为“自主推广”,就表示比价订单。

附2:

淘宝联盟订单查询接口的子订单号trade_id和父订单号trade_parent_id是什么区别?

参考:http://wsd.591hufu.com/taokelianmeng/273.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个条件。

3、查订单时加参数order_scene=2,就可以查到渠道订单relationId。

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

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


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


六、如何处理维权订单:

现在维权订单主要是靠新订单接口中refund_tag字段为1时,就多多注意这些维权订单,

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

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


七、如何区分饿了么订单?

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

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

http://wsd.591hufu.com/taokelianmeng/482.html

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

附:新零售和餐饮订单有什么不同?

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

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

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


八、错误码:

具体错误码参考 http://wsd.591hufu.com/doc/taobaokeapijiekoucuowuma


附:淘客订单接口相关参考:

《订单报表名词解释》http://wsd.591hufu.com/taokelianmeng/428.html

《有时淘宝联盟APP有订单而淘宝联盟PC端没有?》http://wsd.591hufu.com/taokelianmeng/432.html

《订单接口为什么有时获取的订单数量变少了?》http://wsd.591hufu.com/taokelianmeng/423.html 

《淘宝订单查询接口的返回值中,哪个是付款字段?》http://wsd.591hufu.com/taokelianmeng/264.html 

《淘宝联盟订单查询接口的子订单号和父订单号是什么区别?怎样区分每个订单》http://wsd.591hufu.com/taokelianmeng/273.html 

《如何区分订单是哪个客户下单的?如何用PID绑定订单和客户?》http://wsd.591hufu.com/taokelianmeng/265.html

《淘宝联盟APP中订单预估收入和详情页预估收入有误差?》http://wsd.591hufu.com/taokelianmeng/348.html

《淘宝客维权订单接口在退款过程状态值怎么变?》http://wsd.591hufu.com/taokelianmeng/373.html 

 

客服