修改包裹尺寸与重量

接口概述

修改已登记但尚未随已关闭订单发出的包裹的尺寸和/或重量。只需传你想改的那几项测量值。

请求信息

• Method: POST
• Path: /api/parcel/edit-parcel-size-weight
• Authentication: Bearer Token

请求头

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

请求参数

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

参数	类型	必填	说明
wmg_tracking_num	string	条件必填	包裹的 WMG 运单号。最长 60 个字符。本字段与 tracking_number 至少传一个。
tracking_number	string	条件必填	你自己的包裹跟踪号。最长 50 个字符。本字段与 wmg_tracking_num 至少传一个。
weight	number	否	新的申报重量。最多保留 3 位小数。不传则不修改。
length	number	否	新的长度。最多保留 2 位小数。不传则不修改。
width	number	否	新的宽度。最多保留 2 位小数。不传则不修改。
height	number	否	新的高度。最多保留 2 位小数。不传则不修改。

请求体示例

{
    "wmg_tracking_num": "CY18000004XX4SG",
    "weight": "12.028",
    "length": "12.08",
    "width": "12.08",
    "height": "12.08"
}

认证方式

本接口使用 Bearer Token 认证。

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

响应信息

响应为 JSON 格式。

响应格式

字段	类型	说明
Code	integer	0 表示成功；非 0 表示失败
Message	string	可读的结果说明
Data	array	本接口始终返回空数组

成功响应

• Status Code: 200

{
    "Code": 0,
    "Message": "Success",
    "Data": []
}

本接口不返回业务数据。Code 为 0 即表示包裹已更新。

错误响应

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

{
    "Code": 1,
    "Message": "Parcel Not Found",
    "Data": []
}

结果码

Code	说明
0	成功
1	失败

示例

Bash

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

curl -X POST "$BASE_URL/api/parcel/edit-parcel-size-weight" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"wmg_tracking_num":"CY18000004XX4SG","weight":"12.028","length":"12.08","width":"12.08","height":"12.08"}'

Windows PowerShell

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

# 只传你想修改的测量值
$body = @{
    wmg_tracking_num = "CY18000004XX4SG"
    weight           = "12.028"
    length           = "12.08"
    width            = "12.08"
    height           = "12.08"
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "$BASE_URL/api/parcel/edit-parcel-size-weight" -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/parcel/edit-parcel-size-weight", json={
    "wmg_tracking_num": "CY18000004XX4SG",
    "weight": "12.028",
    "length": "12.08",
    "width": "12.08",
    "height": "12.08",
}, 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 res = await fetch(`${BASE_URL}/api/parcel/edit-parcel-size-weight`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${TOKEN}`,
  },
  // 只传你想修改的测量值
  body: JSON.stringify({
    wmg_tracking_num: "CY18000004XX4SG",
    weight: "12.028",
    length: "12.08",
    width: "12.08",
    height: "12.08",
  }),
});
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/parcel/edit-parcel-size-weight');
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([
    'wmg_tracking_num' => 'CY18000004XX4SG',
    'weight'           => '12.028',
    'length'           => '12.08',
    'width'            => '12.08',
    'height'           => '12.08',
]));
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";
?>

注意事项

• 可以用 wmg_tracking_num、tracking_number，或两者同时来定位包裹。两个都不传会返回 Tracking Number or wmg tracking num is invalid。两个都传时，包裹必须同时匹配这两个值。
• 两个标识字段在匹配前都会转为大写，因此不区分大小写。
• 未传的测量值保持不变，因此部分更新是常规用法。显式传 0 会被写入——只有确实要设为 0 时才传 0。
• 包裹不能已属于已关闭的订单。订单一旦关闭，测量值即被锁定，调用会返回 Parcel was used。
• 更新后的长、宽、高、重量会作为一组，按该包裹的服务与目的地限制统一校验。由于未传的字段会沿用已存储的值，只改一项也可能导致超限——消息会指出是哪一项限制。
• 每次修改都会记录到包裹上，用于审计追溯。
• 只能修改属于当前认证账号的包裹。
• 所有参数区分大小写。

错误码

code	message	说明
1	Tracking Number or wmg tracking num is invalid	wmg_tracking_num 和 tracking_number 都没有传。
1	Parcel Not Found	你的账号下没有与所传标识匹配的包裹。
1	Parcel was used	该包裹所属订单已关闭。
1	max size of wmg_tracking_num must be 60	wmg_tracking_num 超过 60 个字符。
1	max size of tracking_number must be 50	tracking_number 超过 50 个字符。
1		更新后的尺寸或重量超出该包裹服务与目的地的限制，消息会指出是哪一项限制。
1	Error encountered, please contact tech@wmg-group.com with screenshot of error page for resolution.	未预期的服务端错误。
1003	Token error	Token 缺失、已过期或被新登录顶替。请重新调用 获取 Token。