基础技术
一、说明
本文档所面向的对象包括接入换货API开发天猫商家换货处理功能的第三方开发者（下文简称为：isv）或进行自主开发的商家。
本文档主要涵盖换货流程介绍与换货API接口说明两个部分。其中，换货API接口说明主要包括了对API的具体功能、常用出参与入参、具体调用场景及注意事项等几个方面。
注：API权限通过证书中心进行申请，处理时间一般为5个工作日以内。
二、换货流程
当前换货的基本流程（状态机）如下图所示，其中红色箭头线表示由买家发起的操作，蓝色箭头线表示由卖家发起的操作。大图请点击此处。
三、换货API接口
1. 具体功能
api接口名称 |
功能介绍 |
tmall.exchange.receive.get |
卖家查询换货列表 |
tmall.exchange.get |
查看换货详情 |
tmall.exchange.messages.get |
查询换货留言列表 |
tmall.exchange.message.add |
卖家创建换货留言 |
tmall.exchange.refusereason.get |
获取拒绝换货原因列表 |
tmall.exchange.agree |
卖家同意换货申请 |
tmall.exchange.refuse |
卖家拒绝换货申请 |
tmall.exchange.returngoods.agree |
卖家确认收货 |
tmall.exchange.returngoods.refuse |
卖家拒绝确认收货 |
tmall.exchange.consigngoods |
卖家发货 |
详细说明请 点击此处。
2. 参数总结
在换货相关的api接口所包含的各个参数中，除去常用的dispute_id（换货单号）、leave_message_pics（凭证图片）、外，还有一些其他参数的含义需要进行更为详细的论述与介绍。下面将逐一对这些需要注意的参数进行说明：
1）fields
fields指的是api接口所返回对象所对应的各个字段。基于换货api接口的功能，可以将其分为三类：
① 换货单对象返回字段：dispute_id(换货单号id), bizorder_id(正向交易子订单号id),alipay_no(正向交易主订单号), buyer_nick(买家昵称),seller_nick(卖家昵称), num(换货数量), status(当前换货状态), good_status(当前商品状态),created(换货创建时间), modified(换货修改时间), reason(申请换货理由), title(商品名称), buyer_logistic_no(买家发货物流单号), seller_logistic_no(卖家发货物流单号), price(商品价格), sku(所购买sku), exchange_sku(申请换货的sku), buyer_address(买家收货地址), address(卖家收货地址), time_out(超时时间)、buyer_logistic_name（买家发货物流公司名）,seller_logistic_name（卖家发货物流公司名）, buyer_phone(买家联系方式), buyer_name(买家收货姓名)；
② 留言返回字段：id(留言id)、refund_id（换货单号）、owner_id(留言者id)、owner_nick(留言者昵称)、owner_role(留言者角色)、content(留言内容)、pic_urls(凭证图片url)、created(留言创建时间)、message_type(留言类型：系统/人工)；
③ 拒绝原因返回字段：reason_id(拒绝原因id)、reason_text(拒绝原因文本)。
2）operator_role(s)
用于卖家查询换货留言列表的api接口**tmall.exchange.messages.get**当中，指的是卖家操作角色，具体含义为：卖家主账户(1)、卖家子账户(2)、小二(3)、买家(4)、系统(5)、系统超时(6)。
3）dispute_type
用于卖家查询换货列表的api接口**tmall.exchange.receive.get**当中，指申请换货的类型，具体含义为：任意类型(0)、售中申请(1)、售后申请(2)。
4）dispute_status_array
用于卖家查询换货列表的api接口**tmall.exchange.receive.get**当中，指每笔换货纠纷单当前所处的状态，主要包括：换货待处理(1), 待买家退货(2), 买家已退货，待收货(3), 换货关闭(4), 换货成功(5), 待买家修改(6), 待发出换货商品(12), 换货转退款(14)。其对应具体信息如下所示：
换货状态ID |
当前换货状态说明 |
top接口输出状态 |
1 |
买家已经申请换货，等待卖家同意换货申请 |
换货待处理 |
2 |
卖家已经同意换货，等待买家退货 |
待买家退货 |
3 |
买家已经退货，等待卖家确认收货 |
买家已退货，待收货 |
4 |
换货关闭 |
换货关闭 |
5 |
换货成功 |
换货成功 |
6 |
卖家拒绝确认收货，等待买家修改换货申请 |
待买家修改 |
12 |
卖家确认收货，等待卖家发货 |
待发出换货商品 |
14 |
换货关闭，转退货退款 |
请退款 |
3. 调用场景
1）所有的功能类换货api接口，如tmall.exchange.refuse、tmall.exchange.agree等，只能针对属于卖家应当处理且处于特定换货状态的换货单；
2）所有的查询类换货api接口，如tmall.exchange.receive.get、tmall.exchange.get、tmall.exchange.messages.get等，卖家可以随时调用；
3）对于创建换货留言的api接口tmall.exchange.message.add，卖家可以调用其在任何仍处于换货流程中的换货单来创建留言。
4. 注意事项
1）库存的校验与扣减发生在卖家同意换货的操作之后。在卖家点击同意换货时，系统会对消费者申请换货的商品的对应库存进行校验，如仍有库存则先预占库存，如没有库存则会给予卖家响应提示。同时，如果在指定时间后如果卖家并未同意或拒绝换货申请，那么系统会根据库存校验的结果自动对买家的换货申请进行处理，如有库存则同意申请，如无库存则拒绝申请。
2）对于买家提交的换货申请，如果卖家拒绝，则整个换货流程将关闭，买家只能再次重新发起申请；而在买家已发货等待卖家确认收货时，如果卖家拒绝确认收货，则买家既可以重新修改换货申请，也可以申请客服介入。
3）换货相关的所有api接口均允许有权限的子账号处理，即可通过子账号授权获取得到的SessionKey或者AccessToken来调用各个接口。如何使用子账号授权请参考此处。
4）卖家同意换货功能的top接口中入参address_id可以从top接口**taobao.logistics.address.search**中获取，其对应属性为**contact_id**。
5） 就说tmall.exchange.receive.get、tmall.exchange.get可以获取到淘宝换货单。但是其他处理天猫换货单的接口目前不支持淘宝换货单。
