获取面单 ZPL

接口概述

生成包裹的 CN23 面单，并以 ZPL 指令流返回，可直接发送给 Zebra 兼容的热敏打印机。

包裹必须已存在，且必须用 WMG 运单号 标识——如果你只有自己的单号，请先调用 获取运单号。

请求信息

• Method: POST
• Path: /api/create-label-zpl
• Authentication: Bearer Token

请求头

字段	说明
Content-Type	application/json
Authorization	Bearer <token>

请求参数

请求体为 JSON 格式，包含以下字段：

参数	类型	必填	说明
Barcode	string	是	包裹的 WMG 运单号，最长 50 个字符。
LabelType	string	是	标签类型。目前仅支持 CN23。最长 10 个字符。
Origin	string	是	起运国家，2 位国家代码，如 SG 表示新加坡、TW 表示台湾。
Destination	string	是	目的国家，2 位国家代码，如 TW 表示台湾、JP 表示日本。

请求体示例

{
    "Barcode": "CY180000662SG",
    "LabelType": "CN23",
    "Origin": "SG",
    "Destination": "JP"
}

认证方式

本接口使用 Bearer Token 认证。

请先通过 获取 Token 取得 Token，并以 Authorization: Bearer <Token> 形式发送。

响应信息

响应为 JSON 格式。

响应格式

字段	类型	说明
Code	integer	0 表示成功；非 0 表示失败
Message	string	可读的结果说明
Data	object	业务数据；失败时为空数组 []

成功响应

• Status Code: 200

{
    "Code": 0,
    "Message": "Success",
    "Data": {
        "Zpl": "^XA^GFA,7200,7200,90,:Z64:eJzt3D1v2zAQBuC..."
    }
}

示例中的 Zpl 值已截断，实际响应包含完整的 ZPL 指令流。

字段	类型	说明
Data.Zpl	string	CN23 面单的 ZPL 指令流。原样发送给打印机即可。

错误响应

• Status Code: 200（业务逻辑错误）或 4xx/5xx（系统错误）

{
    "Code": 1,
    "Message": "Parcel not found",
    "Data": []
}

结果码

Code	说明
0	成功
1	失败

示例

Bash

BASE_URL="https://api.postal.test.wmgdelivery.com"
TOKEN="your_access_token"

curl -X POST "$BASE_URL/api/create-label-zpl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"Barcode":"CY180000662SG","LabelType":"CN23","Origin":"SG","Destination":"JP"}'

Windows PowerShell

$BASE_URL = "https://api.postal.test.wmgdelivery.com"
$TOKEN    = "your_access_token"

$body = @{
    Barcode     = "CY180000662SG"
    LabelType   = "CN23"
    Origin      = "SG"
    Destination = "JP"
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "$BASE_URL/api/create-label-zpl" -Method Post `
    -ContentType "application/json" -Body $body -Headers @{Authorization = "Bearer $TOKEN"}

# 原样写出 ZPL 供打印机使用（不加结尾换行，不加 BOM）
[IO.File]::WriteAllText("label.zpl", $response.Data.Zpl)

Python

import requests

BASE_URL = "https://api.postal.test.wmgdelivery.com"
TOKEN    = "your_access_token"

resp = requests.post(f"{BASE_URL}/api/create-label-zpl", json={
    "Barcode": "CY180000662SG",
    "LabelType": "CN23",
    "Origin": "SG",
    "Destination": "JP",
}, headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
payload = resp.json()

# 原样写出 ZPL 供打印机使用
with open("label.zpl", "w", encoding="utf-8", newline="") as fh:
    fh.write(payload["Data"]["Zpl"])

Node.js / TypeScript

import {writeFileSync} from "node:fs";

const BASE_URL = "https://api.postal.test.wmgdelivery.com";
const TOKEN = "your_access_token";

const res = await fetch(`${BASE_URL}/api/create-label-zpl`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    Barcode: "CY180000662SG",
    LabelType: "CN23",
    Origin: "SG",
    Destination: "JP",
  }),
});
const payload = await res.json();

// 原样写出 ZPL 供打印机使用
writeFileSync("label.zpl", payload.Data.Zpl, "utf8");

PHP

<?php
$BASE_URL = 'https://api.postal.test.wmgdelivery.com';
$TOKEN    = 'your_access_token';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $BASE_URL . '/api/create-label-zpl');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $TOKEN,
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'Barcode'     => 'CY180000662SG',
    'LabelType'   => 'CN23',
    'Origin'      => 'SG',
    'Destination' => 'JP',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
curl_close($ch);

$payload = json_decode($response, true);

// 原样写出 ZPL 供打印机使用
file_put_contents('label.zpl', $payload['Data']['Zpl']);
?>

注意事项

• Barcode 必须是 WMG 运单号，不是你自己的单号。
• Barcode 在匹配前会转为大写；Origin 和 Destination 按原样匹配，请用大写发送。
• ZPL 是先渲染 PDF 面单、再转成位图并封装进 ZPL 指令流得到的。因此 获取面单 PDF 的所有前置条件对本接口同样适用。
• 由于多了这一步转换，本接口是三个面单接口中最慢的，客户端超时时间请设置得宽松一些。
• 面单始终按默认方向渲染；本接口没有 Direction 参数。
• 生成面单会在包裹上记录一条打单事件，因此会出现在该包裹的轨迹历史中。
• 使用自有面单（self-label）服务的包裹无法通过本接口出单，会返回 The package cannot undergo this operation。
• LabelType 只校验长度，不影响生成的面单内容。请传 CN23。
• 其余参数区分大小写。

错误码

code	message	说明
1	Parcel not found	你的账号下没有与 Barcode、Origin、Destination 全部匹配的包裹。
1	The package cannot undergo this operation	该包裹使用自有面单服务，WMG 不为其生成面单。
1	Barcode require	Barcode 缺失或为空。
1	max size of Barcode must be 50	Barcode 超过 50 个字符。
1	LabelType require	LabelType 缺失或为空。
1	max size of LabelType must be 10	LabelType 超过 10 个字符。
1	Origin require	Origin 缺失或为空。
1	max size of Origin must be 2	Origin 超过 2 个字符。
1	Destination require	Destination 缺失或为空。
1	max size of Destination must be 2	Destination 超过 2 个字符。
1	Error encountered, please contact tech@wmg-group.com with screenshot of error page for resolution.	未预期的服务端错误。
1003	Token error	Token 缺失、已过期或被新登录顶替。请重新调用 获取 Token。