# 退货组件简介

退货组件是微信官方推出的小程序插件,为商家提供低成本的退货解决方案。 具有成本低、触达效率高、服务稳定的特点。 接入退货组件后,支持用户在小程序的退货流程中「预约快递员上⻔取件」「回填退货快递单号」,提高用户购物体验;商家可以通过 API 接口,查询用户的退货快递运单号状态,提高商家的运营效率。

# 退货组件 API 接口

# 1. 创建退货 ID
  • 描述:商家在同意用户退货之后,通过本接口创建退货ID,shop_order_id和退货 ID 一一对应。平台根据退货 ID 下发模板消息给用户,提醒用户退货。“一个订单需要多次退货”的场景,可以在商家内部 1 个退货订单号映射多个shop_order_id。
  • 请求地址:https://api.weixin.qq.com/cgi-bin/express/delivery/return/add?access_token=ACCESS_TOKEN
  • 请求方式:POST
  • 请求参数
{
    "shop_order_id": "xxx",//商家内部系统使用的退货编号
    "biz_addr": {  //商家退货地址,必填
        "name": "张三",
        "mobile": "13600000000",//仅支持输入一个联系方式
        "country": "中国",
        "province": "广东省",
        "city": "广州市",
        "area": "海珠区",
        "address": "xx路 xx 号"
    },
    "user_addr": { //用户购物时的收货地址,选填
        "name": "李四",
        "mobile": "13600000000",
        "country": "中国",
        "province": "广东省",
        "city": "广州市",
        "area": "海珠区",
        "address": "xx路 xx 号"
     },
     "openid":"xxx",//退货用户的openid,用于给用户下发模版消息,通过模版消息用户可以选择退货方式
	 "order_path":"xxx",//退货订单在商家小程序的path
	 "goods_list":[
		{
			"name":"xxx",//退货商品的名称
			"url":"xxx"//退货商品图片的url
		}
	 ],
	 "order_price":1//退货订单的价格
}

  • 返回参数
{
	"errcode": 0,
	"errmsg": "OK",
	"return_id": "1935761508265738242"
}

  • 错误码列表
"errcode": 40097  //参数错误:order_id为空或者退货地址为空
"errcode": 9300522   //参数错误:shop_order_id 已存在
"errcode": -1  //系统错误:请联系微信平台解决

# 2. 查询退货 ID 状态
  • 描述:本接口用于商家查询用户退货状态(是否填写退货信息)及追踪用户退货物流,方便仓库收货。通过本接口查询退货 ID 状态,其中 status 是退货 ID 状态,order_status是退货 ID 对应的用户运单号的状态。
  • 请求地址:https://api.weixin.qq.com/cgi-bin/express/delivery/return/get?access_token=ACCESS_TOKEN
  • 请求方式:POST
  • 请求参数
{
  "return_id": "1935761508265738242"
}
  • 返回参数
{
    "errcode": 0,
    "errmsg": "OK",
    "status": "2", //0 用户未填写退货信息, 1. 在线预约, 2. 自主填写
    "waybill_id": "JDxxxxxx", //运单号
    "order_status": 0, //0›   已下单待揽件 1› 已揽件 2›   运输中 3›   派件中 4›   已签收 5›   异常 6› 代签收 7›   揽收失败 8› 签收失败(拒收,超区) 11›  已取消 13›  退件中 14›  已退件 99 未知
    "delivery_name": "申通快递",//运力公司名称
    "delivery_id": SF,//运力   公司编码
}
  • 错误码列表
"errcode": 40097  //参数错误:return_id为空
"errcode": 931023   //参数错误:运单不存在
"errcode": -1  //系统错误:请联系微信平台解决
# 3. 解绑退货 ID
  • 描述:当商家同意退货申请之后,与用户达成协商「无需退货」时,可以通过本接口可以接触商家退货单与退货 ID的绑定。考虑到预约快递员上门取件的情况在用户侧发生,因此只有当用户是自主填写运单号情况下才支持解绑退货 ID 。
  • 请求地址:https://api.weixin.qq.com/cgi-bin/express/delivery/return/unbind?access_token=ACCESS_TOKEN
  • 请求方式:POST
  • 请求参数
{
  "return_id": "1935761508265738242"
}

  • 返回参数
{
	"errcode": 0,
	"errmsg": "OK",
}
  • 错误码列表
"errcode": 40097  //参数错误:return_id为空或者退货单类型不匹配
"errcode": 931023   //参数错误:运单不存在
"errcode": -1  //系统错误:请联系微信平台解决

# 组件调用

自定义插槽 Target 作为触发弹窗且校验的节点弹出 halfDialogScreen 供选择 ”上门取件“ or "自行寄回" 两种退货方式

# 1. 代码示例
# 基本用法

test.wxml:

// 需要使用两个插槽节点(slot="refund" 和 slot="refund_detail" 分别对应退货前跟退货后状态的插槽节点,如果没有要求退货状态,可以使用同意的元素节点)

// 对状态有要求,不同状态展示不同文案节点
<view>
  <sales-return returnId="{{returnId}}">
    <button slot="refund">立即退货</button>   //还未退过货的插槽节点
    <button slot="refund_detail">退货详情</button>  //还退完货后的插槽节点
  </sales-return>
</view>



// 对状态无要求,不同状态展示相同同文案节点
<view>
  <sales-return returnId="{{returnId}}">
    <button slot="refund">立即退货</button>   //还未退过货的插槽节点
    <button slot="refund_detail">立即退货</button>  //退完货后的插槽节点
  </sales-return>
</view>

test.js:

data: {
  returnId: "xxx";
}

test.json:

{
  "usingComponents": {
    "sales-return": "plugin://logisticsPlugin/sales-return"
  }
}

app.json 引入插件:

{
  "pages": [
    "pages/index/index",
   ],
  "window": {
    },
  "plugins": {
    "logisticsPlugin": {
      "version": "2.1.11",
      "provider": "wx9ad912bf20548d92"
    }
  },
 }

# 2. 效果图

其中goods_info的内容如下:

参数名称 类型 必选 备注
returnld string 退货 ID
# 3. 插槽 Slots
插槽名 类型 必选 备注
refund string 还未退货的插槽节点,用来触发弹窗、跳转页面的节点(必填)
refund_detail string 退完货的插槽节点,用来触发弹窗、跳转页面的节点(必填,如果退货行为完成前后是相同文案可使用 refund 所使用的的文案)