创建并关闭订单

接口概述

用已登记的包裹创建一张运输订单（CN38），把包裹分装进袋 / AKE / 托盘，并在同一次调用中关闭该订单。关闭会触发运输单据的生成，之后用获取订单文件取回。

本接口引用的每个包裹都必须已存在、属于你的账号，且尚未被其他订单占用。

请求信息

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

请求头

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

请求参数

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

参数	类型	必填	说明
ship_type	integer	是	装载类型：`1` = 袋（Bag），`2` = AKE，`3` = 托盘（Pallet）。
ship_route	integer	是	运输路线：`1` = Direct CN，`2` = Master2CN，`3` = Master2CN(T2T)，`4` = Master2CN(OA)，`5` = Transshipment CN，`6` = Transshipment CN(AF)，`7` = Transshipment CN(VP)。
is_ddp	string	否	清关模式：`Y` = DDP，`N` = DDU。默认 `N`。必须与订单内每个包裹的清关模式一致。
destination	string	是	目的国家，2 位国家代码，如 `SG` 表示新加坡、`TH` 表示泰国。必须正好 2 个字符。
departure_port	string	是	起运港代码。必须正好 3 个字符。
destination_port	string	是	目的港代码。必须正好 3 个字符。
outbound_flight_no	string	是	出港航班号。最长 60 个字符。
estimated_departure_datetime	string	是	起运地预计出发当地时间，10 位 UNIX 秒级时间戳。
estimated_arrival_datetime	string	是	目的地预计到达当地时间，10 位 UNIX 秒级时间戳。必须晚于 `estimated_departure_datetime`。
shipment_service	string	条件必填	当目的地有可选服务时必填：`TP` = Tracked Packet，`EM` = EMS。目的地没有可选服务时该字段被忽略。
ship_type_details	array	是	装载单元数组。每个元素是该袋 / AKE / 托盘内所装 WMG 运单号的数组，且不能为空。
order_mawb	object	条件必填	MAWB 信息。当 `ship_route` 为 `2`、`3`、`4` 时必填。
order_mawb.mawb_no	string	条件必填	MAWB 号。最长 60 个字符。
order_mawb.departure_airport	string	条件必填	出发机场代码。必须正好 3 个字符。
order_mawb.arrival_airport	string	条件必填	到达机场代码。必须正好 3 个字符。
order_mawb.outbound_flight_no	string	条件必填	MAWB 上的航班号。最长 60 个字符。
order_mawb.estimated_departure_datetime	string	条件必填	预计出发时间，10 位 UNIX 秒级时间戳。
order_mawb.estimated_arrival_datetime	string	条件必填	预计到达时间，10 位 UNIX 秒级时间戳。必须晚于 `order_mawb.estimated_departure_datetime`。

请求体示例

Direct CN 路线——无需 MAWB，两个装载单元：

json

{
  "ship_type": 1,
  "ship_route": 1,
  "is_ddp": "N",
  "departure_port": "SIN",
  "destination_port": "PHS",
  "outbound_flight_no": "SQ918",
  "estimated_departure_datetime": "1784115300",
  "estimated_arrival_datetime": "1784128800",
  "destination": "PH",
  "shipment_service": "TP",
  "ship_type_details": [
    [
      "TES00123456TP",
      "TES00123457TP"
    ],
    [
      "TES00123458TP"
    ]
  ]
}

Master2CN 路线——order_mawb 必填：

json

{
  "ship_type": 3,
  "ship_route": 2,
  "is_ddp": "Y",
  "departure_port": "SIN",
  "destination_port": "TPE",
  "outbound_flight_no": "SQ876",
  "estimated_departure_datetime": "1784115300",
  "estimated_arrival_datetime": "1784128800",
  "destination": "TW",
  "order_mawb": {
    "mawb_no": "12123224",
    "departure_airport": "SIN",
    "arrival_airport": "TPE",
    "outbound_flight_no": "SQ876",
    "estimated_departure_datetime": "1784115300",
    "estimated_arrival_datetime": "1784128800"
  },
  "ship_type_details": [
    [
      "BX000000014CG",
      "BX000000028CG"
    ]
  ]
}

认证方式

本接口使用 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": {
        "JobNo": "CN38SG24010001"
    }
}

字段	类型	说明
Data.JobNo	string	新建订单的 Job No。在获取订单文件中作为 `job_no` 使用。

错误响应

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

json

{
    "Code": 1,
    "Message": "WMG Tracking Num(TES00123456TP) not exists!",
    "Data": []
}

结果码

Code	说明
0	成功
1	失败

示例

Bash

bash

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

curl -X POST "$BASE_URL/api/order/create-order" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "ship_type": 1,
    "ship_route": 1,
    "is_ddp": "N",
    "departure_port": "SIN",
    "destination_port": "PHS",
    "outbound_flight_no": "SQ918",
    "estimated_departure_datetime": "1784115300",
    "estimated_arrival_datetime": "1784128800",
    "destination": "PH",
    "shipment_service": "TP",
    "ship_type_details": [["TES00123456TP", "TES00123457TP"]]
  }'

Windows PowerShell

powershell

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

# @(, @(...)) 保证内层数组不被展平——只有一个内层数组时会被拉平
$body = @{
    ship_type                    = 1
    ship_route                   = 1
    is_ddp                       = "N"
    departure_port               = "SIN"
    destination_port             = "PHS"
    outbound_flight_no           = "SQ918"
    estimated_departure_datetime = "1784115300"
    estimated_arrival_datetime   = "1784128800"
    destination                  = "PH"
    shipment_service             = "TP"
    ship_type_details            = @(, @("TES00123456TP", "TES00123457TP"))
} | ConvertTo-Json -Depth 5

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

Python

python

import requests

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

resp = requests.post(f"{BASE_URL}/api/order/create-order", json={
    "ship_type": 1,
    "ship_route": 1,
    "is_ddp": "N",
    "departure_port": "SIN",
    "destination_port": "PHS",
    "outbound_flight_no": "SQ918",
    "estimated_departure_datetime": "1784115300",
    "estimated_arrival_datetime": "1784128800",
    "destination": "PH",
    "shipment_service": "TP",
    # 外层数组是装载单元，内层数组是该单元内的包裹
    "ship_type_details": [["TES00123456TP", "TES00123457TP"]],
}, headers={"Authorization": f"Bearer {TOKEN}"}, timeout=60)
print(resp.json())

Node.js / TypeScript

typescript

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

const res = await fetch(`${BASE_URL}/api/order/create-order`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    ship_type: 1,
    ship_route: 1,
    is_ddp: "N",
    departure_port: "SIN",
    destination_port: "PHS",
    outbound_flight_no: "SQ918",
    estimated_departure_datetime: "1784115300",
    estimated_arrival_datetime: "1784128800",
    destination: "PH",
    shipment_service: "TP",
    // 外层数组是装载单元，内层数组是该单元内的包裹
    ship_type_details: [["TES00123456TP", "TES00123457TP"]],
  }),
});
console.log(await res.json());

PHP

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/order/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([
    'ship_type'                    => 1,
    'ship_route'                   => 1,
    'is_ddp'                       => 'N',
    'departure_port'               => 'SIN',
    'destination_port'             => 'PHS',
    'outbound_flight_no'           => 'SQ918',
    'estimated_departure_datetime' => '1784115300',
    'estimated_arrival_datetime'   => '1784128800',
    'destination'                  => 'PH',
    'shipment_service'             => 'TP',
    // 外层数组是装载单元，内层数组是该单元内的包裹
    'ship_type_details'            => [['TES00123456TP', 'TES00123457TP']],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
$response = curl_exec($ch);
curl_close($ch);

echo json_encode(json_decode($response, true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n";
?>

注意事项

本接口在一次调用中同时创建并关闭订单。 没有单独的关闭步骤，且订单关闭后无法通过 API 修改——发送前请核对好数据。
运输单据不是立即生成的。请用获取订单文件取回，该接口会短暂等待生成完成。
ship_type_details 是数组的数组：外层是装载单元列表，每个内层数组是该单元内所装的 WMG 运单号。内层数组不能为空。
单个订单最多包含 999 个包裹（所有装载单元合计）。
同一个运单号不能在 ship_type_details 中出现两次，跨装载单元也不行。
每个包裹必须同时满足以下条件，否则整个请求被拒绝：
- 包裹存在且属于你的账号；
- 尚未被其他订单占用——重复使用的包裹会返回 "scanned before in previous shipments" 那条消息，需要重新出 CN23 面单；
- 清关模式与订单的 is_ddp 一致；
- 目的地与订单的 destination 一致——但 Transshipment CN 和 Transshipment CN(AF) 两条路线会跳过这项检查；
- 承运商与订单的承运商一致；
- 尺寸类型与订单的装载尺寸一致；
- 长宽高和重量在该服务与目的地的限制范围内。
order_mawb 只在 Master2CN 系列路线（ship_route 为 2、3、4）下必填，其他路线可传但不强制。
时间戳为 10 位 UNIX 秒级；示例中以字符串形式发送，与现有接入方的用法一致。
本接口会完成订单构建、单据触发和关闭，比普通查询慢，客户端超时时间请设置得宽松一些。
所有参数区分大小写。

错误码

code	message	说明
`1`	ship_type require	`ship_type` 缺失或为空。
`1`	ship_type invalid	`ship_type` 不是 `1`、`2`、`3`。
`1`	ship_route require	`ship_route` 缺失或为空。
`1`	Ship Route Invalid	`ship_route` 不在 `1`～`7` 范围内。
`1`	is_ddp must be in Y,N	`is_ddp` 既不是 `Y` 也不是 `N`。
`1`	destination require	`destination` 缺失或为空。
`1`	size of destination must be 2	`destination` 不是正好 2 个字符。
`1`	departure_port require	`departure_port` 缺失或为空。
`1`	size of departure_port must be 3	`departure_port` 不是正好 3 个字符。
`1`	destination_port require	`destination_port` 缺失或为空。
`1`	size of destination_port must be 3	`destination_port` 不是正好 3 个字符。
`1`	outbound_flight_no require	`outbound_flight_no` 缺失或为空。
`1`	max size of outbound_flight_no must be 60	`outbound_flight_no` 超过 60 个字符。
`1`	estimated_departure_datetime require	`estimated_departure_datetime` 缺失或为空。
`1`	estimated_departure_datetime must be a timestamp	`estimated_departure_datetime` 不是合法的 UNIX 时间戳。
`1`	estimated_arrival_datetime require	`estimated_arrival_datetime` 缺失或为空。
`1`	estimated_arrival_datetime must be a timestamp	`estimated_arrival_datetime` 不是合法的 UNIX 时间戳。
`1`	estimated_arrival_datetime must be greater than 'estimated_departure_datetime'	到达时间不晚于出发时间。
`1`	shipment_service must be TP or EM	目的地有可选服务，但 `shipment_service` 既不是 `TP` 也不是 `EM`。
`1`	ship_type_details require	`ship_type_details` 缺失或为空。
`1`	ship_type_details must be a array	`ship_type_details` 不是数组。
`1`	ship_type_details must contain non-empty bags	`ship_type_details` 中有装载单元为空或不是数组。
`1`	bags require	`ship_type_details` 解析后没有任何装载单元。
`1`	bag item(1) must be array	该位置的装载单元不是数组，括号内是从 1 开始的单元序号。
`1`	bag item parcel(1) must be string	装载单元内该位置的元素不是字符串，括号内是从 1 开始的元素序号。
`1`	WMG Tracking Num(TES00123456TP) Duplicate!	同一个运单号在所有装载单元中出现了多次。
`1`	The number of items cannot exceed 999	单个订单包裹数超过 999。
`1`	WMG Tracking Num(TES00123456TP) not exists!	你的账号下没有该包裹。
`1`	Order clearance mode(DDP) is inconsistent with the parcel((TES00123456TP)) clearance mode(DDU)	包裹的清关模式与订单的 `is_ddp` 不一致。
`1`	Parcel(TES00123456TP) destination(TH) is inconsistent with order destination(PH)	包裹目的地与订单 `destination` 不一致。
`1`	Parcel(TES00123456TP) partner is inconsistent with order partner	包裹承运商与订单承运商不一致。
`1`	(TES00123456TP) The package size does not match the size set in the order	包裹尺寸类型与订单装载尺寸不一致。
`1`	（TES00123456TP）This parcel has been scanned before in previous shipments. Please generate a new CN23 label for this parcel and redo bagging scan.	该包裹已属于其他订单。请重新生成 CN23 面单并重新装袋扫描。
`1`	Parcel(TES00123456TP):	包裹超出该服务与目的地的尺寸、长度或重量限制。冒号后的文本说明是哪一项限制。
`1`	Error encountered, please contact tech@wmg-group.com with screenshot of error page for resolution.	未预期的服务端错误。
`1003`	Token error	Token 缺失、已过期或被新登录顶替。请重新调用获取 Token。

订单构建和承运商匹配失败会带着各自的消息文本返回 Code: 1。凡是无法识别的 Message，都应视为整个订单被拒绝——调用失败时不会创建任何数据。

创建并关闭订单 ​

接口概述 ​

请求信息 ​

请求头 ​

请求参数 ​

请求体示例 ​

认证方式 ​

响应信息 ​

响应格式 ​

成功响应 ​

错误响应 ​

结果码 ​

示例 ​

Bash ​

Windows PowerShell ​

Python ​

Node.js / TypeScript ​

PHP ​

注意事项 ​

错误码 ​

创建并关闭订单

接口概述

请求信息

请求头

请求参数

请求体示例

认证方式

响应信息

响应格式

成功响应

错误响应

结果码

示例

Bash

Windows PowerShell

Python

Node.js / TypeScript

PHP

注意事项

错误码