创建单个包裹

接口概述

登记一个包裹并返回系统为其分配的 WMG 运单号。这是整个接入流程的入口：先在这里创建包裹，再用获取面单 PDF 取面单，等到可以发运时通过创建并关闭订单把它纳入订单。

包裹是同步创建的，因此返回的运单号可以立即使用。

请求信息

Method: POST
Path: /api/parcel/create-order
Authentication: Bearer Token

请求头

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

请求参数

请求体为 JSON 格式，包含以下字段。除商品明细放在 ItemListing 数组内，其余字段都在顶层。

运输信息

参数	类型	必填	说明
OwnerId	number	否	你的公司标识，会原样回显在响应中。
ServiceCode	string	否	使用的服务代码，由客户经理提供。不传则使用你账号配置的第一个服务代码。必须是你账号已开通的服务代码之一。
TrackingNumber	string	是	你自己为该包裹分配的跟踪号，即打印在包裹上的单号。最长 50 个字符。在你的账号内必须唯一。
Origin	string	是	起运国家，2 位国家代码，如 `SG`。必须正好 2 个字符。
Destination	string	是	目的国家，2 位国家代码，如 `TH`。必须正好 2 个字符，且必须是你账号已开通的目的地。
Dep_Iata	string	是	出发机场 IATA 代码。必须正好 3 个字符。
Arr_Iata	string	是	到达机场 IATA 代码。必须正好 3 个字符。
Commodity	string	是	包裹内容的简要描述。
DeclaredCurrency	string	是	申报价值的币种，如 `SGD`。必须正好 3 个字符，且必须是该目的地允许的币种。
DeclaredValue	number	是	包裹申报价值。必须大于或等于 0。
Qty	number	是	该运单号下的件数。必须大于 0。
Weight	number	是	申报重量。必须大于或等于 0。最多保留 3 位小数。
Length	number	否	包裹长度。必须大于或等于 0。最多保留 2 位小数。
Width	number	否	包裹宽度。必须大于或等于 0。最多保留 2 位小数。
Height	number	否	包裹高度。必须大于或等于 0。最多保留 2 位小数。
IsDDP	string	否	清关模式：`Y` = DDP，`N` = DDU。默认 `N`。
MAWBNumber	string	否	航空运单号。最长 30 个字符。
SendingAgentID	string	否	客户或生产商参考号。最长 50 个字符。
OrderNumber	string	否	你系统内部的订单号。最长 50 个字符。
Remark	string	否	派送说明。最长 50 个字符。
ETD	string	否	起运地预计出发时间，格式 `YYYY-MM-DD HH:MM:SS`。
ETA	string	否	目的地预计到达时间，格式 `YYYY-MM-DD HH:MM:SS`。必须晚于 `ETD`。
PickUpDate	string	否	上门取件时间，格式 `YYYY-MM-DD HH:MM:SS`。
DeliveryDate	string	否	预期派送时间，格式 `YYYY-MM-DD HH:MM:SS`。

货到付款（COD）

参数	类型	必填	说明
IsCOD	string	否	`Y` = 货到付款，`N` = 非货到付款。
CODType	integer	否	预期收款方式：`0` = 未指定（默认），`1` = 现金（Cash），`2` = 支票（Cheque）。
CODCurrency	string	否	收款币种。必须正好 3 个字符。
CODAmount	number	否	收款金额。必须大于或等于 0。

新加坡 GST —— 当 Destination 为 SG 时必填，其他目的地可选

参数	类型	必填	说明
SupplierName	string	条件必填	供应商名称。最长 100 个字符。
GSTRegNo	string	条件必填	供应商 GST 注册号。最长 50 个字符。
GSTAmount	number	条件必填	已缴 GST 金额。必须大于或等于 0。
GSTCurrency	string	条件必填	GST 金额的币种。必须正好 3 个字符。
GSTStatus	string	条件必填	GST 状态。最长 5 个字符。

寄件人

参数	类型	必填	说明
SenderName	string	是	寄件人姓名。最长 60 个字符。
SenderCompany	string	否	寄件人公司。最长 80 个字符。
SenderAddress1	string	是	寄件人地址第 1 行。最长 160 个字符。
SenderAddress2	string	否	寄件人地址第 2 行。最长 100 个字符。
SenderCity	string	否	寄件人城市。最长 50 个字符。
SenderState	string	否	寄件人州/省。最长 50 个字符。
SenderCountry	string	是	寄件人国家名称。最长 60 个字符。
SenderPostalCode	string	是	寄件人邮编。最长 20 个字符。不使用邮编的国家请传空字符串。
SenderContactNo	string	否	寄件人联系电话。最长 20 个字符。
SenderEmail	string	否	寄件人邮箱。最长 100 个字符。

收件人

参数	类型	必填	说明
RecipientName	string	是	收件人姓名。最长 60 个字符。
RecipientCompany	string	否	收件人公司。最长 80 个字符。
RecipientAddress1	string	是	收件人地址第 1 行。最长 160 个字符。
RecipientAddress2	string	否	收件人地址第 2 行。最长 160 个字符。
RecipientAddress3	string	否	收件人地址第 3 行。最长 100 个字符。
RecipientCity	string	是	收件人城市。最长 50 个字符。
RecipientState	string	是	收件人州/省。最长 50 个字符。
RecipientCountry	string	是	收件人国家名称。最长 60 个字符。
RecipientPostalCode	string	是	收件人邮编。最长 20 个字符。对有邮编格式要求的目的地会按其格式校验。
RecipientContactNo	string	是	收件人联系电话。最长 20 个字符。
RecipientEmail	string	否	收件人邮箱。最长 100 个字符。

ItemListing —— 数组，至少一条

参数	类型	必填	说明
ItemListing[].SKU	string	否	你的商品 SKU。最长 60 个字符。
ItemListing[].ItemDescription	string	是	商品描述。最长 300 个字符。
ItemListing[].ItemWeight	number	是	商品重量。必须大于或等于 0。
ItemListing[].NoOfPcs	number	是	该商品的件数。必须大于或等于 0。
ItemListing[].ItemValue	number	是	商品价值。必须大于或等于 0。
ItemListing[].ItemCurrency	string	是	商品价值币种。最长 3 个字符，且必须是该目的地允许的币种。
ItemListing[].ItemOrigin	string	是	商品原产国，2 位国家代码。最长 2 个字符。
ItemListing[].ItemDestination	string	是	商品目的国，2 位国家代码。最长 2 个字符。
ItemListing[].HSCode	string	是	商品 HS 编码。最长 50 个字符。

请求体示例

json

{
  "OwnerId": 111,
  "ServiceCode": "A0000",
  "TrackingNumber": "CUST0001234567",
  "Origin": "SG",
  "Destination": "TH",
  "Dep_Iata": "SIN",
  "Arr_Iata": "BKK",
  "Commodity": "Cotton T-shirts",
  "DeclaredCurrency": "SGD",
  "DeclaredValue": 45.50,
  "Qty": 1,
  "Weight": 1.250,
  "Length": 30.00,
  "Width": 20.00,
  "Height": 10.00,
  "IsDDP": "N",
  "OrderNumber": "SO-2026-000123",
  "ETD": "2026-07-30 14:25:00",
  "ETA": "2026-07-31 09:15:00",
  "SenderName": "Jane Tan",
  "SenderCompany": "Example Trading Pte Ltd",
  "SenderAddress1": "10 Anson Road #12-01",
  "SenderCity": "Singapore",
  "SenderCountry": "Singapore",
  "SenderPostalCode": "079903",
  "SenderContactNo": "+6561234567",
  "SenderEmail": "jane.tan@example.com",
  "RecipientName": "Somchai Preecha",
  "RecipientAddress1": "99 Sukhumvit Road",
  "RecipientAddress2": "Khlong Toei",
  "RecipientCity": "Bangkok",
  "RecipientState": "Bangkok",
  "RecipientCountry": "Thailand",
  "RecipientPostalCode": "10110",
  "RecipientContactNo": "+66812345678",
  "RecipientEmail": "somchai@example.com",
  "ItemListing": [
    {
      "SKU": "TS-BLK-M",
      "ItemDescription": "Cotton T-shirt, black, size M",
      "ItemWeight": 0.250,
      "NoOfPcs": 2,
      "ItemValue": 15.00,
      "ItemCurrency": "SGD",
      "ItemOrigin": "SG",
      "ItemDestination": "TH",
      "HSCode": "610910"
    },
    {
      "SKU": "TS-WHT-L",
      "ItemDescription": "Cotton T-shirt, white, size L",
      "ItemWeight": 0.750,
      "NoOfPcs": 1,
      "ItemValue": 15.50,
      "ItemCurrency": "SGD",
      "ItemOrigin": "SG",
      "ItemDestination": "TH",
      "HSCode": "610910"
    }
  ]
}

认证方式

本接口使用 Bearer Token 认证。

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

响应信息

响应为 JSON 格式。

响应格式

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

成功响应

Status Code: 200

json

{
  "Code": 0,
  "Message": "Success",
  "Data": {
    "OwnerId": 111,
    "TrackingNo": "CUST0001234567",
    "WmgTrackingNo": "CY180000999SG",
    "DeliveryId": "",
    "DateTime": "2026-07-30 15:43:48",
    "Status": "",
    "Error": []
  }
}

字段	类型	说明
Data.OwnerId	number	原样回显你传入的 `OwnerId`。未传时为空字符串。
Data.TrackingNo	string	你传入的跟踪号，保持原样大小写。
Data.WmgTrackingNo	string	系统为该包裹分配的 WMG 运单号。后续出面单、查轨迹、下订单都用它。
Data.DeliveryId	string	预留字段，始终返回空字符串。
Data.DateTime	string	包裹创建时的服务器时间，格式 `YYYY-MM-DD HH:MM:SS`。
Data.Status	string	预留字段，始终返回空字符串。
Data.Error	array	预留字段，始终返回空数组——失败时会以 `Code: 1` 返回。

错误响应

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

json

{
    "Code": 1,
    "Message": "Tracking Number already exist",
    "Data": []
}

结果码

Code	说明
0	成功
1	失败

示例

Bash

bash

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

curl -X POST "$BASE_URL/api/parcel/create-order" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @parcel.json

Windows PowerShell

powershell

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

$body = @{
    ServiceCode         = "A0000"
    TrackingNumber      = "CUST0001234567"
    Origin              = "SG"
    Destination         = "TH"
    Dep_Iata            = "SIN"
    Arr_Iata            = "BKK"
    Commodity           = "Cotton T-shirts"
    DeclaredCurrency    = "SGD"
    DeclaredValue       = 45.50
    Qty                 = 1
    Weight              = 1.250
    SenderName          = "Jane Tan"
    SenderAddress1      = "10 Anson Road #12-01"
    SenderCountry       = "Singapore"
    SenderPostalCode    = "079903"
    RecipientName       = "Somchai Preecha"
    RecipientAddress1   = "99 Sukhumvit Road"
    RecipientCity       = "Bangkok"
    RecipientState      = "Bangkok"
    RecipientCountry    = "Thailand"
    RecipientPostalCode = "10110"
    RecipientContactNo  = "+66812345678"
    ItemListing         = @(
        @{
            ItemDescription = "Cotton T-shirt, black, size M"
            ItemWeight      = 0.250
            NoOfPcs         = 2
            ItemValue       = 15.00
            ItemCurrency    = "SGD"
            ItemOrigin      = "SG"
            ItemDestination = "TH"
            HSCode          = "610910"
        }
    )
} | ConvertTo-Json -Depth 5

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

Python

python

import requests

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

parcel = {
    "ServiceCode": "A0000",
    "TrackingNumber": "CUST0001234567",
    "Origin": "SG",
    "Destination": "TH",
    "Dep_Iata": "SIN",
    "Arr_Iata": "BKK",
    "Commodity": "Cotton T-shirts",
    "DeclaredCurrency": "SGD",
    "DeclaredValue": 45.50,
    "Qty": 1,
    "Weight": 1.250,
    "SenderName": "Jane Tan",
    "SenderAddress1": "10 Anson Road #12-01",
    "SenderCountry": "Singapore",
    "SenderPostalCode": "079903",
    "RecipientName": "Somchai Preecha",
    "RecipientAddress1": "99 Sukhumvit Road",
    "RecipientCity": "Bangkok",
    "RecipientState": "Bangkok",
    "RecipientCountry": "Thailand",
    "RecipientPostalCode": "10110",
    "RecipientContactNo": "+66812345678",
    "ItemListing": [
        {
            "ItemDescription": "Cotton T-shirt, black, size M",
            "ItemWeight": 0.250,
            "NoOfPcs": 2,
            "ItemValue": 15.00,
            "ItemCurrency": "SGD",
            "ItemOrigin": "SG",
            "ItemDestination": "TH",
            "HSCode": "610910",
        },
    ],
}

resp = requests.post(f"{BASE_URL}/api/parcel/create-order", json=parcel,
                     headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
payload = resp.json()
print(payload["Data"]["WmgTrackingNo"])

Node.js / TypeScript

typescript

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

const parcel = {
  ServiceCode: "A0000",
  TrackingNumber: "CUST0001234567",
  Origin: "SG",
  Destination: "TH",
  Dep_Iata: "SIN",
  Arr_Iata: "BKK",
  Commodity: "Cotton T-shirts",
  DeclaredCurrency: "SGD",
  DeclaredValue: 45.50,
  Qty: 1,
  Weight: 1.250,
  SenderName: "Jane Tan",
  SenderAddress1: "10 Anson Road #12-01",
  SenderCountry: "Singapore",
  SenderPostalCode: "079903",
  RecipientName: "Somchai Preecha",
  RecipientAddress1: "99 Sukhumvit Road",
  RecipientCity: "Bangkok",
  RecipientState: "Bangkok",
  RecipientCountry: "Thailand",
  RecipientPostalCode: "10110",
  RecipientContactNo: "+66812345678",
  ItemListing: [
    {
      ItemDescription: "Cotton T-shirt, black, size M",
      ItemWeight: 0.250,
      NoOfPcs: 2,
      ItemValue: 15.00,
      ItemCurrency: "SGD",
      ItemOrigin: "SG",
      ItemDestination: "TH",
      HSCode: "610910",
    },
  ],
};

const res = await fetch(`${BASE_URL}/api/parcel/create-order`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${TOKEN}`,
  },
  body: JSON.stringify(parcel),
});
const payload = await res.json();
console.log(payload.Data.WmgTrackingNo);

PHP

php

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

$parcel = [
    'ServiceCode'         => 'A0000',
    'TrackingNumber'      => 'CUST0001234567',
    'Origin'              => 'SG',
    'Destination'         => 'TH',
    'Dep_Iata'            => 'SIN',
    'Arr_Iata'            => 'BKK',
    'Commodity'           => 'Cotton T-shirts',
    'DeclaredCurrency'    => 'SGD',
    'DeclaredValue'       => 45.50,
    'Qty'                 => 1,
    'Weight'              => 1.250,
    'SenderName'          => 'Jane Tan',
    'SenderAddress1'      => '10 Anson Road #12-01',
    'SenderCountry'       => 'Singapore',
    'SenderPostalCode'    => '079903',
    'RecipientName'       => 'Somchai Preecha',
    'RecipientAddress1'   => '99 Sukhumvit Road',
    'RecipientCity'       => 'Bangkok',
    'RecipientState'      => 'Bangkok',
    'RecipientCountry'    => 'Thailand',
    'RecipientPostalCode' => '10110',
    'RecipientContactNo'  => '+66812345678',
    'ItemListing'         => [
        [
            'ItemDescription' => 'Cotton T-shirt, black, size M',
            'ItemWeight'      => 0.250,
            'NoOfPcs'         => 2,
            'ItemValue'       => 15.00,
            'ItemCurrency'    => 'SGD',
            'ItemOrigin'      => 'SG',
            'ItemDestination' => 'TH',
            'HSCode'          => '610910',
        ],
    ],
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $BASE_URL . '/api/parcel/create-order');
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($parcel));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
curl_close($ch);

$payload = json_decode($response, true);
echo $payload['Data']['WmgTrackingNo'] . "\n";
?>

注意事项

TrackingNumber 在你的账号内必须唯一。重复提交已存在的单号会返回 Tracking Number already exist——本接口不是幂等的，也不会返回之前那个包裹。
TrackingNumber 和 Destination 在处理前会转为大写，因此后续匹配用的是大写形式；而 Data.TrackingNo 会原样回显你传入的大小写。
允许不传 ServiceCode：此时使用你账号配置的第一个服务代码。如果账号完全没有配置服务代码，调用会失败并返回 User Service Codes is Empty。
RecipientAddress1、RecipientAddress2、RecipientAddress3 会拼接后打在面单上。三者合计长度不得超过 320 个字符，这与每个字段各自的长度上限是两回事。
DeclaredCurrency 和每条 ItemCurrency 都必须是该目的地允许的币种，否则包裹被拒收。商品币种错误的消息里会给出从 1 开始的商品序号。
目的地为 MY 时，Commodity 和每条 ItemDescription 会被检查是否含医疗、药品相关词汇，命中则返回 Prohibited Item, Do Not Import!。
日期字段（ETD、ETA、PickUpDate、DeliveryDate）使用 YYYY-MM-DD HH:MM:SS 格式。带 T 分隔符或时区偏移的 ISO 8601 字符串会被拒绝。
同时传了 ETD 和 ETA 时，ETA 必须晚于 ETD。
新加坡 GST 相关字段只在 Destination 为 SG 时才必填。
Data.DeliveryId、Data.Status、Data.Error 都是预留字段，始终为空。请用 Code 而不是 Error 判断调用是否成功。
校验在第一个失败处即中断，因此改好一个字段后可能暴露下一个。接入调试阶段请预期多次往返。
所有参数区分大小写。

错误码

code	message	说明
`1`	Tracking Number cannot be empty	`TrackingNumber` 缺失或为空白。
`1`	Tracking Number already exist	你的账号下已存在该 `TrackingNumber` 的包裹。
`1`	User Service Codes is Empty	未传 `ServiceCode`，且你的账号没有配置任何服务代码。
`1`	ServiceCode invalid	`ServiceCode` 不在你账号已开通的服务代码范围内。
`1`	The account you are using does not support destination "XX" for the time being, please contact your business manager to confirm.	该目的地没有对应的包裹尺寸配置。
`1`	Destination not allow	该目的地已配置，但不允许你的账号与服务使用。
`1`	DeclaredCurrency not allow	`DeclaredCurrency` 不是该目的地允许的币种。
`1`	Item 1 ItemCurrency(SGD) not allow	该条商品的 `ItemCurrency` 不是目的地允许的币种，数字是从 1 开始的商品序号。
`1`	ItemListing required	`ItemListing` 缺失或为空。
`1`	Prohibited Item, Do Not Import!	目的地为 `MY` 时，`Commodity` 或某条 `ItemDescription` 含医疗、药品相关词汇。
`1`	The total length of addresses 1, 2, and 3 exceeds the maximum limit of 320 characters	收件人三行地址拼接后超过 320 个字符。
`1`	TrackingNumber require	`TrackingNumber` 缺失或为空。
`1`	max size of TrackingNumber must be 50	`TrackingNumber` 超过 50 个字符。
`1`	Destination require	`Destination` 缺失或为空。
`1`	size of Destination must be 2	`Destination` 不是正好 2 个字符。
`1`	Origin require	`Origin` 缺失或为空。
`1`	size of Origin must be 2	`Origin` 不是正好 2 个字符。
`1`	Commodity require	`Commodity` 缺失或为空。
`1`	DeclaredCurrency require	`DeclaredCurrency` 缺失或为空。
`1`	size of DeclaredCurrency must be 3	`DeclaredCurrency` 不是正好 3 个字符。
`1`	DeclaredValue require	`DeclaredValue` 缺失或为空。
`1`	Qty require	`Qty` 缺失或为空。
`1`	Weight require	`Weight` 缺失或为空。
`1`	IsDDP must be in Y,N	`IsDDP` 既不是 `Y` 也不是 `N`。
`1`	IsCOD must be in Y,N	`IsCOD` 既不是 `Y` 也不是 `N`。
`1`	CODType must be in 0,1,2	`CODType` 不是 `0`、`1`、`2`。
`1`	Dep_Iata require	`Dep_Iata` 缺失或为空。
`1`	size of Dep_Iata must be 3	`Dep_Iata` 不是正好 3 个字符。
`1`	Arr_Iata require	`Arr_Iata` 缺失或为空。
`1`	size of Arr_Iata must be 3	`Arr_Iata` 不是正好 3 个字符。
`1`	ETA range is incorrect	`ETA` 不晚于 `ETD`。
`1`	SupplierName require	`Destination` 为 `SG` 但缺少 `SupplierName`。`GSTRegNo`、`GSTAmount`、`GSTCurrency`、`GSTStatus` 同理。
`1`	SenderName require	`SenderName` 缺失或为空。其余寄件人、收件人和商品必填字段同理。
`1`	max size of SenderName must be 60	该字段超过其长度上限。其余有长度限制的字段同理。
`1`	Error encountered, please contact tech@wmg-group.com with screenshot of error page for resolution.	未预期的服务端错误。
`1003`	Token error	Token 缺失、已过期或被新登录顶替。请重新调用获取 Token。

字段级校验消息的规律是：缺失用 <字段名> require，长度问题用 max size of <字段名> must be <n> 或 size of <字段名> must be <n>，字段名与上面各表中的名称完全一致。

创建单个包裹 ​

接口概述 ​

请求信息 ​

请求头 ​

请求参数 ​

请求体示例 ​

认证方式 ​

响应信息 ​

响应格式 ​

成功响应 ​

错误响应 ​

结果码 ​

示例 ​

Bash ​

Windows PowerShell ​

Python ​

Node.js / TypeScript ​

PHP ​

注意事项 ​

错误码 ​

创建单个包裹

接口概述

请求信息

请求头

请求参数

请求体示例

认证方式

响应信息

响应格式

成功响应

错误响应

结果码

示例

Bash

Windows PowerShell

Python

Node.js / TypeScript

PHP

注意事项

错误码