# logistics.previewTemplate

Call this API at the server side. For more information, see Server API.

This API supports Cloud Calls. The WeChat DevTools version must be 1.02.1904090 or later (download the latest stable version here), and the wx-server-sdk version must be 0.4.0 or later.

Previews the waybill template. It is used to debug waybill templates.

Calling methods:

HTTPS call
Cloud call

# HTTPS Call

# Request Address

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

# Request Parameters

Attribute	Type	Required	Description
access_token	string	Yes	Credentials to call API
waybill_id	string	Yes	The ID of the waybill.
waybill_template	string	Yes	The content of the waybill HTML template (Base64 encoding is required).
waybill_data	string	Yes	Waybill data. For details, see WaybillData in the returned values of Order Placement Event.
custom	Object	Yes	The order placement data of the merchant. It is in the format of the request body in the Placing an Order on the Merchant Side API.

# Return Value

# Object

Property	Type	Description
waybill_id	string	The ID of the waybill
rendered_waybill_template	string	The rendered waybill HTML file (which has been Base64 encoded)
errcode	number	Error code
errmsg	string	Error message

Valid values of errcode

Value	Description	Minimum Version
0	Succeeded
-1	Other errors
40199	Incorrect waybill ID. The waybill is not found.
9300507	Incorrect token.
9300502	incorrect waybill_data. This error occurs during template preview.
9300512	Rendering failed due to the incorrect template format.

# Request Data Example

{
  "waybill_id": "1234567890123",
  "waybill_data": "##ZTO_mark##11-22-33##ZTO_bagAddr##Guangzhou##",
  "waybill_template": "PGh0bWw+dGVzdDwvaHRtbD4=",
  "custom": {
    "order_id": "012345678901234567890123456789",
    "openid": "oABC123456",
    "delivery_id": "ZTO",
    "biz_id": "xyz",
    "custom_remark": "Fragile",
    "sender": {
      "name": "Jim",
      "tel": "18666666666",
      "mobile": "020-88888888",
      "company": "Company name",
      "post_code": "123456",
      "country": "China",
      "province": "Guangdong Province",
      "city": "Guangzhou",
      "area": "Haizhu District",
      "address": "XXxx on Block XX, XX Building, No. XX, Road XX"
    },
    "receiver": {
      "name": "Wang Xiaomeng",
      "tel": "18610000000",
      "mobile": "020-77777777",
      "company": "Company name",
      "post_code": "654321",
      "country": "China",
      "province": "Guangdong Province",
      "city": "Guangzhou",
      "area": "Tianhe District",
      "address": "XXxx on Block XX, XX Building, No. XX, Road XX"
    },
    "shop": {
      "wxa_path": "/index/index?from=waybill",
      "img_url": "https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640",
      "goods_name": "1001 Nights Diamond Purse & Hermes Birkin Bag",
      "goods_count": 2
    },
    "cargo": {
      "count": 2,
      "weight": 5.5,
      "space_x": 30.5,
      "space_y": 20,
      "space_z": 20,
      "detail_list": [
        {
          "name": "1001 Nights Diamond Purse",
          "count": 1
        },
        {
          "name": "Hermes Birkin Bag",
          "count": 1
        }
      ]
    },
    "insured": {
      "use_insured": 1,
      "insured_value": 10000
    },
    "service": {
      "service_type": 0,
      "service_name": "Standard express delivery"
    }
  }
}

# Return Data Example

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

# Template Rendering Syntax

All rendering syntax begins with ##. See Examples.
##VAR(key) Enter the value of the key parameter. The following table shows supported parameters.

key	value
sys.waybillid	The ID of the waybill.
sys.wxaappid	The AppID of the merchant's Mini Program.
waybilldata.*	The WaybillData returned in Order Placement Event. This data is defined by the express company.
custom.*	A field passed into the Placing an Order on the merchant Side API.
custom.order_id	The ID that uniquely identifies the order. It is passed in by the merchant.
custom.custom_remark	Remarks on express delivery. It will be printed on the custom area of the waybill, for example, Fragile.
custom.sender.name	The name of the sender.
custom.sender.tel	The telephone number of the sender.
custom.sender.mobile	The mobile number of the sender.
custom.sender.company	The company name of the sender.
custom.sender.post_code	The postal code of the sender's address.
custom.sender.country	The country where the sender is located.
custom.sender.province	The province where the sender is located.
custom.sender.city	The region/city where the sender is located.
custom.sender.area	The district/county where the sender is located.
custom.sender.address	The detailed address of the sender.
custom.receiver.name	The name of the receiver.
custom.receiver.tel	The telephone number of the receiver.
custom.receiver.mobile	The mobile number of the receiver.
custom.receiver.company	The company name of the receiver.
custom.receiver.post_code	The postal code of the receiver's address.
custom.receiver.country	The country where the receiver is located.
custom.receiver.province	The province where the receiver is located.
custom.receiver.city	The region/city where the receiver is located.
custom.receiver.area	The district/county where the receiver is located.
custom.receiver.address	The detailed address of the receiver.
custom.cargo.count	The quantity of parcels.
custom.cargo.weight	The total weight of parcels (in kg).
custom.cargo.space_x	The length of the parcel (in cm).
custom.cargo.space_y	The width of the parcel (in cm).
custom.cargo.space_z	The height of the parcel (in cm).
custom.shop.goods_name	The name of the commodity.
custom.shop.goods_count	The quantity of commodities.
custom.insured.use_insured	Specifies whether to insure the parcel.
custom.insured.insured_value	The insured value (in fen).
custom.service.service_type	The ID of the service type.
custom.service.service_name	The name of the service.

##TIME(DATE) Enter a date in the format of %Y/%m/%d, for example, 2018/11/22.
##TIME(TIME) Enter time in the format of %H:%M:%S, for example, 17:54:06.
##TIME(FULL) Enter a date and time in the format of %Y/%m/%d %H:%M:%S, for example, 2018/11/22 17:54:06.
##STRBLOAT(VAR(sys.waybillid)) Obtain the waybill ID, and then add spaces between every two characters.
##CODE128(VAR(sys.waybillid)) Obtain the waybill ID, and then convert it into a Code 128 barcode, and encode the picture with base64.
##QRCODE(VAR(sys.waybillid)) Obtain the waybill ID, and then convert it into a QR code, and encode the picture with base64.
##WXASUNCODE(VAR(sys.wxaappid)) Obtain the merchant's Mini Program code, and encode the picture with base64.

For example, to print a barcode for parcel gathering location information on a waybill, you can add the following code to the waybill:

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

# Cloud Call

Cloud call is a capability provided by Mini Program·Cloud Base that allows you to call WeChat APIs in a cloud function. It must be used via wx-server-sdk in the cloud function.

# API Calling Method

openapi.logistics.previewTemplate

You need to configure the permissions for the logistics.previewTemplate API via config.json. Details

# Request Parameters

Attribute	Type	Required	Description
waybillId	string	Yes	The ID of the waybill.
waybillTemplate	string	Yes	The content of the waybill HTML template (Base64 encoding is required).
waybillData	string	Yes	Waybill data. For details, see WaybillData in the returned values of Order Placement Event.
custom	Object	Yes	The order placement data of the merchant. It is in the format of the request body in the Placing an Order on the Merchant Side API.

# Return Value

# Object

Property	Type	Description
waybillId	string	The ID of the waybill
renderedWaybillTemplate	string	The rendered waybill HTML file (which has been Base64 encoded)
errCode	number	Error code
errMsg	string	Error message

Valid values of errCode

Value	Description	Minimum Version
0	Succeeded

# Exceptions

# Object

Thrown Exceptions

Property	Type	Description
errCode	number	Error code
errMsg	string	Error message

Valid values of errCode

Value	Description	Minimum Version
-1	Other errors
40199	Incorrect waybill ID. The waybill is not found.
9300507	Incorrect token.
9300502	incorrect waybill_data. This error occurs during template preview.
9300512	Rendering failed due to the incorrect template format.

# Request Data Example

const cloud = require('wx-server-sdk')
  cloud.init()
  exports.main = async (event, context) => {
    try {
      const result = await cloud.openapi.logistics.previewTemplate({
        custom: {
          openid: 'oABC123456',
          sender: {
            name: 'Jim',
            tel: '18666666666',
            mobile: '020-88888888',
            company: 'Company name',
            country: 'China',
            province: 'Guangdong Province',
            city: 'Guangzhou',
            area: 'Haizhu District',
            address: 'XXxx on Block XX, XX Building, No. XX, Road XX',
            postCode: '123456'
          },
          receiver: {
            name: 'Wang Xiaomeng',
            tel: '18610000000',
            mobile: '020-77777777',
            company: 'Company name',
            country: 'China',
            province: 'Guangdong Province',
            city: 'Guangzhou',
            area: 'Tianhe District',
            address: 'XXxx on Block XX, XX Building, No. XX, Road XX',
            postCode: '654321'
          },
          shop: {
            wxaPath: '/index/index?from=waybill',
            imgUrl: 'https://mmbiz.qpic.cn/mmbiz_png/KfrZwACMrmwbPGicysN6kibW0ibXwzmA3mtTwgSsdw4Uicabduu2pfbfwdKicQ8n0v91kRAUX6SDESQypl5tlRwHUPA/640',
            goodsName: '1001 Nights Diamond Purse & Hermes Birkin Bag',
            goodsCount: 2
          },
          cargo: {
            count: 2,
            weight: 5.5,
            spaceX: 30.5,
            spaceY: 20,
            spaceZ: 20,
            detailList: [
              {
                name: '1001 Nights Diamond Purse',
                count: 1
              },
              {
                name: 'Hermes Birkin Bag',
                count: 1
              }
            ]
          },
          insured: {
            useInsured: 1,
            insuredValue: 10000
          },
          service: {
            serviceType: 0,
            serviceName: 'Standard express delivery'
          },
          orderId: '012345678901234567890123456789',
          deliveryId: 'ZTO',
          bizId: 'xyz',
          customRemark: 'Fragile'
        },
        waybillId: '1234567890123',
        waybillData: '##ZTO_mark##11-22-33##ZTO_bagAddr##Guangzhou##',
        waybillTemplate: 'PGh0bWw+dGVzdDwvaHRtbD4='
      })
      console.log(result)
      return result
    } catch (err) {
      console.log(err)
      return err
    }
  }

# Return Data Example

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