获取面单 PDF

接口概述

生成包裹的 CN23 面单，并以 Base64 编码的 PDF 返回。解码该字符串即可得到 PDF 文件。

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

请求信息

• Method: POST
• Path: /api/create-label
• 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 表示日本。
Direction	string	否	页面方向：horizontal（横向）或 vertical（纵向）。默认 horizontal。

请求体示例

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

认证方式

本接口使用 Bearer Token 认证。

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

响应信息

响应为 JSON 格式。

响应格式

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

成功响应

• Status Code: 200

{
    "Code": 0,
    "Message": "Success",
    "Data": {
        "Base64": "JVBERi0xLjcKJeLjz9MKMyAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQ..."
    }
}

示例中的 Base64 值已截断，实际响应包含完整的编码后 PDF。

字段	类型	说明
Data.Base64	string	CN23 面单，Base64 编码的 PDF。解码后即为 PDF 文件。

错误响应

• 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" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"Barcode":"CY180000662SG","LabelType":"CN23","Origin":"SG","Destination":"JP","Direction":"horizontal"}'

Windows PowerShell

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

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

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

# 将 Base64 内容解码为 PDF 文件
[IO.File]::WriteAllBytes("label.pdf", [Convert]::FromBase64String($response.Data.Base64))

Python

import base64
import requests

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

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

# 将 Base64 内容解码为 PDF 文件
with open("label.pdf", "wb") as fh:
    fh.write(base64.b64decode(payload["Data"]["Base64"]))

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`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    Barcode: "CY180000662SG",
    LabelType: "CN23",
    Origin: "SG",
    Destination: "JP",
    Direction: "horizontal",
  }),
});
const payload = await res.json();

// 将 Base64 内容解码为 PDF 文件
writeFileSync("label.pdf", Buffer.from(payload.Data.Base64, "base64"));

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');
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',
    'Direction'   => 'horizontal',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
curl_close($ch);

$payload = json_decode($response, true);

// 将 Base64 内容解码为 PDF 文件
file_put_contents('label.pdf', base64_decode($payload['Data']['Base64']));
?>

注意事项

• Barcode 必须是 WMG 运单号，不是你自己的单号。这一点与 获取运单号 相反——那里的 Barcode 是你自己的单号。
• Barcode 在匹配前会转为大写；Origin 和 Destination 按原样匹配，请用大写发送。
• Direction 只接受 horizontal 或 vertical。传其他值会返回 Code: 1 和通用错误消息，而不是针对该字段的提示。
• 生成面单会在包裹上记录一条打单事件，因此会出现在该包裹的轨迹历史中。
• 使用自有面单（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.	未预期的服务端错误，也包括 Direction 传了非法值。
1003	Token error	Token 缺失、已过期或被新登录顶替。请重新调用 获取 Token。