WMG CONNECT API DOCS

中文

English

中文

English

主题

查询单个包裹状态 ​

接口说明 ​

按 WMG 单号查询单个包裹的状态轨迹，返回最新状态与完整的状态记录。

请求信息 ​

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

请求头 ​

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

请求参数 ​

参数类型必填说明
tracking_numstring是WMG 包裹单号

NOTE

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

Token 生成说明 ​

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

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

认证 ​

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

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

响应信息 ​

响应为 JSON 格式。

响应结构 ​

字段类型说明
codeinteger结果码。0 = 成功，1 = 失败
messagestring结果描述
dataobject状态数据

成功响应 ​

  • HTTP 状态码：200
json
{
  "code": 0,
  "message": "success",
  "data": {
    "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://xxxxxxx/pod/08d34130-5178-471f-8c91-dc63087d90ff",
          "https://xxxxxx/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": ""
  }
}
字段类型说明
data.tracking_numberstringWMG 包裹单号
data.last_statusstring最新状态码
data.last_status_date_timestring最新状态发生时间（ISO 8601，UTC+8）
data.activitiesarray状态轨迹列表
data.activities[].status_date_timestring该状态发生时间
data.activities[].status_codestring状态码，取值见物流状态码
data.activities[].status_descstring状态英文描述（接口返回原文）
data.activities[].remarksstring备注
data.activities[].receive_bystring签收人
data.activities[].podarray签收凭证图片地址列表，无则为空数组
data.activities[].locationstring状态发生地
data.partner_tracking_nostring承运商自有单号，无则为空字符串
data.partner_namestring承运商名称，无则为空字符串

当前客户下查不到该单号时，返回 code: 1，且 data 中带回单号与 remarks 字段：

json
{
    "code": 1,
    "message": "fail",
    "data": {
        "tracking_number": "240304101132642048443a",
        "remarks": "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）—— 见认证与签名
  • 单号查不到 → code 1，message 为 fail，且 data.remarks 为 No Record(s)

结果码 ​

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 -G "https://api.test.wmgdelivery.com/v1/openapi/order/query-status" \
  --data-urlencode "tracking_num=WMG1234567" \
  -H "x-auth-name: $API_NAME" \
  -H "x-auth-seed: $SEED" \
  -H "x-auth-token: $TOKEN"

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") })

$headers = @{
    "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-status?tracking_num=WMG1234567" `
    -Method Get -Headers $headers
$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 = {
    'x-auth-name':  API_NAME,
    'x-auth-seed':  SEED,
    'x-auth-token': TOKEN,
}

resp = requests.get(
    'https://api.test.wmgdelivery.com/v1/openapi/order/query-status',
    params={'tracking_num': 'WMG1234567'},
    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 url = new URL('https://api.test.wmgdelivery.com/v1/openapi/order/query-status');
url.searchParams.set('tracking_num', 'WMG1234567');

const resp = await fetch(url.toString(), {
    headers: {
        'x-auth-name':  API_NAME,
        'x-auth-seed':  SEED,
        'x-auth-token': TOKEN,
    },
});
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);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.test.wmgdelivery.com/v1/openapi/order/query-status?' . http_build_query(['tracking_num' => 'WMG1234567']));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-auth-name: '  . $API_NAME,
    'x-auth-seed: '  . $SEED,
    'x-auth-token: ' . $TOKEN,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
$response = curl_exec($ch);
curl_close($ch);
echo json_encode(json_decode($response, true), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n";
?>

注意事项 ​

  • 查不到单号时返回的是 code: 1，且 data 中带回传入的单号与原因，而不是空数据。
  • status_desc 为接口返回的英文原文，程序请按 status_code 分支。
  • 认证 token 不包含请求参数，只用凭证和 seed 计算。
  • x-auth-seed 必须是 13 位毫秒级 UNIX 时间戳，且与服务器时间相差不超过 ±10 分钟。
  • 所有参数区分大小写。

错误码 ​

codemessage说明
1认证错误消息认证失败；具体 message 取决于失败原因 —— 完整清单见认证与签名
1fail（data.remarks 为 No Record(s)）当前客户下查不到该单号