预览面单模板
预览面单模板
接口应在服务器端调用，详细说明参见服务端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_idstring是订单ID，须保证全局唯一，不超过512字节openidstring是用户openid，当add_source=2时无需填写（不发送物流服务通知）delivery_idstring是快递公司ID，参见getAllDeliverybiz_idstring是快递客户编码或者现付编码custom_remarkstring否快递备注信息，比如"易碎物品"，不超过1024字节tagidnumber否订单标签id，用于平台型小程序区分平台上的入驻方，tagid须与入驻方账号一一对应，非平台型小程序无需填写该字段add_sourcenumber是订单来源，0为小程序订单，2为App或H5订单，填2则不发送物流服务通知wx_appidstring否App或H5的appid，add_source=2时必填，需和开通了物流助手的小程序绑定同一open账号senderobject是发件人信息属性类型必填说明namestring否发件人姓名，不超过64字节telstring否发件人座机号码，若不填写则必须填写 mobile，不超过32字节mobilestring否发件人手机号码，若不填写则必须填写 tel，不超过32字节companystring否发件人公司名称，不超过64字节post_codestring否发件人邮编，不超过10字节countrystring否发件人国家，不超过64字节provincestring否发件人省份，比如："广东省"，不超过64字节citystring否发件人市/地区，比如："广州市"，不超过64字节areastring否发件人区/县，比如："海珠区"，不超过64字节addressstring否发件人详细地址，比如："XX路XX号XX大厦XX"，不超过512字节receiverobject是收件人信息属性类型必填说明namestring否发件人姓名，不超过64字节telstring否发件人座机号码，若不填写则必须填写 mobile，不超过32字节mobilestring否发件人手机号码，若不填写则必须填写 tel，不超过32字节companystring否发件人公司名称，不超过64字节post_codestring否发件人邮编，不超过10字节countrystring否发件人国家，不超过64字节provincestring否发件人省份，比如："广东省"，不超过64字节citystring否发件人市/地区，比如："广州市"，不超过64字节areastring否发件人区/县，比如："海珠区"，不超过64字节addressstring否发件人详细地址，比如："XX路XX号XX大厦XX"，不超过512字节cargoobject是包裹信息，将传递给快递公司属性类型必填说明countnumber是包裹数量, 默认为1weightnumber是包裹总重量，单位是千克(kg)space_xnumber是包裹总重量，单位是千克(kg)space_ynumber是包裹总重量，单位是千克(kg)space_znumber是包裹总重量，单位是千克(kg)detail_listarray |
返回参数
| 属性 | 类型 | 说明 |
|---|---|---|
| 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 | 模板格式错误，渲染失败 |
浙公网安备 33010602011771号