取消订单

接口说明

批量取消已下单但尚未进入配送流程的包裹。取消成功与失败的单号分别返回。

请求信息

• 方法：POST
• 路径：/openapi/order/cancel-orders
• 认证方式：标准 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 单号数组，单次最多 100 个

适用范围

本接口只处理当前客户名下、且已分配给 Shopee Express（SPX / SPX Pickup）承运的包裹。其他承运商的包裹不会被取消，会出现在 errors 里。

请求体示例

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

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

{
  "code": 0,
  "message": "success",
  "data": {
    "success": [
      "WR0BL260000046SG",
      "SPXSG066849392891",
      "SPXSG068750771351"
    ],
    "errors": [
      {
        "remarks": "Canceled",
        "tracking_number": "C251230155241302430003"
      },
      {
        "remarks": "No Record(s)",
        "tracking_number": "NZ2601089000005"
      },
      {
        "remarks": "Distribution process not found:dp id[660]",
        "tracking_number": "SPXSG061914269951"
      }
    ]
  }
}

字段	类型	说明
data.success	array	取消成功的单号列表
data.errors	array	取消失败的单号及原因
data.errors[].tracking_number	string	传入的单号
data.errors[].remarks	string	失败原因，取值之一：No Record(s)（当前客户下查不到，或不是 SPX 单）、Canceled（已经取消过）、Not Found In Partner System（承运商系统里没有该运单号）、Cancel Fail（承运商接口整批拒绝），或承运商取消接口直接返回的原文

失败响应

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

{
  "code": 1,
  "message": "tracking_nums required",
  "data": []
}

常见错误：

• 认证失败 → code 1；具体 message 取决于失败原因（如 x-auth-token: INVALID、x-auth-seed: TIMEOUT）—— 见认证与签名
• tracking_nums 为空 → code 1，message 为 tracking_nums required
• 单次超过 100 个 → code 1，message 为 Batch Cancel Maximum 100 tracking nums

结果码

Code	说明
0	成功
1	失败

调用示例

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/cancel-orders" \
  -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"]}'

Windows 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")
} | 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/cancel-orders" `
    -Method Post -Headers $headers -Body $body
$response | ConvertTo-Json -Depth 10

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'],
}

resp = requests.post('https://api.test.wmgdelivery.com/v1/openapi/order/cancel-orders', json=body, headers=headers)
print(resp.json())

Node.js / 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'],
});

const resp = await fetch('https://api.test.wmgdelivery.com/v1/openapi/order/cancel-orders', {
    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
$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'],
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.test.wmgdelivery.com/v1/openapi/order/cancel-orders');
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，不要只看 code。
• 单次最多 100 个单号。
• 认证 token 不包含请求参数，只用凭证和 seed 计算。
• x-auth-seed 必须是 13 位毫秒级 UNIX 时间戳，且与服务器时间相差不超过 ±10 分钟。
• 所有参数区分大小写。

错误码

code	message	说明
1	认证错误消息	认证失败；具体 message 取决于失败原因 —— 完整清单见认证与签名
1	tracking_nums required	tracking_nums 缺失或为空
1	Batch Cancel Maximum 100 tracking nums	单次提交超过 100 个单号