查询多个包裹状态

接口概述

一次调用返回一批包裹的当前状态和轨迹历史。每个运单号独立解析：查到的放在 Data.Success，查不到的放在 Data.Errors。

请求信息

• Method: POST
• Path: /api/status/lookup
• Authentication: Bearer Token

请求头

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

请求参数

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

参数	类型	必填	说明
TrackingNumber	array	是	待查询的 WMG 运单号数组。即使只查一个也必须是 JSON 数组。

请求体示例

{
    "TrackingNumber": [
        "C240129142515839830635",
        "C240126144626997791271"
    ]
}

认证方式

本接口使用 Bearer Token 认证。

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

响应信息

响应为 JSON 格式。

响应格式

字段	类型	说明
Code	integer	0 表示成功；非 0 表示失败
Message	string	可读的结果说明
Data	object	按运单号逐条给出的结果

成功响应

• Status Code: 200

{
  "Code": 0,
  "Message": "Success",
  "Data": {
    "Success": [
      {
        "TrackingNumber": "C240129142515839830635",
        "LastStatus": "DR_DR",
        "LastStatusDateTime": "2024-01-29T14:27:10+08:00",
        "Activities": [
          {
            "StatusDateTime": "2024-01-29T14:27:10+08:00",
            "StatusCode": "DR_DR",
            "StatusDesc": "Data Received via API",
            "Remarks": "",
            "ReceiveBy": ""
          }
        ]
      }
    ],
    "Errors": [
      {
        "TrackingNumber": "C240126144626997791271",
        "Remarks": "No Record(s)"
      }
    ]
  }
}

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

错误响应

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

{
    "Code": 1,
    "Message": "TrackingNumber require",
    "Data": []
}

结果码

Code	说明
0	成功
1	失败

示例

Bash

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

curl -X POST "$BASE_URL/api/status/lookup" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"TrackingNumber":["C240129142515839830635","C240126144626997791271"]}'

Windows PowerShell

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

# 即使只有一个单号也要强制成数组，保证序列化为 JSON 数组
$body = @{
    TrackingNumber = @("C240129142515839830635", "C240126144626997791271")
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "$BASE_URL/api/status/lookup" -Method Post `
    -ContentType "application/json" -Body $body -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.post(f"{BASE_URL}/api/status/lookup", json={
    "TrackingNumber": [
        "C240129142515839830635",
        "C240126144626997791271",
    ],
}, headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
payload = resp.json()

# 两个数组都要检查——单个包裹查不到不会改变 Code
print(payload["Data"]["Success"], payload["Data"]["Errors"])

Node.js / TypeScript

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

const res = await fetch(`${BASE_URL}/api/status/lookup`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    TrackingNumber: [
      "C240129142515839830635",
      "C240126144626997791271",
    ],
  }),
});
const payload = await res.json();

// 两个数组都要检查——单个包裹查不到不会改变 Code
console.log(payload.Data.Success, payload.Data.Errors);

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/lookup');
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([
    'TrackingNumber' => [
        'C240129142515839830635',
        'C240126144626997791271',
    ],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
curl_close($ch);

$payload = json_decode($response, true);

// 两个数组都要检查——单个包裹查不到不会改变 Code
print_r([$payload['Data']['Success'], $payload['Data']['Errors']]);
?>

注意事项

• 部分查不到不算失败。 只要请求本身合法，响应就是 Code: 0 和 Message: "Success"——即使所有运单号都落进了 Data.Errors。请遍历 Data.Success 和 Data.Errors 两个数组，不要只看 Code。
• 两个数组合起来覆盖你提交的全部运单号，顺序与提交顺序一致。
• 所有时间均为新加坡时间（UTC+08:00），以带偏移量的 ISO 8601 格式返回。
• 请按 StatusCode 做业务分支，不要按 StatusDesc 做字符串匹配。描述文本会随承运商和账号配置变化，而状态码是稳定的。
• 仅内部使用的状态记录会被过滤掉，因此 Activities 可能短于包裹的完整内部历史。
• 运单号按原样精确匹配——不会转为大写，请完全按签发时的形式发送。
• 只能查询到属于当前认证账号的包裹；属于其他账号的单号会被报为 No Record(s)，而不是权限错误。
• TrackingNumber 必须是 JSON 数组，传纯字符串会被校验拒绝。
• 服务端未对数组长度设上限，但请把批量大小控制在你自己客户端超时能承受的范围内——整批在一个请求里完成解析。

错误码

code	message	说明
1	TrackingNumber require	TrackingNumber 缺失或为空。
1	Error encountered, please contact tech@wmg-group.com with screenshot of error page for resolution.	未预期的服务端错误。
1003	Token error	Token 缺失、已过期或被新登录顶替。请重新调用 获取 Token。

单个运单号解析失败不会出现在这张表里——它们会以 Remarks: "No Record(s)" 的形式返回在 Data.Errors 中，而 Code 仍为 0。