运单服务-下单

基本信息

• 方法：POST
• 路径：/label/carrier/create
• Handler：carrierApi.CreateOrder
• Service：CarrierOpenAPIService.CreateOrder

用途

创建开放运单并向承运商下单，返回 TMS 运单号、渠道订单号、主跟踪号、面单地址和成本摘要。

幂等规则

externalRequestId 是幂等键，行为如下：

• 如果同一 OpenAPI 用户下已经存在 created 状态的相同请求，会直接返回历史结果
• 如果同一请求仍处于 processing 状态，会返回：request is processing, please retry later

请求参数

在询价参数基础上，额外支持以下字段。嵌套对象结构见下方各对象字段说明。

字段	类型	必填	说明
externalRequestId	string	是	外部请求号，幂等键
carrierCode	string	是	承运商代码
serviceCode	string	否	服务代码
accountAlias	string	否	账号别名，多账号场景建议传
accountId	int	否	预留字段，当前未使用
senderAddress	object	是	发件地址，结构见下方地址对象字段
recipientAddress	object	是	收件地址，结构见下方地址对象字段
returnAddress	object	否	退件地址，结构见下方地址对象字段；当前服务实现未消费
packages	array	是	包裹列表，至少 1 条，元素结构见下方包裹对象字段
products	array	否	商品列表，元素结构见下方商品对象字段
options	object	否	附加选项，结构见下方附加选项对象字段
labelFileType	string	否	面单文件类型，如 PDF
sellerOrderNumber	string	否	卖家订单号
referenceNo	string	否	订单参考号；当前服务实现未消费
selectedRateId	string	否	选中的报价 ID；当前服务实现未消费

地址对象字段

用于 senderAddress、recipientAddress、returnAddress 等字段。

字段	类型	必填	说明
code	string	否	地址编码
name	string	否	名称/公司名
attentionName	string	否	联系人姓名
countryCode	string	是	国家代码，如 US
stateCode	string	否	州/省代码，如 CA、NY
city	string	否	城市
addressLine1	string	是	地址行 1
addressLine2	string	否	地址行 2
addressLine3	string	否	地址行 3
postalCode	string	是	邮编
phone	string	否	联系电话
phoneExtension	string	否	电话分机
email	string	否	邮箱
memo	string	否	备注
mid	string	否	MID 标识，部分国际件场景使用
isResidential	bool	否	是否住宅地址，默认 false
verifyStatus	int	否	地址校验状态，一般由响应回填，请求可不传

说明：Gin 绑定仅校验地址对象本身非空；实际调用时 countryCode、addressLine1、postalCode 为业务必填。

包裹对象字段

用于 packages[] 数组元素，至少 1 条。

字段	类型	必填	说明
id	int	否	包裹 ID，内部使用，开放接口可不传
length	float	是	长度，单位由 options.dimensionUnitCode 决定
width	float	是	宽度
height	float	是	高度
weight	float	是	重量，单位由 options.weightUnitCode 决定
quantity	int	否	数量，默认 1
declaredValue	float	否	单包裹申报价值
reference1	string	否	参考号 1
reference2	string	否	参考号 2
reference3	string	否	参考号 3
hazMat	object	否	危险品信息，结构见下方危险品对象字段
freightClass	string	否	货运等级，LTL 等场景使用
quantityUnitPcs	int	否	件数单位

危险品对象字段

嵌套在 packages[].hazMat 中，仅危险品包裹需要传。

字段	类型	必填	说明
ReferenceNumber	string	否	参考号
shippingName	string	否	危险品正式运输名称
RegulationSet	string	否	法规集，空运常用 IATA
TransportationMode	string	否	运输模式，常用 CAO
classDivisionNumber	string	否	危险等级/分类号
quantity	string	否	危险品数量
IDNumber	string	否	UN/ID 编号
UOM	string	否	计量单位
PackagingType	string	否	包装类型，如 FIBERBOARD BOX

商品对象字段

用于 products[] 数组元素，国际件建议传。

字段	类型	必填	说明
id	int	否	商品 ID，内部使用，开放接口可不传
description	string	否	商品描述
quantity	int	否	数量
weight	float	否	重量
declaredValue	float	否	申报价值
declaredValueClass	int	否	申报价值等级
hsCode	string	否	HS 编码
originCountry	string	否	原产国代码

附加选项对象字段

用于 options 字段。

字段	类型	必填	说明
deliveryConfirmation	string	否	签收确认类型，如 signature、adult_signature
shipDate	string	否	发货日期，格式 YYYY-MM-DD
packageType	string	否	包装类型，如 YOUR_PACKAGING
dimensionUnitCode	string	否	尺寸单位，常用 IN 或 CM
weightUnitCode	string	否	重量单位，常用 LBS 或 KG
declaredValueCurrencyCode	string	否	申报价值币种，如 USD
isUniqueSellerOrderNumber	bool	否	卖家订单号是否唯一，默认 false

请求示例

{
  "externalRequestId": "REQ-20260611-CREATE-001",
  "carrierCode": "UPARCEL",
  "serviceCode": "GROUND",
  "accountAlias": "UPARCEL_MAIN",
  "accountId": 0,
  "senderAddress": {
    "name": "Sender Company",
    "attentionName": "Tom",
    "countryCode": "US",
    "stateCode": "CA",
    "city": "Los Angeles",
    "addressLine1": "123 Main St",
    "addressLine2": "",
    "postalCode": "90001",
    "phone": "1234567890",
    "email": "demo@example.com",
    "isResidential": false
  },
  "recipientAddress": {
    "name": "Receiver Company",
    "attentionName": "Jerry",
    "countryCode": "US",
    "stateCode": "NY",
    "city": "New York",
    "addressLine1": "456 Madison Ave",
    "addressLine2": "",
    "postalCode": "10001",
    "phone": "1234567890",
    "email": "demo@example.com",
    "isResidential": false
  },
  "returnAddress": {
    "name": "Return Company",
    "attentionName": "Tom",
    "countryCode": "US",
    "stateCode": "CA",
    "city": "Los Angeles",
    "addressLine1": "789 Return Rd",
    "addressLine2": "",
    "postalCode": "90001",
    "phone": "1234567890",
    "email": "demo@example.com",
    "isResidential": false
  },
  "packages": [
    {
      "length": 10,
      "width": 8,
      "height": 6,
      "weight": 5.5,
      "quantity": 1,
      "declaredValue": 120,
      "reference1": "BOX-001",
      "reference2": "",
      "reference3": ""
    }
  ],
  "products": [
    {
      "description": "T-shirt",
      "quantity": 1,
      "weight": 1.2,
      "declaredValue": 25,
      "hsCode": "610910",
      "originCountry": "US"
    }
  ],
  "options": {
    "deliveryConfirmation": "signature",
    "shipDate": "2026-06-11",
    "packageType": "YOUR_PACKAGING",
    "dimensionUnitCode": "IN",
    "weightUnitCode": "LBS",
    "declaredValueCurrencyCode": "USD",
    "isUniqueSellerOrderNumber": false
  },
  "labelFileType": "PDF",
  "sellerOrderNumber": "SO-20260611-001",
  "referenceNo": "REF-001",
  "selectedRateId": "rate_d4g8m1abc"
}

成功响应示例

{
  "code": 200,
  "data": {
    "externalRequestId": "REQ-20260611-CREATE-001",
    "tmsShipmentNumber": "OAPI_d4g8m1abc",
    "carrierCode": "UPARCEL",
    "serviceCode": "GROUND",
    "platformOrderNumber": "P202606110001",
    "masterTrackingNumber": "1Z999AA10123456784",
    "trackingNumbers": [
      "1Z999AA10123456784"
    ],
    "labelUrl": "https://label.example.com/1.pdf",
    "labelFileType": "PDF",
    "labels": [
      {
        "trackingNumber": "1Z999AA10123456784",
        "labelUrl": "https://label.example.com/1.pdf",
        "fileType": "PDF"
      }
    ],
    "costEstimate": {
      "amount": 15.67,
      "currencyCode": "USD",
      "source": "carrier_cost"
    }
  },
  "message": "success"
}

返回字段说明

字段	类型	说明
data.externalRequestId	string	外部请求号
data.tmsShipmentNumber	string	TMS 侧生成的开放运单号
data.carrierCode	string	承运商代码
data.serviceCode	string	服务代码
data.platformOrderNumber	string	渠道订单号
data.masterTrackingNumber	string	主跟踪号
data.trackingNumbers	array[string]	跟踪号列表
data.labelUrl	string	主面单地址
data.labelFileType	string	面单文件类型
data.labels	array	面单明细，元素结构见下方面单对象字段
data.costEstimate	object	成本摘要，结构见下方成本摘要对象字段

面单对象字段

用于 data.labels[] 数组元素。

字段	类型	说明
trackingNumber	string	该面单对应跟踪号
labelUrl	string	面单下载地址
fileType	string	面单文件类型，如 PDF

成本摘要对象字段

用于 data.costEstimate。

字段	类型	说明
amount	float	预估成本金额
currencyCode	string	币种，如 USD
source	string	成本来源，当前固定为 carrier_cost

接口说明

• 服务层会先落一条 processing 状态的审计记录，再调用渠道适配器 BuyLabel()
• 下单成功后会更新为 created 状态，并保存跟踪号、面单列表和成本摘要
• 如果保存审计记录时遇到唯一键冲突，会尝试返回已存在的幂等结果

当前实现注意点：

• accountId 当前未使用
• returnAddress、referenceNo、selectedRateId 在请求结构中已定义，但当前服务实现没有实际消费
• 实际下单服务代码取自解析后的账号服务，不是直接把请求里的 selectedRateId 用于下单