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

文档中心 > 基础技术

天猫换货业务接口说明

更新时间:2018/01/30 访问次数:11869

一、说明

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

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

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


二、换货流程

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

image | center


三、换货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(凭证图片)、外,还有一些其他参数的含义需要进行更为详细的论述与介绍。下面将逐一对这些需要注意的参数进行说明:

  • fields

fields指的是api接口所返回对象所对应的各个字段。基于换货api接口的功能,可以将其分为三类:

  1. 换货单对象返回字段: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(买家收货姓名)

  2. 留言返回字段:id(留言id)、refund_id(换货单号)、owner_id(留言者id)、owner_nick(留言者昵称)、owner_role(留言者角色)、content(留言内容)、pic_urls(凭证图片url)、created(留言创建时间)、message_type(留言类型:系统/人工)

  3. 拒绝原因返回字段:reason_id(拒绝原因id)、reason_text(拒绝原因文本)

  • operator_role(s)

用于卖家查询换货留言列表的api接口**tmall.exchange.messages.get**当中,指的是卖家操作角色,具体含义为:卖家主账户(1)、卖家子账户(2)、小二(3)、买家(4)、系统(5)、系统超时(6)

  • dispute_type

用于卖家查询换货列表的api接口**tmall.exchange.receive.get**当中,指申请换货的类型,具体含义为:任意类型(0)、售中申请(1)、售后申请(2)

  • 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.调用场景

image | center

  • 所有的功能类换货api接口,如tmall.exchange.refuse、tmall.exchange.agree等,只能针对属于卖家应当处理且处于特定换货状态的换货单

  • 所有的查询类换货api接口,如tmall.exchange.receive.get、tmall.exchange.get、tmall.exchange.messages.get等,卖家可以随时调用

  • 对于创建换货留言的api接口tmall.exchange.message.add,卖家可以调用其在任何仍处于换货流程中的换货单来创建留言

4.注意事项

  • 库存的校验与扣减发生在买家同意换货的操作之后。在买家点击同意换货时,系统会对消费者申请换货的商品的对应库存进行校验,如仍有库存则先预占库存,如没有库存则会给予卖家响应提示。同时,如果在指定时间后如果卖家并未同意或拒绝换货申请,那么系统会根据库存校验的结果自动对买家的换货申请进行处理,如有库存则同意申请,如无库存则拒绝申请

  • 对于买家提交的换货申请,如果卖家拒绝,则整个换货流程将关闭,买家只能再次重新发起申请;而在买家已发货等待卖家确认收货时,如果卖家拒绝确认收货,则买家既可以重新修改换货申请,也可以申请客服介入

  • 换货相关的所有api接口均允许有权限的子账号处理,即可通过子账号授权获取得到的SessionKey或者AccessToken来调用各个接口。如何使用子账号授权请参考此处

  • 卖家同意换货功能的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
返回
顶部