运单服务-取消运单

基本信息

• 方法：POST
• 路径：/label/carrier/void
• Handler：carrierApi.VoidOrder
• Service：CarrierOpenAPIService.VoidOrder

用途

取消已经通过开放接口创建的运单。

请求参数

字段	类型	必填	说明
carrierCode	string	是	承运商代码
accountAlias	string	否	账号别名
accountId	int	否	预留字段，当前未使用
externalRequestId	string	条件必填	外部请求号
tmsShipmentNumber	string	条件必填	TMS 运单号
platformOrderNumber	string	条件必填	渠道订单号
masterTrackingNumber	string	否	当前实现未用于查单
trackingNumber	string	否	当前实现未用于查单

说明：tmsShipmentNumber、platformOrderNumber、externalRequestId 三者至少传一个。

查单优先级

服务层按以下优先级定位订单：

1. tmsShipmentNumber
2. platformOrderNumber
3. externalRequestId

请求示例

{
  "externalRequestId": "REQ-20260611-CREATE-001",
  "carrierCode": "UPARCEL",
  "accountAlias": "UPARCEL_MAIN",
  "accountId": 0,
  "tmsShipmentNumber": "OAPI_d4g8m1abc",
  "platformOrderNumber": "",
  "masterTrackingNumber": "",
  "trackingNumber": ""
}

成功响应示例

{
  "code": 200,
  "data": {
    "externalRequestId": "REQ-20260611-CREATE-001",
    "tmsShipmentNumber": "OAPI_d4g8m1abc",
    "platformOrderNumber": "P202606110001",
    "trackingNumber": "1Z999AA10123456784",
    "result": "success",
    "message": "already voided"
  },
  "message": "success"
}

返回字段说明

字段	类型	说明
data.externalRequestId	string	外部请求号
data.tmsShipmentNumber	string	TMS 运单号
data.platformOrderNumber	string	渠道订单号
data.trackingNumber	string	跟踪号
data.result	string	取消结果，常见值 success / fail
data.message	string	结果说明

接口说明

• 如果订单已是 voided 状态，会直接返回成功，消息为 already voided
• 只有 created 状态的订单允许取消
• 如果订单归属的 ApiUserID 与当前用户不一致，会返回 order not found

当前实现注意点：

• masterTrackingNumber 和 trackingNumber 虽然在请求结构中存在，但当前取消逻辑不会用这两个字段查单
• 找到订单后，实际取消调用依赖审计订单上已保存的承运商与订单号信息