查看源

接口名称

上传订单 (Upload Orders)

接口地址

/api/shipper/v1/order/upload/uploadOrder

请求方式

POST

Content-Type: multipart/form-data

接口描述

该接口用于上传 Excel 文件批量创建运单订单。上传时需要指定映射模板、发件网点、目的国家和服务渠道等参数。

请求头

参数	类型	必填	说明
sessionId	String	是	登录会话ID
language	String	是	语言
Content-Type	String	是	multipart/form-data

语言取值：

值	说明
zh_CN	中文
en_US	英文

请求参数（multipart/form-data）

参数	类型	必填	说明
file	File	是	上传的 Excel 文件（.xlsx 或 .xls）
templateId	Number	是	映射模板ID，默认0
facility	String	是	发件网点代码，默认为 "*"
country	String	是	目的国家代码
channelId	Number	是	服务渠道ID

文件限制：

限制项	说明
文件类型	xlsx, xls
文件大小	最大 15MB
文件数量	单次最多 1 个文件

请求示例

curl 'https://tracking-qa.etowertech.com/api/shipper/v1/order/upload/uploadOrder' \
  -H 'sessionId: vP1l43F_OqvoTUWBcaAtyg' \
  -H 'language: zh_CN' \
  -F 'file=@/path/to/orders.xlsx' \
  -F 'templateId=0' \
  -F 'facility=*' \
  -F 'country=US' \
  -F 'channelId=456'

返回示例

*真实响应示例（文件内容为空）：*

{
  "success": true,
  "code": "0",
  "data": {
    "errorMessage": "上传的文件中无可解析的信息",
    "errors": [],
    "uploadResult": false,
    "missHeaders": [],
    "rowWarnings": [],
    "rowErrors": [],
    "verrors": []
  },
  "errors": []
}

*成功响应（code="0"，部分成功）：*

{
  "success": true,
  "code": "0",
  "data": {
    "errorMessage": "",
    "errors": [],
    "uploadResult": true,
    "missHeaders": [],
    "rowWarnings": [],
    "rowErrors": [
      {
        "rowNo": 5,
        "columnNo": "A",
        "errorMessage": "参考号已存在",
        "maxValue": null,
        "maxValueName": null,
        "hints": null
      }
    ],
    "verrors": []
  },
  "errors": []
}

*完整示例（包含成功和失败）：*

{
  "success": true,
  "code": "0",
  "data": {
    "fileId": "abc123xyz",
    "successCount": 95,
    "errorMessage": "",
    "uploadResult": true,
    "missHeaders": [],
    "rowWarnings": [
      "Row 10: Weight exceeds maximum limit",
      "Row 15: Length value too large"
    ],
    "rowErrors": [
      {
        "rowNo": 20,
        "columnNo": "C",
        "errorMessage": "Invalid country code",
        "maxValue": null,
        "maxValueName": null,
        "hints": null
      },
      {
        "rowNo": 25,
        "columnNo": "F",
        "errorMessage": "邮编格式错误",
        "maxValue": null,
        "maxValueName": null,
        "hints": null
      }
    ],
    "verrors": []
  },
  "errors": []
}

*失败响应（code≠"0"）：*

{
  "success": false,
  "code": "400",
  "data": null,
  "errors": [
    {
      "message": "Invalid template ID",
      "code": "INVALID_TEMPLATE"
    }
  ]
}

返回字段说明

*响应顶层字段：*

字段	类型	说明
success	Boolean	请求是否成功
code	String	响应状态码，"0"表示成功
data	Object	上传结果数据
errors	Array	错误信息列表

*data 字段说明：*

字段	类型	说明
fileId	String	上传文件ID，用于下载失败文件
successCount	Number	成功创建的订单数量
errorMessage	String	总体错误信息
uploadResult	Boolean	上传是否成功（整体结果）
missHeaders	Array[String]	缺失的必填列名
rowWarnings	Array[String]	行警告信息（不影响上传）
rowErrors	Array[Object]	行错误详情（该行未创建成功）
verrors	Array	其他验证错误

*rowError 字段说明：*

字段	类型	说明
rowNo	Number	错误行号
columnNo	String	错误列号（Excel列字母）
errorMessage	String	错误描述
maxValue	Number	最大允许值（如有）
maxValueName	String	最大值字段名
hints	Object	提示信息