查询单个包裹状态

接口概述

按 WMG 运单号返回单个包裹的当前状态和完整轨迹历史。适用于单个包裹的轨迹页面；需要一次轮询多个包裹时请使用 查询多个包裹状态。

请求信息

• Method: GET
• Path: /api/status/track
• Authentication: Bearer Token

请求头

字段	说明
Authorization	Bearer <token>

请求参数

请求包含以下查询参数：

参数	类型	必填	说明
ID	string	是	包裹的 WMG 运单号。长度 8～50 个字符。

认证方式

本接口使用 Bearer Token 认证。

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

响应信息

响应为 JSON 格式。

响应格式

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

成功响应

• Status Code: 200

{
  "Code": 0,
  "Message": "Success",
  "Data": {
    "TrackingNumber": "C240129142515376136497",
    "LastStatus": "DR_DR",
    "LastStatusDateTime": "2024-01-29T14:27:09+08:00",
    "Activities": [
      {
        "StatusDateTime": "2024-01-29T14:27:09+08:00",
        "StatusCode": "DR_DR",
        "StatusDesc": "Data Received via API",
        "Remarks": "",
        "ReceiveBy": ""
      }
    ]
  }
}

字段	类型	说明
Data.TrackingNumber	string	本次查询的 WMG 运单号。
Data.LastStatus	string	最新一条轨迹的状态码。包裹尚无可对外发布的状态时为空。
Data.LastStatusDateTime	string	最新一条轨迹的时间，ISO 8601 格式并带时区偏移（+08:00）。
Data.Activities	array	轨迹历史，按时间倒序（最新在前）。
Data.Activities[].StatusDateTime	string	该条轨迹的时间，ISO 8601 格式并带时区偏移（+08:00）。
Data.Activities[].StatusCode	string	状态码——见 Delivery Status。
Data.Activities[].StatusDesc	string	状态码对应的描述文本。
Data.Activities[].Remarks	string	该条轨迹的补充备注；没有时为空字符串。
Data.Activities[].ReceiveBy	string	预留字段，始终返回空字符串。

错误响应

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

{
  "Code": 1,
  "Message": "Fail",
  "Data": {
    "TrackingNumber": "C240129142515376136497a",
    "Remarks": "No Record(s)"
  }
}

字段	类型	说明
Data.TrackingNumber	string	本次查询的运单号。
Data.Remarks	string	查询失败的原因。

结果码

Code	说明
0	成功
1	失败

示例

Bash

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

curl -G "$BASE_URL/api/status/track" \
  --data-urlencode "ID=C240129142515376136497" \
  -H "Authorization: Bearer $TOKEN"

Windows PowerShell

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

$response = Invoke-RestMethod -Uri "$BASE_URL/api/status/track?ID=$ID" -Method Get `
    -Headers @{Authorization = "Bearer $TOKEN"}
$response | ConvertTo-Json -Depth 10

Python

import requests

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

resp = requests.get(f"{BASE_URL}/api/status/track",
                    params={"ID": "C240129142515376136497"},
                    headers={"Authorization": f"Bearer {TOKEN}"}, timeout=10)
print(resp.json())

Node.js / TypeScript

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

const url = new URL(`${BASE_URL}/api/status/track`);
url.searchParams.set("ID", "C240129142515376136497");

const res = await fetch(url, {headers: {"Authorization": `Bearer ${TOKEN}`}});
console.log(await res.json());

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/status/track?' . http_build_query([
    'ID' => 'C240129142515376136497',
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $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";
?>

注意事项

• 所有时间均为新加坡时间（UTC+08:00），以带偏移量的 ISO 8601 格式返回。
• Activities 按最新在前排序，LastStatus / LastStatusDateTime 始终等于其第一条。
• 请按 StatusCode 做业务分支，不要按 StatusDesc 做字符串匹配。描述文本会随承运商和账号配置变化，而状态码是稳定的。
• 仅内部使用的状态记录会被过滤掉，因此 Activities 可能短于包裹的完整内部历史——刚创建的包裹也可能合法地返回空的 Activities 和空的 LastStatus。
• 你的账号下不存在该包裹时不是 HTTP 错误：接口返回 Code: 1、Message: "Fail"，Data.Remarks 为 No Record(s)。注意此时 Data 是对象，不是其他接口失败时返回的空数组。
• ID 必须是 WMG 运单号，且按原样精确匹配——不会转为大写，请完全按签发时的形式发送。
• 只能查询到属于当前认证账号的包裹。

错误码

code	message	说明
1	Fail	你的账号下没有与 ID 匹配的包裹，Data.Remarks 为 No Record(s)。
1	ID require	ID 缺失或为空。
1	min size of ID must be 8	ID 少于 8 个字符。
1	max size of ID must be 50	ID 超过 50 个字符。
1	Error encountered, please contact tech@wmg-group.com with screenshot of error page for resolution.	未预期的服务端错误。
1003	Token error	Token 缺失、已过期或被新登录顶替。请重新调用 获取 Token。