# 无忧退货（运费险）简介

小程序无忧退货（运费险）是微信官方推出的售后退换货保障服务。商家向微信充值保费后，可以为用户订单购买运费险，若订单发生退换货，无忧退货支持用户预约上门取件，寄退货免付基础运费，最高抵扣¥19.35（基本全国免费寄退货）。商家使用无忧退货无需支付额外费用。

# 接入案例

# 1. 运作流程

1. 预充值：商家通过微信向保司充值保费，账期60天，到期未用余额自动原路退回。
2. 投保：商家需要对订单投保时，通过投保接口向微信主动发起投保。
3. 理赔：
   • 上门取件：京东上门取件，用户寄件时直接抵扣基础运费，最高抵扣¥19.35。
   • 自行寄回：支持全部物流公司，用户自行线下寄回后填写退货物流单号，理赔款¥10打款到用户微信零钱包。
4. 退款：商家主动向微信/系统自动发起退款，资金原路返回。

注：微信支付单号、保单号、理赔单号一一对应，一笔交易订单仅能投保和理赔一次。

# 2. 用户体验 (消息无需订阅，页面无需开发)

# 3. 开通路径 (无需支付额外费用)

# 开通位置

小程序后台-功能-物流服务-无忧退货(运费险)

# 签署服务协议

# 后台接口对接

# 保费预充值(支持扫码/网银转账)

# 查看投保和资金记录

# 4. 开票流程

目前支持开具电子普票、纸质普票和纸质增值税专用发票，商家可以在指定日期，按照要求邮件申请（附件大小不超过15M），开具的纸质发票将通过快递的方式寄送给商家，发票邮寄费用由商家自行承担。电子发票由所填邮箱接收。

邮件标题：运费险发票申请-xx小程序x月

邮件正文及附件内容：

1. 小程序主体名、小程序appid、开票金额（元）、纳税人名称（与小程序主体一致）、纳税人识别号、地址、电话、开户行及账号、电子邮箱、联系人及电话

2. 营业执照扫描件/复印件，加盖公章

3. 需要开票的保单信息（可在小程序后台-物流服务-无忧退货-保单信息中筛选下载excel）

发送时间：请在每月初1-5日，发送邮件申请。

开票邮箱： xuziyi900@pingan.com.cn

# 5. 开发文档

# 接入流程泳道图

# 请求域名

https://api.weixin.qq.com{PathName}?access_token=${access_token}

# 调用方式

文档所有接口请求方式均为HTTPS-POST请求，UTF-8编码，请求和相应参数仅支持JSON数据格式，所有接口的调用均需要获取access_token授权，服务商获取access_token，走微信开放平台-第三方平台的模式。
调用主体为小程序appid 或 第三方平台appid均可，二选一即可。

# 基本返回参数

# 常见返回码

# 6. API接口列表

# 开通无忧退货接口

PathName: /wxa/business/insurance_freight/open
请求参数：
无
返回参数：
无

# 查询开通状态接口

PathName: /wxa/business/insurance_freight/query_open
请求参数：
无
返回参数：

# 投保接口(发货时投保)

PathName: /wxa/business/insurance_freight/createorder
请求参数：

返回参数：

请求参数示例

{
  "openid":"oZGTP5DwGDPfEf1EBBHH_oxHw2aU",
  "order_no": "4200001197202103228672982585",
  "pay_amount": 1,
  "pay_time": 1679473667,
  "delivery_place":{
      "province":"广东省",
      "city": "广州市",
      "county": "海珠区",
      "address": "创业园23号"
  },
  "receipt_place":{
      "province":"广东省",
      "city": "惠州市",
      "county": "惠普区",
      "address": "龙山村10-2"
  },
  "delivery_no": "d20230322001"
}

返回参数示例

{
    "errcode": 0,
    "errmsg": "ok",
    "policy_no": "10288003264673876282",
    "insurance_end_date": "2023-06-20 16:36:54",
    "estimate_amount": 1200
}

# 理赔接口 (收到用户退货后再触发)

PathName: /wxa/business/insurance_freight/claim
请求参数：

返回参数：

请求参数示例

{
    "openid": "oZGTP5DwGDPfEf1EBBHH_oxHw2aU",
    "order_no": "4200001197202103228672982585",
    "refund_delivery_no" : "rd20230322001",
    "refund_company": "SF"
}

返回参数示例

{
    "errcode": 0,
    "errmsg": "ok",
    "report_no": "90581008120350195232",
    "is_home_pick_up": 1
}

# 理赔结果推送

# 接入方式

如果需要监听理赔结果的事件，接入方式可以参考公众平台的消息推送:

如果开发者是小程序商家，请移步 消息推送

如果开发者是服务商第三方平台，请移步 消息与事件接收配置

# 理赔结果推送事件

事件类型: wxainsurance_claim_result

参数

参数示例

<xml>
    <ToUserName>gh_abcdefg</ToUserName>
    <FromUserName>oABCD</FromUserName>
    <CreateTime>1234455555</CreateTime>
    <MsgType>event</MsgType>
    <Event>wxainsurance_claim_result</Event>
    <upload_event>
        <OrderNo><![CDATA[42000021662024041000000000000]]></OrderNo>
        <Status>5</Status>
        <FinishTime>1234455555</FinishTime>
    </upload_event>
</xml>

# 申请充值订单号接口 (支持自定义金额)

PathName: /wxa/business/insurance_freight/createchargeid
请求参数：

返回参数：

请求参数示例

{
    "quota" : 1000
}

返回参数示例

{
    "errcode": 0,
    "errmsg": "ok",
    "order_id": 2850151276313431996
}

# 申请支付接口

PathName: /wxa/business/insurance_freight/applypay
请求参数：

返回参数：

特别提示： 充值后退款只能退回原充值账号

请求参数示例

{
    "order_id" : 2850151276313431996
}

返回参数示例

{
    "errcode": 0,
    "errmsg": "ok",
    "pay_url": "https://fuwu.weixin.qq.com/service/common/buy?hasApply=1&orderId=2850151276313431996"
}

# 拉取充值订单信息接口

PathName: /wxa/business/insurance_freight/getpayorderlist
请求参数：

返回参数：

请求参数示例

{
    "status_list": [
        2, 3, 4, 5, 6
    ],
    "offset": 0,
    "limit": 20
}

返回参数示例

{
    "errcode": 0,
    "errmsg": "ok",
    "list": [
        {
            "order_id": 2850151276313431996,
            "order_status": 5,
            "total_price": 1000,
            "create_time": 1678966793,
            "pay_time": 1678966880,
            "can_refund": true,
            "refund_time": 0,
            "refund_status": 1
        }
    ],
    "total": 1
}

# 退款接口

PathName: /wxa/business/insurance_freight/refund
请求参数：
无 返回参数：
无
特别提示： 充值后退款只能退回原充值账号

# 拉取摘要接口 (查询当前保费、投保单量、理赔单量、账号余额等信息)

PathName: /wxa/business/insurance_freight/getsummary
请求参数：

返回参数：

# 拉取保单信息接口

PathName: /wxa/business/insurance_freight/getorderlist
请求参数：

返回参数：

请求参数示例

{
    "status_list": [
        2, 4, 5
    ],
    "offset": 0,
    "limit": 20
}

返回参数示例

{
    "errcode": 0,
    "errmsg": "ok",
    "list": [
        {
            "order_no": "4200001197202103228672982584",
            "policy_no": "10288003264673876281",
            "report_no": "",
            "status": 2,
            "insurance_end_date": "2023-06-14 19:41:34",
            "premium": 20,
            "estimate_amount": 1200,
            "delivery_no": "delivery20230321001",
            "refund_delivery_no": "delivery20230322001",
            "is_home_pick_up": 1
        },
        {
            "order_no": "4200001197202103228672982585",
            "policy_no": "10288003264673876282",
            "report_no": "90581008120350195232",
            "status": 4,
            "insurance_end_date": "2023-06-20 16:36:54",
            "premium": 20,
            "estimate_amount": 1200,
            "delivery_no": "delivery20230322001",
            "refund_delivery_no": "delivery20230322001",
            "is_home_pick_up": 1
        }
    ],
    "total": 2
}

# 设置告警余额接口

开发者可通过接口自定义余额为xx时通知小程序管理员（余额xx无改动情况下24h内通知一次）。通知消息将通过 微信公众平台 下发。

PathName: /wxa/business/insurance_freight/update_notify_funds
请求参数：

返回参数：
无

# 创建退货 ID

• 描述：商家在同意用户退货之后，通过本接口创建退货ID，shop_order_id和退货 ID 一一对应。一个订单需要多次退货”的场景，可以在商家内部 1 个退货订单号映射多个shop_order_id。注：该接口中文相关的字段用UTF-8。
• 提醒退货通知：商家创建退货 ID 时，平台会自动下发模板消息给用户，提醒用户退货。
• 请求地址：https://api.weixin.qq.com/cgi-bin/express/delivery/no_worry_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//退货订单的价格,
    "wx_pay_id":"420000198020231123341140012"//微信支付投保单号
}

• 返回参数

{
	"errcode": 0,
	"errmsg": "OK",
	"return_id": "1935761508265738242"
}

• 错误码列表

"errcode": 40097        //参数错误:order_id为空或者退货地址为空或者wx_pay_id为空
"errcode": 9300522   //参数错误:shop_order_id 已存在
"errcode": 9300569   //参数错误:wx_pay_id 为空
"errcode": 9300570   //逻辑错误:该微信支付单号填写错误或未投保
"errcode": -1  //系统错误:请联系微信平台解决

# 查询退货 ID 状态

• 描述：本接口用于商家查询用户退货状态（是否填写退货信息）及追踪用户退货物流，方便仓库收货。通过本接口查询退货 ID 状态，其中status是退货ID状态，order_status是退货 ID 对应的用户运单号的状态。
• 请求地址：https://api.weixin.qq.com/cgi-bin/express/delivery/no_worry_return/get?access_token=ACCESS_TOKEN
• 请求方式：POST
• 请求参数

{
  "return_id": "1935761508265738242"
}

• 返回参数

{
    "errcode": 0,
    "errmsg": "OK",
    "status": "1", // 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  //系统错误:请联系微信平台解决

# 解绑退货 ID

• 描述：当商家同意退货申请之后，与用户达成协商「无需退货」时，可以通过本接口可以解除商家退货单与退货 ID的绑定。考虑到预约快递员上门取件的情况在用户侧发生，因此只有当用户是自主填写运单号情况下才支持解绑退货 ID 。
• 请求地址：https://api.weixin.qq.com/cgi-bin/express/delivery/no_worry_return/unbind?access_token=ACCESS_TOKEN
• 请求方式：POST
• 请求参数

{
    "return_id": "1935761508265738242"
}

• 返回参数

{
	"errcode": 0,
	"errmsg": "OK",
}

• 错误码列表

"errcode": 40097    //参数错误:return_id为空
"errcode": 931023   //参数错误:运单不存在
"errcode": -1       //系统错误:请联系微信平台解决

# 7. 组件调用

商家可选择调用组件（the latest version）至小程序页面，实现用户在小程序页面内点击按钮拉起退货寄件。

①订单有运费险：拉起无忧退货页面，上门取件抵扣基础运费。

②订单无运费险：拉起半屏弹窗，上门取件自付运费。

# 代码示例

# 基本用法

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.3.0",
      "provider": "wx9ad912bf20548d92"
    }
  },
 }

# goods_info内容

# 插槽 Slots

# 8. 咨询建议

# 如有疑问或建议，可前往微信开放社区-微信物流服务 发帖提问讨论，官方工作人员会及时回复。