# 预览面单模板

接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考接口调用指南

接口英文名：previewTemplate

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

# 1. 调用方式

# HTTPS 调用

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

# 云调用

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

# 第三方调用

本接口不支持第三方平台调用。

# 2. 请求参数

# 查询参数 `Query String parameters`

参数名	类型	必填	说明
access_token	string	是	接口调用凭证，可使用 access_token

# 请求体 `Request Payload`

参数名	类型	必填	说明
waybill_id	string	是	运单 ID
waybill_template	string	是	面单 HTML 模板内容（需经 Base64 编码）
waybill_data	string	是	面单数据。详情参考下单事件返回值中的 WaybillData
custom	object	是	商户下单数据，格式是商户侧下单addOrder 接口中的请求体

# Body.custom `Object Payload`

商户下单数据，格式是商户侧下单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	是	发件人信息
receiver	object	是	收件人信息
cargo	object	是	包裹信息，将传递给快递公司
shop	object	是	商品信息，会展示到物流服务通知和电子面单中
insured	object	是	保价信息
service	object	是	服务类型
expect_time	number	否	Unix 时间戳, 单位秒，顺丰必须传。预期的上门揽件时间，0表示已事先约定取件时间；否则请传预期揽件时间戳，需大于当前时间，收件员会在预期时间附近上门。例如expect_time为“1557989929”，表示希望收件员将在2019年05月16日14:58:49-15:58:49内上门取货。说明：若选择了预期揽件时间，请不要自己打单，由上门揽件的时候打印。如果是下顺丰散单，则必传此字段，否则不会有收件员上门揽件。
take_mode	number	否	分单策略，【0：线下网点签约，1：总部签约结算】，不传默认线下网点签约。目前支持圆通。

# Body.custom.sender `Object Payload`

发件人信息

参数名	类型	必填	说明
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字节

# Body.custom.receiver `Object Payload`

收件人信息

参数名	类型	必填	说明
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字节

# Body.custom.cargo `Object Payload`

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

参数名	类型	必填	说明
count	number	是	包裹数量, 默认为1
weight	number	是	货物总重量，比如1.2，单位是千克(kg)
space_x	number	是	货物长度，比如20.0，单位是厘米(cm)
space_y	number	是	货物宽度，比如15.0，单位是厘米(cm)
space_z	number	是	货物高度，比如10.0，单位是厘米(cm)
detail_list	objarray	是	货物总重量，单位是千克(kg)

# Body.custom.cargo.detail_list(Array) `Object Payload`

货物总重量，单位是千克(kg)

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

# Body.custom.shop `Object Payload`

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

参数名	类型	必填	说明
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	否	该参数在【即时配送】的addLocalOrder接口才生效。若结算方式为：第三方向配送公司统一结算，商户后续和第三方结算，则该参数必填；在该结算模式下，第三方用自己的开发小程序替授权商户发起下单，并将授权小程序的appid给平台，后续配送通知中可回流授权商户小程序。

# Body.custom.insured `Object Payload`

保价信息

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

# Body.custom.service `Object Payload`

服务类型

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

# 3. 返回参数

# 返回体 `Response Payload`

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

# 4. 注意事项

# 模板渲染语法

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

# 5. 代码示例

# 5.1 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="
}

# 5.2 云函数调用

请求示例

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

# 6. 错误码

以下是本接口的错误码列表，其他错误码可参考通用错误码；调用接口遇到报错，可使用官方提供的 API 诊断工具辅助定位和分析问题。

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

# 7. 适用范围

本接口暂未明确可调用账号类型，或在业务中根据调用传参自行确定是否可调用，请已实际调用情况为准。

# 预览面单模板

# 1. 调用方式

# HTTPS 调用

# 云调用

# 第三方调用

# 2. 请求参数

# 查询参数 Query String parameters

# 请求体 Request Payload

# Body.custom Object Payload

# Body.custom.sender Object Payload

# Body.custom.receiver Object Payload

# Body.custom.cargo Object Payload

# Body.custom.cargo.detail_list(Array) Object Payload

# Body.custom.shop Object Payload

# Body.custom.insured Object Payload

# Body.custom.service Object Payload