文档中心 > 商家经营工具-开发指引

天猫换货业务接口说明

更新时间：2024/08/01 访问次数：57817

一、说明
二、换货流程
三、换货API接口

一、说明

本文档所面向的对象包括接入换货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可以获取到淘宝换货单。但是其他处理天猫换货单的接口目前不支持淘宝换货单。

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

淘宝开放平台

商家经营工具-开发指引