注意:以下文档只适用于TOP接口,请谨慎使用!

文档中心 > 基础技术

天猫换货业务接口说明

更新时间:2023/04/03 访问次数:53275

一、说明


本文档所面向的对象包括接入换货API开发天猫商家换货处理功能的第三方开发者(下文简称为:isv)或进行自主开发的商家。

本文档主要涵盖换货流程介绍与换货API接口说明两个部分。其中,换货API接口说明主要包括了对API的具体功能、常用出参与入参、具体调用场景及注意事项等几个方面。

注:API权限通过证书中心进行申请,处理时间一般为5个工作日以内。


二、换货流程


当前换货的基本流程(状态机)如下图所示,其中红色箭头线表示由买家发起的操作,蓝色箭头线表示由卖家发起的操作。大图请点击此处


image.png


三、换货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**。


四、FAQ


Q:换货的top接口是否已对接RDS?

A:暂时未对接RDS。


Q:换货是否支持沙箱调试?

A:沙箱不支持同意换货的调试。


Q:如何申请换货TOP接口的权限?

A:已经有自研发后台系统的APPKEY,只用在后台申请API权限。如果你们系统是第三方服务商开发的,请联系第三方ERP服务商。


FAQ

关于此文档暂时还没有FAQ
返回
顶部