运单服务-下单

基本信息

方法：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 用于下单

基本信息​

用途​

幂等规则​

请求参数​

地址对象字段​

包裹对象字段​

危险品对象字段​

商品对象字段​

附加选项对象字段​

请求示例​

成功响应示例​

返回字段说明​

面单对象字段​

成本摘要对象字段​

接口说明​