# 预览面单模板

调试工具

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

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

# 接口说明

# 接口英文名

previewTemplate

# 功能描述

该接口用于预览面单模板。以及用于调试面单模板使用。

# 调用方式

# HTTPS 调用


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

# 云调用

出入参和HTTPS调用相同，调用方式可查看云调用说明文档
接口方法为: openapi.logistics.previewTemplate

# 请求参数

属性

类型

必填

说明

access_token

string

是

接口调用凭证，该参数为 URL 参数，非 Body 参数。使用getAccessToken

waybill_id

string

是

运单 ID

waybill_template

string

是

面单 HTML 模板内容（需经 Base64 编码）

waybill_data

string

是

面单数据。详情参考下单事件返回值中的 WaybillData

custom

object

是

商户下单数据，格式是商户侧下单addOrder 接口中的请求体

属性

类型

必填

说明

order_id

string

是

订单ID，须保证全局唯一，不超过512字节

openid

string

是

用户openid，当add_source=2时无需填写（不发送物流服务通知）

delivery_id

string

是

快递公司ID，参见getAllDelivery

biz_id

string

是

快递客户编码或者现付编码

custom_remark

string

否

快递备注信息，比如"易碎物品"，不超过1024字节

tagid

number

否

订单标签id，用于平台型小程序区分平台上的入驻方，tagid须与入驻方账号一一对应，非平台型小程序无需填写该字段

add_source

number

是

订单来源，0为小程序订单，2为App或H5订单，填2则不发送物流服务通知

wx_appid

string

否

App或H5的appid，add_source=2时必填，需和开通了物流助手的小程序绑定同一open账号

sender

object

是

发件人信息

属性	类型	必填	说明
name	string	否	发件人姓名，不超过64字节
tel	string	否	发件人座机号码，若不填写则必须填写 mobile，不超过32字节
mobile	string	否	发件人手机号码，若不填写则必须填写 tel，不超过32字节
company	string	否	发件人公司名称，不超过64字节
post_code	string	否	发件人邮编，不超过10字节
country	string	否	发件人国家，不超过64字节
province	string	否	发件人省份，比如："广东省"，不超过64字节
city	string	否	发件人市/地区，比如："广州市"，不超过64字节
area	string	否	发件人区/县，比如："海珠区"，不超过64字节
address	string	否	发件人详细地址，比如："XX路XX号XX大厦XX"，不超过512字节

receiver

object

是

收件人信息

属性	类型	必填	说明
name	string	否	发件人姓名，不超过64字节
tel	string	否	发件人座机号码，若不填写则必须填写 mobile，不超过32字节
mobile	string	否	发件人手机号码，若不填写则必须填写 tel，不超过32字节
company	string	否	发件人公司名称，不超过64字节
post_code	string	否	发件人邮编，不超过10字节
country	string	否	发件人国家，不超过64字节
province	string	否	发件人省份，比如："广东省"，不超过64字节
city	string	否	发件人市/地区，比如："广州市"，不超过64字节
area	string	否	发件人区/县，比如："海珠区"，不超过64字节
address	string	否	发件人详细地址，比如："XX路XX号XX大厦XX"，不超过512字节

cargo

object

是

包裹信息，将传递给快递公司

属性

类型

必填

说明

count

number

是

包裹数量, 默认为1

weight

number

是

包裹总重量，单位是千克(kg)

space_x

number

是

包裹总重量，单位是千克(kg)

space_y

number

是

包裹总重量，单位是千克(kg)

space_z

number

是

包裹总重量，单位是千克(kg)

detail_list

array<object>

是

包裹总重量，单位是千克(kg)

	属性	类型	必填	说明
	name	string	是	商品名，不超过128字节
	count	number	是	商品数量

shop

object

是

商品信息，会展示到物流服务通知和电子面单中

属性

类型

必填

说明

wxa_path

string

否

商家小程序的路径，建议为订单页面

img_url

string

否

商品缩略图 url；shop.detail_list为空则必传，shop.detail_list非空可不传。

goods_name

string

否

商品名称, 不超过128字节；shop.detail_list为空则必传，shop.detail_list非空可不传。

goods_count

number

否

商品数量；shop.detail_list为空则必传。shop.detail_list非空可不传，默认取shop.detail_list的size

wxa_appid

string

否

该参数在【即使配送】的addOrder接口才生效。若结算方式为：第三方向配送公司统一结算，商户后续和第三方结算，则该参数必填；在该结算模式下，第三方用自己的开发小程序替授权商户发起下单，并将授权小程序的appid给平台，后续配送通知中可回流授权商户小程序。

detail_list

array<object>

否

	属性	类型	必填	说明
	goods_name	string	是	商品名称
	goods_img_url	string	是	商品图片url

insured

object

是

保价信息

	属性	类型	必填	说明
	use_insured	number	否	是否保价，0 表示不保价，1 表示保价
	insured_value	number	否	保价金额，单位是分，比如: 10000 表示 100 元

service

object

是

服务类型

	属性	类型	必填	说明
	service_type	number	是	服务类型ID，详见已经支持的快递公司基本信息
	service_name	string	是	服务名称，详见已经支持的快递公司基本信息

expect_time

number

否

Unix 时间戳, 单位秒，顺丰必须传。预期的上门揽件时间，0表示已事先约定取件时间；否则请传预期揽件时间戳，需大于当前时间，收件员会在预期时间附近上门。例如expect_time为“1557989929”，表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明：若选择了预期揽件时间，请不要自己打单，由上门揽件的时候打印。如果是下顺丰散单，则必传此字段，否则不会有收件员上门揽件。

take_mode

number

否

分单策略，【0：线下网点签约，1：总部签约结算】，不传默认线下网点签约。目前支持圆通。

# 返回参数

属性	类型	说明
waybill_id	string	运单 ID
rendered_waybill_template	string	渲染后的面单 HTML 文件（已经过 Base64 编码）

# 其他说明

# 模板渲染语法

所有渲染语法由##开始，可参考示例。
##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	服务名称

##TIME(DATE) 用日期填充当前位置，格式为%Y/%m/%d，比如2018/11/22。
##TIME(TIME) 用时间填充当前位置，格式为%H:%M:%S，比如17:54:06。
##TIME(FULL) 用日期时间填充当前位置，格式为%Y/%m/%d %H:%M:%S，比如2018/11/22 17:54:06。
##STRBLOAT(VAR(sys.waybillid)) 获取运单 ID，然后在每个字符间填充空格。
##CODE128(VAR(sys.waybillid)) 获取运单 ID，然后转换成CODE128条码，图片为base64编码。
##QRCODE(VAR(sys.waybillid)) 获取运单 ID，然后转换为二维码，图片为base64编码。
##WXASUNCODE(VAR(sys.wxaappid)) 获取商户的小程序码，图片为base64编码。

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

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

# 调用示例

示例说明: HTTPS调用

# 请求数据示例


{
  "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="
}

示例说明: 云函数调用

# 请求数据示例


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
  }
}

# 返回数据示例


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

# 错误码

错误码	错误码取值	解决方案
-1	system error	系统繁忙，此时请开发者稍候再试
40199	waybill_id not found	运单 ID 不存在，未查到运单
9300507	invalid token can't decryption ordecryption result is different from the plaintext	Token 不正确
9300502	Delivery side sys error	快递公司系统错误
9300512	invalid waybill template format	模板格式错误，渲染失败