维易淘客联盟接口开发文档:新版淘客订单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、优化底层性能,解决媒体每秒获取订单受限问题(能承受度变高极多),日常、大促批量获取订单更顺畅。


新版订单查询API注意点:

新报表从2019-04-23以后产生的订单开始查看,之前产生的订单,可点击“历史报表”,还是看原来的几张明细报表

若在2019-04-23之前产生的订单,发生维权退款,则仍需在历史报表“淘宝客维权退款”明细中查看。


订单接口名词解释:

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

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

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


2、订单状态名词:

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

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

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

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

订单失效:表示下了单但关闭订单等情形。



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

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

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时间。

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-结算成功;不传,表示所有状态。

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 插件,才能正确显示订单号,其它插件不能正确显示订单号。


返回值如下,字段含义参考官方文档 :


四、新版淘宝联盟订单接口如何计算佣金?

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

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


1、订单结算前:

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

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


2、订单结算后:

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

以买家确认收货的付款金额为基数,预估您可能获得的收入。因买家退款、您违规推广等原因,可能与您最终收入不一致。最终收入以月结后您实际收到的为准


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

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会看到创建时间),当您没有查询到订单,请注意本参数类型是否正确。


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



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

《订单报表名词解释》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 

 

客服

关注