# logistics.previewTemplate

本接口应在服务器端调用,详细说明参见服务端API

本接口支持云调用。需开发者工具版本 >= 1.02.1904090(最新稳定版下载),wx-server-sdk >= 0.4.0

预览面单模板。用于调试面单模板使用。

调用方式:

# HTTPS 调用

# 请求地址

POST https://api.weixin.qq.com/cgi-bin/express/delivery/template/preview?access_token=ACCESS_TOKEN

# 请求参数

属性 类型 默认值 必填 说明
access_token / cloudbase_access_token string 接口调用凭证
waybill_id string 运单 ID
waybill_template string 面单 HTML 模板内容(需经 Base64 编码)
waybill_data string 面单数据。详情参考下单事件返回值中的 WaybillData
custom Object 商户下单数据,格式是商户侧下单 API 中的请求体

# 返回值

# Object

属性 类型 说明
waybill_id string 运单 ID
rendered_waybill_template string 渲染后的面单 HTML 文件(已经过 Base64 编码)
errcode number 错误码
errmsg string 错误信息

errcode 的合法值

说明 最低版本
0 成功
-1 其他错误
40199 运单 ID 错误,未查到运单
9300507 Token 不正确
9300502 预览模板中出现该错误,一般是waybill_data数据错误
9300512 模板格式错误,渲染失败

# 请求数据示例

{
  "waybill_id": "1234567890123",
  "waybill_data": "##ZTO_mark##11-22-33##ZTO_bagAddr##广州##",
  "waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4=",
  "custom": {
    "order_id": "012345678901234567890123456789",
    "openid": "oABC123456",
    "delivery_id": "ZTO",
    "biz_id": "xyz",
    "custom_remark": "易碎物品",
    "sender": {
      "name": "张三",
      "tel": "18666666666",
      "mobile": "020-88888888",
      "company": "公司名",
      "post_code": "123456",
      "country": "中国",
      "province": "广东省",
      "city": "广州市",
      "area": "海珠区",
      "address": "XX路XX号XX大厦XX栋XX"
    },
    "receiver": {
      "name": "王小蒙",
      "tel": "18610000000",
      "mobile": "020-77777777",
      "company": "公司名",
      "post_code": "654321",
      "country": "中国",
      "province": "广东省",
      "city": "广州市",
      "area": "天河区",
      "address": "XX路XX号XX大厦XX栋XX"
    },
    "shop": {
      "wxa_path": "/index/index?from=waybill",
      "img_url": "https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640",
      "goods_name": "一千零一夜钻石包&爱马仕柏金钻石包",
      "goods_count": 2
    },
    "cargo": {
      "count": 2,
      "weight": 5.5,
      "space_x": 30.5,
      "space_y": 20,
      "space_z": 20,
      "detail_list": [
        {
          "name": "一千零一夜钻石包",
          "count": 1
        },
        {
          "name": "爱马仕柏金钻石包",
          "count": 1
        }
      ]
    },
    "insured": {
      "use_insured": 1,
      "insured_value": 10000
    },
    "service": {
      "service_type": 0,
      "service_name": "标准快递"
    }
  }
}

# 返回数据示例

{
  "waybill_id": "1234567890123",
  "rendered_waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4="
}

# 模板渲染语法

  1. 所有渲染语法由##开始,可参考示例
  2. ##VAR(key) 用参数key对应的值填充。支持的参数如下表格所示
key value
sys.waybillid 运单 ID
sys.wxaappid 商户小程序 APPID
waybilldata.* 下单事件返回中的WaybillData,快递侧自定义的数据
custom.* 商户侧下单 API 中传入的字段
custom.order_id 唯一标识订单的 ID,由商户传入
custom.custom_remark 快递备注,会打印到面单的自定义区,比如"易碎物品"
custom.sender.name 发件人名字
custom.sender.tel 发件人座机号码
custom.sender.mobile 发件人手机号码
custom.sender.company 发件人公司名
custom.sender.post_code 发件人邮编
custom.sender.country 发件人所在国家
custom.sender.province 发件人省份
custom.sender.city 发件人地区/市
custom.sender.area 发件人区/县
custom.sender.address 发件人详细地址
custom.receiver.name 收件人名字
custom.receiver.tel 收件人座机号码
custom.receiver.mobile 收件人手机号码
custom.receiver.company 收件人公司名
custom.receiver.post_code 收件人邮编
custom.receiver.country 收件人所在国家
custom.receiver.province 收件人省份
custom.receiver.city 收件人地区/市
custom.receiver.area 收件人区/县
custom.receiver.address 收件人详细地址
custom.cargo.count 包裹数量
custom.cargo.weight 包裹总重量,单位是千克(kg)
custom.cargo.space_x 包裹长度,单位是厘米(cm)
custom.cargo.space_y 包裹宽度,单位是厘米(cm)
custom.cargo.space_z 包裹高度,单位是厘米(cm)
custom.shop.goods_name 商品名称
custom.shop.goods_count 商品数量
custom.insured.use_insured 是否使用保价
custom.insured.insured_value 报价金额,单位是分
custom.service.service_type 服务类型 ID
custom.service.service_name 服务名称
  1. ##TIME(DATE) 用日期填充当前位置,格式为%Y/%m/%d,比如2018/11/22
  2. ##TIME(TIME) 用时间填充当前位置,格式为%H:%M:%S,比如17:54:06
  3. ##TIME(FULL) 用日期时间填充当前位置,格式为%Y/%m/%d %H:%M:%S,比如2018/11/22 17:54:06
  4. ##STRBLOAT(VAR(sys.waybillid)) 获取运单 ID,然后在每个字符间填充空格。
  5. ##CODE128(VAR(sys.waybillid)) 获取运单 ID,然后转换成CODE128条码,图片为base64编码。
  6. ##QRCODE(VAR(sys.waybillid)) 获取运单 ID,然后转换为二维码,图片为base64编码。
  7. ##WXASUNCODE(VAR(sys.wxaappid)) 获取商户的小程序码,图片为base64编码。

举例,如果想在面单上打印一个集包地信息的条形码,可以在面单中增加:

<img src="data:image/jpeg;base64, ##CODE128(VAR(waybilldata.ZTO_bagAddr))" class="block_5__barCode">

# 云调用

云调用是微信云开发提供的在云函数中调用微信开放接口的能力,需要在云函数中通过 wx-server-sdk 使用。

# 接口方法

openapi.logistics.previewTemplate

需在 config.json 中配置 logistics.previewTemplate API 的权限,详情

# 请求参数

属性 类型 默认值 必填 说明
waybillId string 运单 ID
waybillTemplate string 面单 HTML 模板内容(需经 Base64 编码)
waybillData string 面单数据。详情参考下单事件返回值中的 WaybillData
custom Object 商户下单数据,格式是商户侧下单 API 中的请求体

# 返回值

# Object

属性 类型 说明
waybillId string 运单 ID
renderedWaybillTemplate string 渲染后的面单 HTML 文件(已经过 Base64 编码)
errCode number 错误码
errMsg string 错误信息

errCode 的合法值

说明 最低版本
0 成功

# 异常

# Object

抛出的异常

属性 类型 说明
errCode number 错误码
errMsg string 错误信息

errCode 的合法值

说明 最低版本
-1 其他错误
40199 运单 ID 错误,未查到运单
9300507 Token 不正确
9300502 预览模板中出现该错误,一般是waybill_data数据错误
9300512 模板格式错误,渲染失败

# 请求数据示例

const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.logistics.previewTemplate({
        "custom": {
          "openid": 'oABC123456',
          "sender": {
            "name": '张三',
            "tel": '18666666666',
            "mobile": '020-88888888',
            "company": '公司名',
            "country": '中国',
            "province": '广东省',
            "city": '广州市',
            "area": '海珠区',
            "address": 'XX路XX号XX大厦XX栋XX',
            "postCode": '123456'
          },
          "receiver": {
            "name": '王小蒙',
            "tel": '18610000000',
            "mobile": '020-77777777',
            "company": '公司名',
            "country": '中国',
            "province": '广东省',
            "city": '广州市',
            "area": '天河区',
            "address": 'XX路XX号XX大厦XX栋XX',
            "postCode": '654321'
          },
          "shop": {
            "wxaPath": '/index/index?from=waybill',
            "imgUrl": 'https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640',
            "goodsName": '一千零一夜钻石包&爱马仕柏金钻石包',
            "goodsCount": 2
          },
          "cargo": {
            "count": 2,
            "weight": 5.5,
            "spaceX": 30.5,
            "spaceY": 20,
            "spaceZ": 20,
            "detailList": [
              {
                "name": '一千零一夜钻石包',
                "count": 1
              },
              {
                "name": '爱马仕柏金钻石包',
                "count": 1
              }
            ]
          },
          "insured": {
            "useInsured": 1,
            "insuredValue": 10000
          },
          "service": {
            "serviceType": 0,
            "serviceName": '标准快递'
          },
          "orderId": '012345678901234567890123456789',
          "deliveryId": 'ZTO',
          "bizId": 'xyz',
          "customRemark": '易碎物品'
        },
        "waybillId": '1234567890123',
        "waybillData": '##ZTO_mark##11-22-33##ZTO_bagAddr##广州##',
        "waybillTemplate": 'PGh0bWw+dGVzdDwvaHRtbD4='
      })
    return result
  } catch (err) {
    return err
  }
}

# 返回数据示例

{
  "waybillId": "1234567890123",
  "renderedWaybillTemplate": "PGh0bWw+dGVzdDwvaHRtbD4=",
  "errMsg": "openapi.logistics.previewTemplate:ok"
}