创建订单

接口说明

提交单个包裹下单。成功后返回 WMG 分配的运单号。

请求信息

方法：POST
路径：/openapi/order/create-order
认证方式：标准 OpenAPI token（基于 MD5）

请求头

字段	说明
Content-Type	application/json
x-auth-name	$API_NAME
x-auth-seed	$SEED（13 位毫秒级 UNIX 时间戳）
x-auth-token	$TOKEN（MD5 哈希）

请求参数

请求体为 JSON 格式。下表按代码中的校验规则整理。

字段名与取值保持英文

字段名与所有取值（如 A/B、Y/N、DDU/DDP）都是接口实际使用的字面量，请勿翻译或改写大小写。

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

参数	类型	必填	说明
custom_tracking_num	string	是	你的内部订单号。只允许字母、数字、`-`、`_`；最长 32 个字符
recipient_name	string	是	收件人全名；最长 64 个字符
recipient_country	string	是	收件国家代码，ISO 3166-1 alpha-2（大写，2 位）
recipient_phone	string	是	收件人电话，仅限数字；最长 24 个字符
recipient_address	string	是	收件详细地址；最长 512 个字符
sender_country	string	是	寄件国家代码，ISO 3166-1 alpha-2（大写，2 位）
client_size	string	是	包裹尺寸，格式 `长,宽,高`（厘米），三个逗号分隔的非负数，如 `30,20,10`；最长 30 个字符
client_weight	float	是	包裹重量（范围 0–9999）；单位跟随账户配置
declared_value	float	是	申报价值；范围 0–9999.99
declared_value_currency	string	是	申报价值币种，ISO 4217 三位字母代码
item	array	是	商品对象数组 —— 见下方 `item[]` 表
postal_code	string	条件必填	收件人邮编。除 `HK` 外的所有目的地均必填。校验前会先剔除非数字字符，再按目的地校验长度（SG = 5–6 位，MY = 4–5 位，KR = 4–5 位，JP = 5–7 位，其他目的地 3–10 位）
recipient_state	string	条件必填	收件人州/省。仅当 `recipient_country = US` 时必填；最长 60 个字符
recipient_city	string	否	收件城市；最长 64 个字符
recipient_email	string	否	收件人邮箱；最长 320 个字符
sender_name	string	条件必填	寄件人全名。揽件类 service_type 下必填；最长 64 个字符
sender_phone	string	条件必填	寄件人电话，仅限数字，最长 24 个字符。揽件类 service_type 下必填
sender_address	string	条件必填	寄件详细地址，最长 512 个字符。揽件类 service_type 下必填
sender_postal_code	string	条件必填	寄件人邮编（3–10 位）。揽件类 service_type 下除 `sender_country = HK` 外均必填；非揽件类为选填
sender_city	string	否	寄件城市；最长 64 个字符
sender_email	string	否	寄件人邮箱；最长 320 个字符
service_type	string	否	服务类型代码，3 位。请使用 WMG 为你的账户分配的代码；不传时按纯尾程处理。揽件类服务类型还需一并提供 `sender_*` 字段
service_code	string	否	承运路由服务代码，3 位。`recipient_country = US` 时必传且必须是有效代码；`SG` 时可不传，传了必须有效；其他目的地会被忽略。账户可用的代码请向 WMG 索取
instruction	string	否	派送备注；最长 1024 个字符
cash	float	否	货到付款金额；0–9999.99；需与 `cash_currency` 同时提供
cash_currency	string	否	货到付款币种，ISO 4217 三位字母代码；`recipient_country = SG` 时必须为 `SGD`；需与 `cash` 同时提供
supplier_name	string	否	供应商名称；最长 64 个字符
supplier_gstn	string	否	供应商 GST 税号；最长 64 个字符
total_gst_amount	float	否	GST 总额；0–9999.99
gst_currency	string	否	GST 币种，ISO 4217 三位字母代码
gst_paid	string	否	`Y` 或 `N`
incoterm_type	string	否	贸易术语：`DDU` 或 `DDP`
locker_type	string	否	智能柜处理方式。`A` = 地址本身已是智能柜地址；`B` = 普通地址，需转换为最近的智能柜。只接受 `A` 和 `B`
locker_station	object	条件必填	当 `locker_type` 为 `A` 时必填。见下方 locker_station 表

item[] 的每个元素必须包含：

参数	类型	必填	说明
description	string	是	商品描述；最长 255 个字符
unitPrice	float	是	单价；≥ 0
quantity	number	是	数量；≥ 0
weight	float	是	商品重量；≥ 0
currency	string	是	币种，ISO 4217 三位字母代码
totalValue	float	是	商品总价；≥ 0
countryOfOrigin	string	否	原产国代码，ISO 3166-1 alpha-2（2 位）
itemHSCode	string	否	海关 HS 编码；最长 255 个字符
productURL	string	否	商品页面 URL；最长 500 个字符

locker_station

参数	类型	必填	说明	长度
zipcode	string	是	智能柜邮编	≤ 16 个字符
station_name	string	是	网点名称	≤ 64 个字符
station_address	string	是	网点地址	≤ 255 个字符
address_detail	string	是	地址补充说明	≤ 255 个字符
distance	float	是	距离
station_code	string	是	网点代码	≤ 10 个字符

请求体示例

json

{
  "custom_tracking_num": "ORDER-20260501-001",
  "recipient_name": "Jane Smith",
  "recipient_country": "SG",
  "recipient_phone": "6591234567",
  "recipient_address": "123 Orchard Road",
  "recipient_city": "Singapore",
  "recipient_email": "jane@example.com",
  "postal_code": "238858",
  "sender_country": "SG",
  "client_size": "30,20,10",
  "client_weight": 1.5,
  "declared_value": 99.99,
  "declared_value_currency": "SGD",
  "item": [
    {
      "description": "Electronics",
      "itemHSCode": "8471300000",
      "quantity": 1,
      "unitPrice": 99.99,
      "weight": 1.5,
      "currency": "SGD",
      "totalValue": 99.99
    }
  ]
}

Token 生成说明

token 只由凭证和 seed 计算得出 —— 请求参数不参与。

seed  = "1746700000000"   （13 位毫秒时间戳）
token = md5( strtolower(api_name) + api_key + seed )

认证

本接口使用标准 OpenAPI 认证（MD5 token）。

完整的认证说明与多语言示例见认证与签名。

响应信息

响应为 JSON 格式。

响应结构

字段	类型	说明
code	integer	结果码。`0` = 成功，`1` = 失败
message	string	结果描述
data	object	下单结果

成功响应

HTTP 状态码：200

json

{
  "code": 0,
  "message": "success",
  "data": {
    "custom_tracking_num": "C240719112805334a634B",
    "wmg_tracking_num": "WGC000000000233",
    "date_time": "2024-07-19T13:34:26+08:00",
    "status": "",
    "error": []
  }
}

字段	类型	说明
data.custom_tracking_num	string	回显你传入的内部订单号
data.wmg_tracking_num	string	WMG 分配的运单号
data.date_time	string	下单时间（ISO 8601，UTC+8）
data.status	string	下单状态
data.error	array	单条错误信息，无错误时为空数组

失败响应

HTTP 状态码：200（业务错误）或 4xx/5xx（系统错误）

json

{
  "code": 1,
  "message": "Client Size invalid",
  "data": []
}

常见错误：

认证失败 → code 1；具体 message 取决于失败原因（如 x-auth-token: INVALID、x-auth-seed: TIMEOUT）—— 见认证与签名
字段缺失或不合法 → code 1，返回字段校验消息（如 client_weight require、recipient_country invalid）
内部单号重复 → code 1，message 为 custom_tracking_num (XXX) already exist（注意 exist 没有 s）
服务代码无效 → code 1，message 为 Service code invalid（US）或 Service code (XXX) invalid（SG）
目的国不支持 → code 1，message 为 recipient_country(XX) not allow
商品明细校验失败 → code 1，message 为 Item <row> <field> <reason>（如 Item 1 unitPrice require）

结果码

Code	说明
0	成功
1	失败

调用示例

Bash

bash

API_NAME="your_api_name"
API_KEY="your_api_key"
SEED=$(date +%s%3N)
TOKEN=$(printf '%s' "$(echo -n "$API_NAME" | tr '[:upper:]' '[:lower:]')${API_KEY}${SEED}" | md5sum | cut -d' ' -f1)

curl -X POST "https://api.test.wmgdelivery.com/v1/openapi/order/create-order" \
  -H "Content-Type: application/json" \
  -H "x-auth-name: $API_NAME" \
  -H "x-auth-seed: $SEED" \
  -H "x-auth-token: $TOKEN" \
  -d '{
    "custom_tracking_num": "ORDER-20260501-001",
    "recipient_name": "Jane Smith",
    "recipient_country": "SG",
    "recipient_phone": "6591234567",
    "recipient_address": "123 Orchard Road",
    "recipient_city": "Singapore",
    "recipient_email": "jane@example.com",
    "postal_code": "238858",
    "sender_country": "SG",
    "client_size": "30,20,10",
    "client_weight": 1.5,
    "declared_value": 99.99,
    "declared_value_currency": "SGD",
    "item": [{"description": "Electronics", "itemHSCode": "8471300000", "quantity": 1, "unitPrice": 99.99, "weight": 1.5, "currency": "SGD", "totalValue": 99.99}]
  }'

Windows PowerShell

powershell

$API_NAME = "your_api_name"
$API_KEY  = "your_api_key"
$SEED     = [string]([DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds())

$raw   = [System.Text.Encoding]::UTF8.GetBytes($API_NAME.ToLower() + $API_KEY + $SEED)
$md5   = [System.Security.Cryptography.MD5]::Create().ComputeHash($raw)
$TOKEN = -join ($md5 | ForEach-Object { $_.ToString("x2") })

$body = [ordered]@{
    custom_tracking_num     = "ORDER-20260501-001"
    recipient_name          = "Jane Smith"
    recipient_country       = "SG"
    recipient_phone         = "6591234567"
    recipient_address       = "123 Orchard Road"
    recipient_city          = "Singapore"
    recipient_email         = "jane@example.com"
    postal_code             = "238858"
    sender_country          = "SG"
    client_size             = "30,20,10"
    client_weight           = 1.5
    declared_value          = 99.99
    declared_value_currency = "SGD"
    item                    = @(@{ description = "Electronics"; itemHSCode = "8471300000"; quantity = 1; unitPrice = 99.99; weight = 1.5; currency = "SGD"; totalValue = 99.99 })
} | ConvertTo-Json -Depth 5 -Compress

$headers = @{
    "Content-Type" = "application/json"
    "x-auth-name"  = $API_NAME
    "x-auth-seed"  = $SEED
    "x-auth-token" = $TOKEN
}

$response = Invoke-RestMethod `
    -Uri "https://api.test.wmgdelivery.com/v1/openapi/order/create-order" `
    -Method Post -Headers $headers -Body $body
$response | ConvertTo-Json -Depth 10

Python

python

import hashlib, time
import requests

API_NAME = 'your_api_name'
API_KEY  = 'your_api_key'
SEED     = str(int(time.time() * 1000))
TOKEN    = hashlib.md5((API_NAME.lower() + API_KEY + SEED).encode()).hexdigest()

headers = {
    'Content-Type': 'application/json',
    'x-auth-name':  API_NAME,
    'x-auth-seed':  SEED,
    'x-auth-token': TOKEN,
}

body = {
    'custom_tracking_num':     'ORDER-20260501-001',
    'recipient_name':          'Jane Smith',
    'recipient_country':       'SG',
    'recipient_phone':         '6591234567',
    'recipient_address':       '123 Orchard Road',
    'recipient_city':          'Singapore',
    'recipient_email':         'jane@example.com',
    'postal_code':             '238858',
    'sender_country':          'SG',
    'client_size':             '30,20,10',
    'client_weight':           1.5,
    'declared_value':          99.99,
    'declared_value_currency': 'SGD',
    'item': [{'description': 'Electronics', 'itemHSCode': '8471300000', 'quantity': 1, 'unitPrice': 99.99, 'weight': 1.5, 'currency': 'SGD', 'totalValue': 99.99}],
}

resp = requests.post('https://api.test.wmgdelivery.com/v1/openapi/order/create-order', json=body, headers=headers)
print(resp.json())

Node.js / TypeScript

typescript

import crypto from 'node:crypto';

const API_NAME = 'your_api_name';
const API_KEY  = 'your_api_key';
const SEED     = String(Date.now());
const TOKEN    = crypto.createHash('md5').update(API_NAME.toLowerCase() + API_KEY + SEED).digest('hex');

const body = JSON.stringify({
    custom_tracking_num:     'ORDER-20260501-001',
    recipient_name:          'Jane Smith',
    recipient_country:       'SG',
    recipient_phone:         '6591234567',
    recipient_address:       '123 Orchard Road',
    recipient_city:          'Singapore',
    recipient_email:         'jane@example.com',
    postal_code:             '238858',
    sender_country:          'SG',
    client_size:             '30,20,10',
    client_weight:           1.5,
    declared_value:          99.99,
    declared_value_currency: 'SGD',
    item: [{ description: 'Electronics', itemHSCode: '8471300000', quantity: 1, unitPrice: 99.99, weight: 1.5, currency: 'SGD', totalValue: 99.99 }],
});

const resp = await fetch('https://api.test.wmgdelivery.com/v1/openapi/order/create-order', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-auth-name':  API_NAME,
        'x-auth-seed':  SEED,
        'x-auth-token': TOKEN,
    },
    body,
});
console.log(JSON.stringify(await resp.json(), null, 2));

PHP

php

<?php
$API_NAME = 'your_api_name';
$API_KEY  = 'your_api_key';
$SEED     = (string)(time() * 1000);
$TOKEN    = md5(strtolower($API_NAME) . $API_KEY . $SEED);

$body = [
    'custom_tracking_num'     => 'ORDER-20260501-001',
    'recipient_name'          => 'Jane Smith',
    'recipient_country'       => 'SG',
    'recipient_phone'         => '6591234567',
    'recipient_address'       => '123 Orchard Road',
    'recipient_city'          => 'Singapore',
    'recipient_email'         => 'jane@example.com',
    'postal_code'             => '238858',
    'sender_country'          => 'SG',
    'client_size'             => '30,20,10',
    'client_weight'           => 1.5,
    'declared_value'          => 99.99,
    'declared_value_currency' => 'SGD',
    'item'                    => [
        ['description' => 'Electronics', 'itemHSCode' => '8471300000', 'quantity' => 1, 'unitPrice' => 99.99, 'weight' => 1.5, 'currency' => 'SGD', 'totalValue' => 99.99],
    ],
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.test.wmgdelivery.com/v1/openapi/order/create-order');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-auth-name: '  . $API_NAME,
    'x-auth-seed: '  . $SEED,
    'x-auth-token: ' . $TOKEN,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
$response = curl_exec($ch);
curl_close($ch);
echo json_encode(json_decode($response, true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n";
?>

注意事项

custom_tracking_num 在同一客户下必须唯一，重复会被拒绝。
client_size 三个数字的顺序系统会自动从大到小重排。
认证 token 不包含请求参数，只用凭证和 seed 计算。
x-auth-seed 必须是 13 位毫秒级 UNIX 时间戳，且与服务器时间相差不超过 ±10 分钟。
所有参数区分大小写。

错误码

code	message	说明
`1`	认证错误消息	认证失败；具体 message 取决于失败原因 —— 完整清单见认证与签名
`1`	`custom_tracking_num (XXX) already exist`	该内部单号在当前客户下已存在。注意 `exist` 没有结尾的 `s`
`1`	`Service code invalid`	`recipient_country = US` 且 `service_code` 未传或不是可识别的代码
`1`	`Service code (XXX) invalid`	`recipient_country = SG` 且传入的 `service_code` 不是可识别的代码
`1`	`recipient_country(XX) not allow`	该收件国代码不在平台允许的国家清单内
`1`	`Item <row> <field> <reason>`	`item[]` 中某一项校验失败，`<row>` 为行号、`<field>` 为字段名
`1`	字段校验消息	其他字段级校验失败（必填、长度、格式、枚举）

创建订单 ​

接口说明 ​

请求信息 ​

请求头 ​

请求参数 ​

请求体示例 ​

Token 生成说明 ​

认证 ​

响应信息 ​

响应结构 ​

成功响应 ​

失败响应 ​

结果码 ​

调用示例 ​

Bash ​

Windows PowerShell ​

Python ​

Node.js / TypeScript ​

PHP ​

注意事项 ​

错误码 ​

创建订单

接口说明

请求信息

请求头

请求参数

请求体示例

Token 生成说明

认证

响应信息

响应结构

成功响应

失败响应

结果码

调用示例

Bash

Windows PowerShell

Python

Node.js / TypeScript

PHP

注意事项

错误码