退款退货场景
一、 说明
本文档面向对象为接入退款退货API开发天猫商家退款退货管理功能的第三方开发者(下文简称:isv)或自主开发的商家。
本文档将涵盖API调用场景及注意事项,天猫与集市的退款退货API将统一为一大套接口对外开放;API权限通过证书中心进行申请,处理时间一般为5个工作日以内。
对于原有已经接入tmall.eai.*接口进行天猫退款退货处理的,在处理具体退款单时,务必先重新同步一次退款数据。
问题交流群请加入:
1408358214
二、 调用流程
三、 退款状态变化
退款单的状态可以在Refund数据结构中的Status获取,会根据退款操作的变化而变化。
关于退款单状态的变化情况请参考上文天猫退款退货流程,以下列表仅做描述,现有的退款单状态:
API | 描述 | 说明 |
WAIT_SELLER_AGREE | 买家已经申请退款,等待卖家同意 | 买家提交退款申请时的状态 |
WAIT_BUYER_RETURN_GOODS | 卖家已经同意退款,等待买家退货 | 退款申请包含退货时,卖家同意退货(后台或者taobao.rp.returngoods.agree)后的状态 |
WAIT_SELLER_CONFIRM_GOODS | 买家已经退货,等待卖家确认收货 | 退款申请包含退货,买家上传退货物流信息后的状态 |
SELLER_REFUSE_BUYER | 卖家拒绝退款 | 卖家拒绝退货或者拒绝退款时 |
SUCCESS | 退款成功 | 卖家批量同意退款操作后的状态 |
CLOSED | 退款关闭 | 退款申请超时或者未发货的订单申请退款时卖家强制发货后的状态 |
四、 FAQ
1. 批量同意退款(taobao.rp.refunds.agree)操作说明
taobao.rp.refunds.agree接口仅允许子账号授权调用,并且集市支持批量(20笔以内,总金额6000以内),天猫支持30笔以内,总金额10000以内。 该接口分两个阶段,第一次不带Code参数,系统会发送验证码到当前授权所代表的子账号用户注册的手机上,第二次带Code参数(参数内容为验证码),执行同意退款打款操作,调用成功,则直接将支付宝打款给买家。
当前调用 API所用的子账号必须在子账号后台授权退款操作的权限,并设定具体的操作限额。
入参refund_infos说明
对于集市,包含信息如下:RefundId(退款单ID)、Fee(退款金额)、Version(通过Refund数据结构获取)
对于天猫,包含的数据有退款ID|其对应的金额|对应版本号列表|退款阶段(onsale\aftersale),其中金额以分为单位,ID与金额以“|”符号分隔,多笔订单以“,”分隔
格式:
RefundId1|Fee1|Version1|Refund_phase,RefundId2|Fee2|Version2|Refund_phase ...
示例:
192242532288979|6000|12312|onsale,192242532298979|6000|32112|onsale
判断是否退款成功
success为true时,不一定全部成功,ISV需要取到results后逐个判断是否成功
2. 如何知道是否有退货?
通过Refund. has_good_return判断,true为既退款又退货,false仅退款
3. 如何获取退款单的refund_phase和refund_version
可以通过查询接口从Refund中获取
4. 买家修改退款申请后卖家操作退款单有什么影响
买家修改退款申请后,退款的refund_version会变化,退款操作时会校验refund_version,在操作中可以通过taobao.refund.get接口查询具体退款单的Refund信息。
5. 天猫暂时不支持退款留言的操作;
6. 目前不支持同意退款接口只调用一次即完成退款操作,由于接口调用会直接打款至支付宝,基于安全必须通过获取短信的方式完成退款。
7. 目前仅对同意退款操作要求仅允许子账号授权操作退款,即使用子账号授权获取到的SessionKey或者AccessToken调用taobao.rp.refunds.agree。如何使用子账号授权参考:
//open.taobao.com/doc/detail.htm?spm=a219a.7386797.0.0.dXrNao&id=101141
特别需要注意,需要保证该子账号拥有客户服务-售中售后管理-同意退款(集市需要交易管理-子账号售中退款-同意子账号退款)的权限点。
8. 沙箱不支持同意退款的调试
9. 同意退款接口返回的error_code列表有:
编号 | 含义 |
10000 | 发送二次验证短信成功 |
10001 | 发送二次验证短信失败 |
10002 | 二次验证码前5分钟内已发出 |
10003 | 验证短信码失败 |
10004 | 短信验证码超时(15分钟) |
10005 | 没有输入短信验证码 |
10006 | 请先获取验证码 |
20000 | 申请退款笔数超过限制 |
20001 | 申请退款金额超过限制 |
30000 | 退款编号不合法 |
30001 | 退款不存在 |
30002 | 天猫订单 |
40000 | 操作成功 |
40001 | 操作失败 |
40002 | 部分操作失败 |
40003 | 操作失败 系统异常 |
50000 | 非子帐号 |
60000 | 退款单版本已经发生变化 |
60001 | 申请金额与其实不合 |
99999 | 其它异常 |
五、 涉及API
API文档链接:
//open.taobao.com/doc/api_cat_detail.htm?scope_id=11527&category_id=102
API | 功能描述 |
taobao.user.seller.get | 查询商家信息 |
taobao.refunds.receive.get | 查询退款列表 |
taobao.refund.get | 查询单笔退款 |
taobao.rp.returngoods.refuse | 拒绝退货 |
taobao.rp.returngoods.agree | 同意退货 |
taobao.rp.returngoods.refill | 天猫商家回填退款物流单号 |
taobao.rp.refund.review | 退款单标记 |
taobao.refund.refuse | 拒绝退款 |
taobao.rp.refunds.agree | 批量同意退款 |
FAQ