logistics.previewTemplate

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

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

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

调用方式:

HTTPS 调用

请求地址

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

请求参数

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

返回值

Object

属性类型说明
waybill_idstring运单 ID
rendered_waybill_templatestring渲染后的面单 HTML 文件(已经过 Base64 编码)
errcodenumber错误码
errmsgstring错误信息

errcode 的合法值

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

请求数据示例

  1. {
  2. "waybill_id": "1234567890123",
  3. "waybill_data": "##ZTO_mark##11-22-33##ZTO_bagAddr##广州##",
  4. "waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4=",
  5. "custom": {
  6. "order_id": "012345678901234567890123456789",
  7. "openid": "oABC123456",
  8. "delivery_id": "ZTO",
  9. "biz_id": "xyz",
  10. "custom_remark": "易碎物品",
  11. "sender": {
  12. "name": "张三",
  13. "tel": "18666666666",
  14. "mobile": "020-88888888",
  15. "company": "公司名",
  16. "post_code": "123456",
  17. "country": "中国",
  18. "province": "广东省",
  19. "city": "广州市",
  20. "area": "海珠区",
  21. "address": "XX路XX号XX大厦XX栋XX"
  22. },
  23. "receiver": {
  24. "name": "王小蒙",
  25. "tel": "18610000000",
  26. "mobile": "020-77777777",
  27. "company": "公司名",
  28. "post_code": "654321",
  29. "country": "中国",
  30. "province": "广东省",
  31. "city": "广州市",
  32. "area": "天河区",
  33. "address": "XX路XX号XX大厦XX栋XX"
  34. },
  35. "shop": {
  36. "wxa_path": "/index/index?from=waybill",
  37. "img_url": "https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640",
  38. "goods_name": "一千零一夜钻石包&爱马仕柏金钻石包",
  39. "goods_count": 2
  40. },
  41. "cargo": {
  42. "count": 2,
  43. "weight": 5.5,
  44. "space_x": 30.5,
  45. "space_y": 20,
  46. "space_z": 20,
  47. "detail_list": [
  48. {
  49. "name": "一千零一夜钻石包",
  50. "count": 1
  51. },
  52. {
  53. "name": "爱马仕柏金钻石包",
  54. "count": 1
  55. }
  56. ]
  57. },
  58. "insured": {
  59. "use_insured": 1,
  60. "insured_value": 10000
  61. },
  62. "service": {
  63. "service_type": 0,
  64. "service_name": "标准快递"
  65. }
  66. }
  67. }

返回数据示例

  1. {
  2. "waybill_id": "1234567890123",
  3. "rendered_waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4="
  4. }

模板渲染语法

  1. 所有渲染语法由##开始,可参考示例)。
  2. ##VAR(key) 用参数key对应的值填充。支持的参数如下表格所示
keyvalue
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编码。

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

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

云调用

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

接口方法

  1. openapi.logistics.previewTemplate

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

请求参数

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

返回值

Object

属性类型说明
waybillIdstring运单 ID
renderedWaybillTemplatestring渲染后的面单 HTML 文件(已经过 Base64 编码)
errCodenumber错误码
errMsgstring错误信息

errCode 的合法值

说明最低版本
0成功

异常

Object

抛出的异常

属性类型说明
errCodenumber错误码
errMsgstring错误信息

errCode 的合法值

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

请求数据示例

  1. const cloud = require('wx-server-sdk')
  2. cloud.init({
  3. env: cloud.DYNAMIC_CURRENT_ENV,
  4. })
  5. exports.main = async (event, context) => {
  6. try {
  7. const result = await cloud.openapi.logistics.previewTemplate({
  8. custom: {
  9. openid: 'oABC123456',
  10. sender: {
  11. name: '张三',
  12. tel: '18666666666',
  13. mobile: '020-88888888',
  14. company: '公司名',
  15. country: '中国',
  16. province: '广东省',
  17. city: '广州市',
  18. area: '海珠区',
  19. address: 'XX路XX号XX大厦XX栋XX',
  20. postCode: '123456'
  21. },
  22. receiver: {
  23. name: '王小蒙',
  24. tel: '18610000000',
  25. mobile: '020-77777777',
  26. company: '公司名',
  27. country: '中国',
  28. province: '广东省',
  29. city: '广州市',
  30. area: '天河区',
  31. address: 'XX路XX号XX大厦XX栋XX',
  32. postCode: '654321'
  33. },
  34. shop: {
  35. wxaPath: '/index/index?from=waybill',
  36. imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640',
  37. goodsName: '一千零一夜钻石包&爱马仕柏金钻石包',
  38. goodsCount: 2
  39. },
  40. cargo: {
  41. count: 2,
  42. weight: 5.5,
  43. spaceX: 30.5,
  44. spaceY: 20,
  45. spaceZ: 20,
  46. detailList: [
  47. {
  48. name: '一千零一夜钻石包',
  49. count: 1
  50. },
  51. {
  52. name: '爱马仕柏金钻石包',
  53. count: 1
  54. }
  55. ]
  56. },
  57. insured: {
  58. useInsured: 1,
  59. insuredValue: 10000
  60. },
  61. service: {
  62. serviceType: 0,
  63. serviceName: '标准快递'
  64. },
  65. orderId: '012345678901234567890123456789',
  66. deliveryId: 'ZTO',
  67. bizId: 'xyz',
  68. customRemark: '易碎物品'
  69. },
  70. waybillId: '1234567890123',
  71. waybillData: '##ZTO_mark##11-22-33##ZTO_bagAddr##广州##',
  72. waybillTemplate: 'PGh0bWw+dGVzdDwvaHRtbD4='
  73. })
  74. return result
  75. } catch (err) {
  76. return err
  77. }
  78. }

返回数据示例

  1. {
  2. "waybillId": "1234567890123",
  3. "renderedWaybillTemplate": "PGh0bWw+dGVzdDwvaHRtbD4=",
  4. "errMsg": "openapi.logistics.previewTemplate:ok"
  5. }