批量查询包裹状态

接口说明

一次提交多个 WMG 单号查询状态。查得到的进 success，查不到的进 errors。

请求信息

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

请求头

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

请求参数

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

参数	类型	必填	说明
tracking_nums	array	是	WMG 单号数组

NOTE

所有时间统一为 UTC+8（新加坡时间）

请求体示例

json

{
  "tracking_nums": ["WMG1234567", "WMG7654321", "WMG9999999"]
}

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	查询结果，分为 `success` 与 `errors` 两部分

成功响应

HTTP 状态码：200

json

{
  "code": 0,
  "message": "success",
  "data": {
    "success": [
      {
        "tracking_number": "CW900000019VN",
        "last_status": "FD_BA",
        "last_status_date_time": "2025-01-10T13:52:59+08:00",
        "activities": [
          {
            "status_date_time": "2025-01-10T13:52:59+08:00",
            "status_code": "FD_BA",
            "status_desc": "Parcel has a bad recipient address",
            "remarks": "",
            "receive_by": "",
            "pod": [
              "https://xxxxxx/pod/08d34130-5178-471f-8c91-dc63087d90ff",
              "https://xxxxxxx/pod/5d0d5d54-74bc-40bf-99fc-356a302482b8"
            ],
            "location": "VN"
          },
          {
            "status_date_time": "2025-01-08T16:01:51+08:00",
            "status_code": "DR_DR",
            "status_desc": "Data Received via API",
            "remarks": "",
            "receive_by": "",
            "pod": [],
            "location": "VN"
          }
        ],
        "partner_tracking_no": "",
        "partner_name": ""
      }
    ],
    "errors": [
      {
        "tracking_number": "240304101132555047718",
        "remarks": "No Record(s)"
      },
      {
        "tracking_number": "C240719112805AF011",
        "remarks": "No Record(s)"
      },
      {
        "tracking_number": "WGC000000000051",
        "remarks": "No Record(s)"
      }
    ]
  }
}

字段	类型	说明
data.success	array	查询成功的包裹列表，单条结构与单个查询的 `data` 相同
data.errors	array	查询失败的单号列表
data.errors[].tracking_number	string	传入的单号
data.errors[].remarks	string	失败原因，如 `No Record(s)`

失败响应

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

json

{
  "code": 1,
  "message": "x-auth-token: INVALID",
  "data": []
}

常见错误：

认证失败 → code 1；具体 message 取决于失败原因（如 x-auth-token: INVALID、x-auth-seed: TIMEOUT）—— 见认证与签名

tracking_nums 必须以数组形式传递。传空数组会返回 code: 0，success 与 errors 均为空数组；完全不传该字段、或传字符串而非数组，会返回通用系统错误（code: 1，message 为 something error）—— 本接口不做逐字段检查，因此不会给出更具体的提示。

结果码

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/query-multi-status" \
  -H "Content-Type: application/json" \
  -H "x-auth-name: $API_NAME" \
  -H "x-auth-seed: $SEED" \
  -H "x-auth-token: $TOKEN" \
  -d '{"tracking_nums": ["WMG1234567", "WMG7654321", "WMG9999999"]}'

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 = @{
    tracking_nums = @("WMG1234567", "WMG7654321", "WMG9999999")
} | ConvertTo-Json -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/query-multi-status" `
    -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 = {
    'tracking_nums': ['WMG1234567', 'WMG7654321', 'WMG9999999'],
}

resp = requests.post('https://api.test.wmgdelivery.com/v1/openapi/order/query-multi-status', 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({
    tracking_nums: ['WMG1234567', 'WMG7654321', 'WMG9999999'],
});

const resp = await fetch('https://api.test.wmgdelivery.com/v1/openapi/order/query-multi-status', {
    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 = [
    'tracking_nums' => ['WMG1234567', 'WMG7654321', 'WMG9999999'],
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.test.wmgdelivery.com/v1/openapi/order/query-multi-status');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_UNICODE));
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";
?>

注意事项

只要请求本身合法，code 就是 0，即使全部单号都查不到。请逐条检查 data.success 与 data.errors。
认证 token 不包含请求参数，只用凭证和 seed 计算。
x-auth-seed 必须是 13 位毫秒级 UNIX 时间戳，且与服务器时间相差不超过 ±10 分钟。
所有参数区分大小写。

错误码

code	message	说明
`1`	认证错误消息	认证失败；具体 message 取决于失败原因 —— 完整清单见认证与签名

批量查询包裹状态 ​

接口说明 ​

请求信息 ​

请求头 ​

请求参数 ​

请求体示例 ​

Token 生成说明 ​

认证 ​

响应信息 ​

响应结构 ​

成功响应 ​

失败响应 ​

结果码 ​

调用示例 ​

Bash ​

Windows PowerShell ​

Python ​

Node.js / TypeScript ​

PHP ​

注意事项 ​

错误码 ​

批量查询包裹状态

接口说明

请求信息

请求头

请求参数

请求体示例

Token 生成说明

认证

响应信息

响应结构

成功响应

失败响应

结果码

调用示例

Bash

Windows PowerShell

Python

Node.js / TypeScript

PHP

注意事项

错误码