一、基础订单说明

订单是卖家的核心数据，卖家的日常工作都是围绕着订单展开，应用的基本功能就是要保证订单获取的及时性、完整性，以及把获取的字段转化为业务语义展示给卖家做后续处理。

平台提供订单同步有两种方式：1、通过交易API获取订单数据。2、通过rds订单推送服务获取订单。本文主要介绍淘宝订单的基本逻辑和使用订单API的方案。推荐使用rds订单推送，由平台根据订单的实时变化，按照API的字段获取订单最新信息，然后推送到开发者RDS数据库中，具体使用方法请 查看这里 ；

1. 基础概念

1）主&子订单关系

一个主订单（trade）下可能有一个或者多个子订单（order）。产生的原因，用户在使用购物车时，如果购物车中添加了某一店铺多个不同的商品并且进行下单，这次购物车的下单就会生成一笔主订单，购物车中的每个尺码不同的商品（num_iid+sku_id）就变成一个单独子订单（order）。不使用购物车直接下单，会生成一个主订单包含一个子订单。

2）订单正向链路的一般逻辑

第一步、消费者创建订单还未付款 ，订单状态：WAIT_BUYER_PAY；第二步、消费者付款进入卖家发货阶段，订单状态：WAIT_SELLER_SEND_GOODS；第三步、卖家发货，订单状态：WAIT_BUYER_CONFIRM_GOODS；第四步、消费者确认收货，订单状态：TRADE_FINISHED。其他状态根据买卖家操作不同或者订单类型（type）不同会有变化。

3）订单其他状态的逻辑说明

订单创建后买家可以主动放弃付款，卖家也可以主动关闭订单，订单会直接关闭；

订单已付款后买家可以发起退款，此时卖家可以同意退款订单会关闭，卖家也可以做发货操作，订单进入下一个状态；

订单已发货后买家可以发起退款退货流程，进入买卖家协商流程，参考退款退货场景说明。

交易完成后，买家能发起售后维权流程，这部分订单目前交易接口无法处理。

4）关于订单常用金额说明

商品级优惠：对单个商品的，常见如 商品原价的8折；商品原价的减50元。

订单级优惠：对主订单的优惠，常见的，店铺优惠券10元；订单满200元减10元；订单满80包邮。

以一个订单为例，主要使用的金额字段：payment（主订单实付金额），discount_fee（主订单优惠），post_fee（订单邮费）， promotion_details(订单优惠信息明细，商品和订单级优惠一般都在里面)，order.payment（子订单实付金额，不算主订单分摊金额），order.discount_fee（子订单商品优惠），order.price（商品原价），order.num（商品数量） ,part_mjz_discount(子订单分摊金额)，divide_order_fee （分摊后子订单实付金额）

详细说明：点击查看 。

5）关于订单发票金额说明

针对订单付款后最终的开票给消费者金额和开票给天猫金额，提供了单独接口获取淘宝订单页面上的返回结果。

taobao.trade.invoice.amount.get 获取订单最终开票金额， 该接口仅在订单需要开票时调用使用，避免大批量调用。推荐商家服务商开票功能直接使用 阿里电子发票平台 功能。

6）关于订单类型说明

大淘宝有很多不同的商品交易类型，不同类型商品在购买、交易、履约、逆向链路都不同，为了区分这些订单，在订单上增加了type字段。

对于普通淘宝天猫店商家type不用传入，taobao.trades.sold.get 接口会默认查询fixed(一口价)auction(拍卖)step(分阶段付款，万人团，阶梯团订单）auto_delivery(自动发货) ec(直冲) cod(货到付款) 6种状态的交易类型， 基本满足普通商家的交易处理需要。

对与海外旗舰店商家，type必须传入tmall_i18n（天猫国际） 才能获取店铺订单。对于有电子凭证商品的商家，type必须传入eticket(电子凭证) 才能获取电子凭证订单。涉及到其他特殊交易类型商家，可以先找一笔该店铺的订单号通过taobao.trade.fullinfo.get接口查询type类型， 再传入对应的type类型用批量接口查询。

?

2. 订单敏感信息安全规范

平台为了更好的保障用户信息的安全、提升服务商应用对于用户敏感信息的安全防护能力，提升服务商应用的安全性，降低用户数据泄露或者被恶意修改的风险。

淘宝开放平台定义订单R2相关隐私数据（包括收货人、联系方式、收货地址等用户信息）需要从聚石塔ECS内请求获取和使用，具体的安全规范说明：点击查看 。

二、API介绍

taobao.trades.sold.get - 获取三个月内已卖出的在线订单，适用于用户初始化的时候使用

taobao.trade.fullinfo.get - 获取单笔订单详情。

taobao.trades.sold.increment.get – 获取增量订单列表，适用于做订单增量同步，获取一段时间内发生状态或信息变化的订单。

使用方法：先通过批量接口获取订单id列表，然后再通过详情接口获取每笔订单的详细字段。

三、实施方案

订单同步主要分为初始化和增量获取两个步骤：

1）初始化是把3个月内的在线订单全部同步回来，这个需要较长的时间；

2）增量获取则是把淘宝发生了变更的订单同步回来，这个一般需要较短的时间。

下面的方案都会围绕着如何初始化和增量获取来讲。?

?

方案一

1）同步流程

2）核心步骤

① 三个月数据：通过taobao.trades.sold.get获取3个月内到现在创建的订单ID，再通过taobao.trade.fullinfo.get获取订单详情；

② 增量数据：通过taobao.trades.sold.increment.get获取从现在开始的增量订单ID，再通过taobao.trade.fullinfo.get获取订单详情。

3）适用范围

适用于ISV测试订单同步功能或生产环境的中小卖家进行订单同步。此方案比较低效，除非老的应用更新成本很高，否则不推荐大家使用，建议采用下面的方案。

方案二

1）同步流程

2）核心步骤

① 首先，通过taobao.trades.sold.get获取3个月内到昨天23:59:59创建的订单详情；

② 然后，通过taobao.trades.sold.increment.get获取从今天00:00:00到现在的增量订单ID，再通过taobao.trade.fullinfo.get获取订单详情；

③ 增量数据：通过消息服务客户端实时监听订单变更消息，再通过taobao.trade.fullinfo.get获取订单详情。

3）适用范围

适用于所有类型的卖家，是所有方案中相对复杂，但效率最高的方案，推荐所有ISV采用。

跟上面两个方案进行比较，推荐开发者使用的是订单同步服务使用，该效率最为高效。

四、经验分享

1. 漏单问题

通过taobao.trades.sold.get和taobao.trades.sold.increment.get获取订单时，交易类型type入参默认只查询部分类型的订单，要查询所有类型的订单，必须显式提供所有交易类型作为type入参。

通过taobao.trades.sold.increment.get获取增量订单时，返回结果是按订单修改时间倒序排序的，分页必须从后往前翻，防止正向翻页过程中订单发生变更而导致漏单。

通过taobao.trades.sold.increment.get获取增量订单时，每次获取的起始时间适当前移10分钟左右（双11大促时建议前移30分钟左右），防止极端情况下由于淘宝系统压力而导致订单延迟更新到数据库而产生的漏单。

通过主动通知接收订单变更消息时，需要处理服务器重启或网络断开连接而导致的消息丢失问题，详细内容请查看消息服务。

2. 性能问题

1）taobao.trades.sold.get获取三个月已卖家的订单

① 采用入参use_has_next=true的分页方式可以避免每次API请求对淘宝数据库产生的count(*)，从而显著提升速度和稳定性。

② 由于获取三个月内的订单接口是用创建时间过滤的，而创建时间是不可变的，所以从前往后翻页也不会导致漏单，因而可以省掉第一步的count(*)，而直接采用入参use_has_next=true的方式分页获取，直到返回结果中has_next=false时终止翻页。

③ 如果接口返回的字段无法满足应用的需要，则强烈建议只获取fields=tid这一个字段，然后再通过taobao.trade.fullinfo.get获取订单详情。

④ 由于卖家三个月订单量比较大，建议把三个月的订单切分成按天获取，减少单次请求对淘宝数据库的记录扫描量，以提升效率。

2）taobao.trades.sold.increment.get获取增量订单

① 采用入参use_has_next=true的分页方式可以避免每次API请求时对淘宝数据库产生的count(*)，从而显著提升速度和稳定性。

② 由于获取增量订单接口是用修改时间过滤的，而修改时间是可变的，所以需要从后往前翻页才能避免漏单。从后往前翻页必须要知道最后一页，所以必须在首次API请求时采用use_has_next=false方式统计订单总数，计算出总页数，然后再设置use_has_next=true终止订单统计，从后往前翻页。

③ 如果接口返回的字段无法满足应用的需要，则强烈建议只获取fields=tid这一个字段，然后再通过taobao.trade.fullinfo.get获取订单详情。

3）使用taobao.trades.sold.get/taobao.trades.sold.increment.get只获取tid字段时，建议设置page_size为最大值，减少API请求次数，提升效率。获取多个字段时可根据自身的网络情况设置page_size，建议设置为50左右。

3. 异常处理

1）同步订单一般会采用多线程处理，由于API请求对APP是有频率限制的，所以设置线程池大小时，需要根据TOP允许的API调用频率来设置，避免限流后导致应用长时间无法调用API。

2）对于API返回的ISP类型的错误或网络连接错误，应用线程应该在休眠片刻中自动重试。而对于API返回的ISV类型的错误，应用需要记录日志以便日后排查，同时不要重试。

五、预售场景

1. 业务流程

2. 预售的业务逻辑

预售订单与一口价订单存在差异，在订单处理中对预售订单要单独处理。

a. 预售订单类型与一口价不一样，type为step，卖家ERP在筛选订单时，需要增加对这一类订单的同步。

b. 预售订单有单独的预售订单交易状态，由于尾款未付的情况下，订单状态不会变化，在关注订单状态外，还需要关注订单的预售交易状态，包括以下三种：

1）FRONT_NOPAID_FINAL_NOPAID(定金未付尾款未付),对于这一类状态的订单，卖家ERP中可暂不处理；

2）FRONT_PAID_FINAL_NOPAID（定金已付尾款未付），对于这一类订单，可以保持HOLD状态，继续等待并且着手准备排期；

3）FRONT_PAID_FINAL_PAID（定金和尾款都付），对于这一类订单，需要安排发货。

预售业务中定金已付，卖家不支付尾款的订定金金是不做退回的，因此，商家在做账的时候，需要针对这一部分在做账时进行处理。

3. 实施方案

预售业务需要关注以下API。

a. type的可选值：step;

b. 参数返回值

Trade. step_trade_status（分阶段付款的订单状态，例如万人团订单等，目前有三返回状态：

1）FRONT_NOPAID_FINAL_NOPAID(定金未付尾款未付)；

2）FRONT_PAID_FINAL_NOPAID(定金已付尾款未付)；

3）FRONT_PAID_FINAL_PAID(定金和尾款都付)）；

Trade. step_paid_fee（分阶段付款的已付金额，万人团订单已付金额）；

Trade. send_time（预约配送时间，一般需按照物流服务的时间倒推，最好提前三天（按物流时效计算）开始准备发货）。