有赞云开放接口逆向交易场景对接说明
一、场景说明
用户在有赞微商城下单后申请退款，如商家需要使用第三方系统同步拉取退款维权订单，同意或拒绝退款，可参考本篇说明。由于用户退款包含两种场景，仅退款和退货退款，涉及退货退款相关场景的接口说明会包含商家退货相关接口。
逆向交易场景涉及的主要接口有：查看退款列表、查看退款详情、商家拒绝退货、商家同意退款、商家拒绝退款、卖家同意退货、商家主动退款等。
二、场景接口对接说明
1、批量查看退款信息列表场景
场景描述：用户在微商城申请退款或退货退款时，如何在微商城查看退款信息？如何通过接口查看退款信息？
——微商城后台 - 订单 - 所有订单 - 退款中即可查看用户申请退款或退货退款的订单；
——通过哪个接口可以查看买家申请的退款单列表？
（1）查看退款列表接口：youzan.trade.refund.search
（2）链接地址：https://doc.youzanyun.com/doc#/content/API/1-432/detail/api/0/131
（3）重要字段说明：
》》create_time_end：时间范围查询，退款创建的截止时间时间戳 (单位为秒) 例如:1513868400，时间戳与标准时间格式转换工具：https://tool.lu/timestamp/ ；
》》create_time_start：时间范围查询，退款创建的起始时间时间戳 (单位为秒) 例如:1513785600，工具参考如上；
》》refund_id：退款 ID，若不传则返回所有未处理的退款信息，若传了具体的退款 ID，只返回该 ID 对应的退款信息；
》》tid：订单号，操作退款的订单号；如果传了具体的订单号，结果只返回该订单中产生的退款信息；例如 E20180903203737007600006；
》》update_time_end：退款状态的更新截止时间，不同于创建截止时间；举例：如果买家在上午 10 点申请了退款，一直到晚上 8 点退款的状态都没有进一步更新（比如商家没有处理），此时接口中传入的更新截止时间就算是在晚上 8 点之后，结果也不会返回该退款消息，因为该退款的退款状态一直未更新；格式同上；
》》update_time_start：退款状态的更新起始时间，不同于退款创建的起始时间，格式同上；
（4）调用格式，通过（2）中链接访问后：
（5）HTTP 调用示例：
curl -X POST "https://open.youzanyun.com/api/youzan.trade.refund.search/3.0.0?access_token=c3220121ae0fc6c4e11123370e0d1b03" -H 'content-type: application/json' -d '{ "page_no":"1","page_size":"20","created_time_start":"1566982033","create_time_end":"1567068433"}'
（6）JAVA 调用示例：
YouzanTradeRefundSearch youzanTradeRefundSearch = new YouzanTradeRefundSearch();
//创建参数对象,并设置参数
YouzanTradeRefundSearchParams youzanTradeRefundSearchParams = new YouzanTradeRefundSearchParams();
youzanTradeRefundSearchParams.setTid("E20190711092944057400033");
youzanTradeRefundSearchParams.setCreateTimeStart(1566982033L);
youzanTradeRefundSearchParams.setCreateTimeEnd(1567068433L);
youzanTradeRefundSearchParams.setPageNo(1);
youzanTradeRefundSearchParams.setPageSize(20);
youzanTradeRefundSearch.setAPIParams(youzanTradeRefundSearchParams);
YouzanTradeRefundSearchResult result = yzClient.invoke(youzanTradeRefundSearch, token, YouzanTradeRefundSearchResult.class);
2、查看退款详情场景
场景描述：买家申请退款或退货退款后，商家如何在微商城查看退款详情？如何通过接口查看退款详情？
——显示在“退款中”列表中的订单，会有一个“买家发起维权”按钮如下图： 
——点击后即可进入退款详情界面进行查看：
——通过哪个接口可以查询买家申请的退款单详情？
（1）查看退款详情：youzan.trade.refund.get
（2）链接地址：https://doc.youzanyun.com/doc#/content/API/1-432/detail/api/0/135（3）重要字段说明：
》》refund_id，退款 ID，每个退款流程会有唯一对应的一个 ID；可以通过接口:youzan.trade.refund.search
链接：https://doc.youzanyun.com/doc#/content/API/1-432/detail/api/0/131获取，也可以通过对接有赞的消息推送服务获取：https://doc.youzanyun.com/doc#/content/MSG/1-%E4%BA%A4%E6%98%93%E9%80%80%E6%AC%BE/detail/msg/trade_refund_BuyerCreated ；
（4）调用格式：
通过（2）中链接访问后：
（5）HTTP 调用示例：
curl -X POST "https://open.youzanyun.com/api/youzan.trade.refund.get/3.0.0?access_token=c3220121ae0fc6c4e11123370e0d1b03" -H 'content-type: application/json' -d '{ "refund_id":"20190928234567890909"}'
（6）JAVA 调用示例：
YouzanTradeRefundGet youzanTradeRefundGet = new YouzanTradeRefundGet();
//创建参数对象,并设置参数
YouzanTradeRefundGetParams youzanTradeRefundGetParams = new YouzanTradeRefundGetParams();
youzanTradeRefundGetParams.setRefundId("20190928234567890909");
youzanTradeRefundGet.setAPIParams(youzanTradeRefundGetParams);
YouzanTradeRefundGetResult result = yzClient.invoke(youzanTradeRefundGet, token, YouzanTradeRefundGetResult.class);
3、商家拒绝退货场景
场景描述：当买家申请退货退款时，商家如何在微商城处理“拒绝退货”？
——微商城后台 - 订单 - 全部订单 - 退款中列表中，点击“买家发起维权”按钮进入退货退款单详情页：
——点击拒绝退款申请后，需要填写拒绝理由，买家直接收到的拒绝反馈，建议认真填写；
——通过哪个接口可以完成“商家拒绝退货”操作？
（1）商家拒绝退货：youzan.trade.returngoods.refuse
（2）链接地址：https://doc.youzanyun.com/doc#/content/API/1-403/detail/api/0/315
（3）重要字段说明：
》》refund_id：退款 ID，每个退款流程会有唯一对应的 ID，可通过退款查询接口查询，接口链接：https://doc.youzanyun.com/doc#/content/API/1-432/detail/api/0/131；
》》remark：拒绝理由，写明拒绝退货的理由；买家直接看到的反馈，建议认真填写；
》》version：退款版本号，每个退款流程对应的唯一版本号，可通过退款查询接口获取；
（4）调用格式，通过（2）中链接访问后：
（5）HTTP 调用示例：
curl -X POST "https://open.youzanyun.com/api/youzan.trade.returngoods.refuse/3.0.0?access_token=c3220121ae0fc6c4e11123370e0d1b03" -H 'content-type: application/json' -d '{ "refund_id":"2019092823456789","version":"201909099090","remark":"test"}'
（6）JAVA 调用示例：
YouzanTradeReturngoodsRefuse youzanTradeReturngoodsRefuse = new YouzanTradeReturngoodsRefuse();
//创建参数对象,并设置参数
YouzanTradeReturngoodsRefuseParams youzanTradeReturngoodsRefuseParams = new YouzanTradeReturngoodsRefuseParams();
youzanTradeReturngoodsRefuseParams.setRefundId("20190923456789902442");
youzanTradeReturngoodsRefuseParams.setVersion(2989L);
youzanTradeReturngoodsRefuseParams.setRemark("test");
youzanTradeReturngoodsRefuse.setAPIParams(youzanTradeReturngoodsRefuseParams);
YouzanTradeReturngoodsRefuseResult result = yzClient.invoke(youzanTradeReturngoodsRefuse, token, YouzanTradeReturngoodsRefuseResult.class);
4、商家同意退货场景
场景描述：当买家申请退货退款时，商家如何在微商城处理“同意退货”？
——微商城后台 - 订单 - 全部订单 - 退款中列表中，点击“买家发起维权”按钮进入退货退款单详情页：
——点击“同意退货，发送退货地址”，进入同意退货操作界面，选择退货地址发送给买家；
——通过哪个接口可以完成“商家同意退货”操作？
（1）商家同意退货：youzan.trade.returngoods.agree
（2）链接地址：https://open.youzanyun.com/api/youzan.trade.returngoods.agree/3.0.0
（3）重要字段说明：
》》address：收货地址，既买家收到的退货地址，买家将把需要退款的商品寄送到该地址；
》》mobile：收货手机号，既商家处理退货的人员手机号，买家退货时在快递单上填写的商家收货人手机号；
》》name：收货人姓名，既商家负责接收退货的人员姓名，买家退货时在快递单上填写的商家收货人姓名；
》》refund_id：退款 ID，买家申请的退款单的唯一 ID，可使用退款查询接口查询；
》》remark：退货说明，可以加一些备注，比如用户退货时需要注意些什么；
》》version：退款版本号，通过接口操作退款时的退款版本号，可使用退款查询接口查询；
（4）调用格式：
通过（2）中链接访问后： 
（5）HTTP 调用示例：
curl -X POST "https://open.youzanyun.com/api/youzan.trade.returngoods.agree/3.0.0?access_token=c3220121ae0fc6c4e11123370e0d1b03" -H 'content-type: application/json' -d '{ "refund_id":"2019092823456789","version":"201909099090","address":"杭州市西湖区黄龙万科中心G座11楼","mobile":"13567677898","name":"mark",}'
（6）JAVA 调用示例：
YouzanTradeReturngoodsAgree youzanTradeReturngoodsAgree = new YouzanTradeReturngoodsAgree();
//创建参数对象,并设置参数
YouzanTradeReturngoodsAgreeParams youzanTradeReturngoodsAgreeParams = new YouzanTradeReturngoodsAgreeParams();
youzanTradeReturngoodsAgreeParams.setAddress("杭州市西湖区黄龙万科G座11楼");
youzanTradeReturngoodsAgreeParams.setMobile("13567788787");
youzanTradeReturngoodsAgreeParams.setName("mark");
youzanTradeReturngoodsAgreeParams.setRefundId("20190909090909");
youzanTradeReturngoodsAgreeParams.setVersion(2989922L);
youzanTradeReturngoodsAgreeParams.setRemark("test");
youzanTradeReturngoodsAgree.setAPIParams(youzanTradeReturngoodsAgreeParams);
YouzanTradeReturngoodsAgreeResult result = yzClient.invoke(youzanTradeReturngoodsAgree, token, YouzanTradeReturngoodsAgreeResult.class);
——商家收到退还的商品之后，通过哪个接口更新库存？
（1）全量或增量方式更新 SKU 库存：youzan.item.quantity.update
（2）链接地址：https://open.youzanyun.com/api/youzan.item.quantity.update/3.0.0；
（3）重要字段说明：
》》item_id：商品 ID，需要更新库存信息的商品 ID，商品 ID 可以在对应的订单信息中获得；如果对接了有赞的消息推送服务，也可以在推送消息中获得订单号，再通过接口https://doc.youzanyun.com/doc#/content/API/1-305/detail/api/0/120获取商品 ID；
》》quantity：SKU 库存数量，此处数量应该填写为多少在后面的“type”字段中会有说明；
》》sku_id：规格 ID，更新商品某个具体规格的库存，如果是无规格商品可以不传，有规格的商品则必须传，否则会报错；
》》type：库存更新方式，0 为全量更新，1 为增量更新；举例说明：原库存是 5，如果设置为全量更新，quantity 设置为 6，则更新后总库存为 6；原库存是 5，如果设置为增量更新，quantity 设置为 6，则更新后总库存为 11；
（4）调用格式，通过（2）中链接访问后： 
（5）HTTP 调用示例：
curl -X POST "https://open.youzanyun.com/api/youzan.item.quantity.update/3.0.0?access_token=c3220121ae0fc6c4e11123370e0d1b03" -H 'content-type: application/json' -d '{ "quantity":"12","item_id":"4565443","sku_id":"322033","type":"0"}'
（6）JAVA 调用示例：
YouzanItemQuantityUpdate youzanItemQuantityUpdate = new YouzanItemQuantityUpdate();
//创建参数对象,并设置参数
YouzanItemQuantityUpdateParams youzanItemQuantityUpdateParams = new YouzanItemQuantityUpdateParams();
youzanItemQuantityUpdateParams.setItemId(432244L);
youzanItemQuantityUpdateParams.setQuantity(20L);
youzanItemQuantityUpdateParams.setSkuId(39443L);
youzanItemQuantityUpdateParams.setType(0);
youzanItemQuantityUpdate.setAPIParams(youzanItemQuantityUpdateParams);
YouzanItemQuantityUpdateResult result = yzClient.invoke(youzanItemQuantityUpdate, token, YouzanItemQuantityUpdateResult.class);
5、商家拒绝退款场景
场景描述：买家申请退款后，商家如何在微商城操作“拒绝退款”？
——微商城后台 - 订单 - 全部订单 - 退款中，可以查看买家申请退款的订单信息，点击“买家发起维权”按钮，即可查看退款详情；
——点击“拒绝退款申请”，填写拒绝理由发送给买家； 
——通过哪个接口可以完成“拒绝退款”操作？
（1）商家拒绝退款：youzan.trade.refund.refuse
（2）链接地址：https://doc.youzanyun.com/doc#/content/API/1-403/detail/api/0/165
（3）重要字段说明：
》》refund_id：退款 ID，退款单的唯一 ID，退款查询接口可查询到，如https://www.youzanyun.com/apilist/detail/group_trade/trade_advanced/youzan.trade.refund.search ；
》》remark：拒绝理由，直接展示给买家，建议认真填写；
》》version：退款版本号，退款流程的版本号，退款查询接口可查询到，如https://www.youzanyun.com/apilist/detail/group_trade/trade_advanced/youzan.trade.refund.search ；
（4）调用格式，通过（2）中链接访问后：
（5）HTTP 调用示例：
curl -X POST "https://open.youzanyun.com/api/youzan.trade.refund.refuse/3.0.0?access_token=c3220121ae0fc6c4e11123370e0d1b03" -H 'content-type: application/json' -d '{ "refund_id":"2019092823456789","version":"201909099090","remark":"test"}'
（6）JAVA 调用示例：
YouzanTradeRefundRefuse youzanTradeRefundRefuse = new YouzanTradeRefundRefuse();
//创建参数对象,并设置参数
YouzanTradeRefundRefuseParams youzanTradeRefundRefuseParams = new YouzanTradeRefundRefuseParams();
youzanTradeRefundRefuseParams.setRefundId("201909093398848443");
youzanTradeRefundRefuseParams.setRemark("test");
youzanTradeRefundRefuseParams.setVersion(20094L);
youzanTradeRefundRefuse.setAPIParams(youzanTradeRefundRefuseParams);
YouzanTradeRefundRefuseResult result = yzClient.invoke(youzanTradeRefundRefuse, token, YouzanTradeRefundRefuseResult.class);
6、商家同意退款场景
场景描述：买家申请退款后，商家如何在微商城处理“同意退款”？
——微商城后台 - 订单 - 所有订单 - 退款中，点击“买家发起维权”后，即可查看退款详情； 
——点击“同意买家退款”将退款给买家，退款将在 3-15 个工作日期间退还给买家支付账户； 
——通过哪个接口可以完成“商家同意退款”操作？
（1）商家同意退款：youzan.trade.refund.agree
（2）链接地址：https://doc.youzanyun.com/doc#/content/API/1-403/detail/api/0/143；
（3）重要字段说明：
》》refund_id：退款 ID，退款单的唯一 ID，退款查询接口可查询到；
》》version：退款版本号，退款流程的版本号，退款查询接口可查询；
（4）调用格式，通过（2）中链接访问后： 
（5）HTTP 调用示例：
curl -X POST "https://open.youzanyun.com/api/youzan.trade.refund.agree/3.0.0?access_token=c3220121ae0fc6c4e11123370e0d1b03" -H 'content-type: application/json' -d '{ "refund_id":"2019092823456789","version":"201909099090"}'
（6）JAVA 调用示例：
YouzanTradeRefundAgree youzanTradeRefundAgree = new YouzanTradeRefundAgree();
//创建参数对象,并设置参数
YouzanTradeRefundAgreeParams youzanTradeRefundAgreeParams = new YouzanTradeRefundAgreeParams();
youzanTradeRefundAgreeParams.setRefundId("2019099228494943");
youzanTradeRefundAgreeParams.setVersion(9898L);
youzanTradeRefundAgree.setAPIParams(youzanTradeRefundAgreeParams);
YouzanTradeRefundAgreeResult result = yzClient.invoke(youzanTradeRefundAgree, token, YouzanTradeRefundAgreeResult.class);
7、商家主动退款场景
场景描述：买家申请退款后或者买家并未申请维权，商家由于商品缺货或其他问题需要主动给买家退款，该如何操作？
——微商城后台 - 订单 - 所有订单 - 点击查看详情；
——在订单详情页面，点击主动退款，退款给买家；
——点击后，输入退款金额即可完成主动退款，退款将在 3-15 个工作日返回买家支付账户；
——通过哪个接口可以完成商家“主动退款”操作？
（1）商家主动退款：youzan.trade.refund.seller.active
（2）链接地址：https://doc.youzanyun.com/doc#/content/API/1-403/detail/api/0/148
（3）重要字段说明：
》》desc：退款原因，需要给买家说明退款原因，比如缺货，无法发货等；
》》oid：订单明细 id，大订单号中的明细 id，可以通过订单详情接口获取，链接地址：https://doc.youzanyun.com/doc#/content/API/1-305/detail/api/0/120；订单明细 ID 的产生规则说明：如果一个订单中含有四件商品，有两件商品是一样的，也就是该订单含有三种商品，则一个大订单号 Tid 中会包含 3 个 oid，即每种不同的商品会形成一个 oid，相同的商品无法拆分；
》》refund_fee：退款金额，单位“元”；
》》tid：订单号，需要退款的订单号；
（4）调用格式，通过（2）中链接访问后： 
（5）HTTP 调用示例：
curl -X POST "https://open.youzanyun.com/api/youzan.trade.refund.seller.active/3.0.0?access_token=c3220121ae0fc6c4e11123370e0d1b03" -H 'content-type: application/json' -d '{ "refund_fee":"20","oid":"20190909909033332","tid":"E20190921153115076000025","desc":"test"}'
（6）JAVA 调用示例：
YouzanTradeRefundSellerActive youzanTradeRefundSellerActive = new YouzanTradeRefundSellerActive();
//创建参数对象,并设置参数
YouzanTradeRefundSellerActiveParams youzanTradeRefundSellerActiveParams = new YouzanTradeRefundSellerActiveParams();
youzanTradeRefundSellerActiveParams.setOid(201949444424L);
youzanTradeRefundSellerActiveParams.setRefundFee("20");
youzanTradeRefundSellerActiveParams.setTid("E20190921153115076000025");
youzanTradeRefundSellerActiveParams.setDesc("test");
youzanTradeRefundSellerActive.setAPIParams(youzanTradeRefundSellerActiveParams);
YouzanTradeRefundSellerActiveResult result = yzClient.invoke(youzanTradeRefundSellerActive, token, YouzanTradeRefundSellerActiveResult.class);
三、使用 API 接口调试工具排查问题 - 商家主动退款场景
调用有赞 API 接口出现问题时，可以使用 Postman 接口调试工具对调用参数进行测试，以此确定是否是调用参数的问题。
示例：商家主动退款 （参考入参和调用方式）