跳到主要内容

创建尾派小包

在系统中创建新尾派小包并生成跟踪号。

端点： POST /api/shipments

所需权限 (Scope): shipments:write

请求规范​

属性类型必填描述
ReferenceIdstring否您对此尾派小包的内部参考 ID。
DuplicatedReferenceIdControlDuplicatedReferenceIdControl否当系统中存在重复的参考 ID 时应如何处理。仅在提供了 ReferenceId 时有效。
ShippingProductIdstring是要使用的运输产品 ID。
ToAddressAddress是目的地址。
FromAddressAddress是始发地址。
ReturnAddressAddress否退货地址。
WeightWeight是尾派小包重量。
SizeDimensions是尾派小包尺寸。
DeclaredValueMoney否尾派小包申报价值。
ShipDatestring是计划发货日期，格式为 YYYY-MM-DD。
ExtraServicesstring[]否小包的额外服务项，例如 usps_818。
Notesstring否200字以内的备注。

DuplicatedReferenceIdControl 枚举​

属性描述
AlwaysAllow默认行为，始终允许系统中存在重复的参考 ID。
AllowRecreateIfExistingShipmentFailed如果参考 ID 已存在，且现有尾派小包处于失败状态，则重新创建一个全新尾派小包。
Disallow如果参考 ID 已存在，则拒绝请求。

请谨慎对待重复的参考 ID：

如果您允许重复，则同一参考 ID 将拥有多条记录，在通过参考 ID 查询的 查询尾派小包 API 中，您将获得多条记录。如果记录成功获取跟踪号，您将为每条记录付费。

如果您禁止重复，则需要自行处理重复的参考 ID，尤其是在尾派小包无法从承运商处获取跟踪号时。在这种情况下，重新提交与之前完全相同的创建请求仅会获取旧的尾派小包记录。如果使用相同的参考 ID 但不同的地址/重量/尺寸信息重新提交创建请求，将遇到重复参考 ID 错误（代码 OMS-SHPT-005）。

响应规范​

返回包装在 Result 中的 Shipment 对象。

示例 JSON​

请求​

{
  "ReferenceId": "ORDER-123",
  "ShippingProductId": "PRODUCT001",
  "ToAddress": {
    "ContactName": "John Doe",
    "Street1": "123 Main St",
    "City": "New York",
    "Province": "NY",
    "CountryCode": "US",
    "Postcode": "10001",
    "Tel": "555-0199"
  },
  "FromAddress": {
    "ContactName": "Shipper Name",
    "Street1": "456 Logistic Way",
    "City": "Los Angeles",
    "Province": "CA",
    "CountryCode": "US",
    "Postcode": "90001"
  },
  "Weight": {
    "Value": 1.3,
    "Unit": "LB"
  },
  "Size": {
    "Length": 25.4,
    "Width": 12.7,
    "Height": 7.62,
    "Unit": "IN"
  },
  "ShipDate": "2026-04-01",
  "ExtraServices": null,
  "Notes": ""
}

响应​

{
  "Data": {
    "Id": "2603XSHPT00001GA",
    "AccountNo": "TEST",
    "ReferenceId": "ORDER-123",
    "ShippingProductId": "PRODUCT001",
    "ToAddress": {
      "Company": "",
      "Street1": "123 Main St",
      "Street2": "",
      "Street3": "",
      "City": "New York",
      "Province": "NY",
      "CountryCode": "US",
      "Postcode": "10001",
      "ContactName": "John Doe",
      "Tel": "555-0199",
      "Email": "",
      "TaxId": ""
    },
    "FromAddress": {
      "Company": "",
      "Street1": "456 Logistic Way",
      "Street2": "",
      "Street3": "",
      "City": "Los Angeles",
      "Province": "CA",
      "CountryCode": "US",
      "Postcode": "90001",
      "ContactName": "Shipper Name",
      "Tel": "",
      "Email": "",
      "TaxId": ""
    },
    "ReturnAddress": null,
    "Weight": {
      "Value": 1.3,
      "Unit": "LB"
    },
    "Size": {
      "Length": 25.4,
      "Width": 12.7,
      "Height": 7.62,
      "Unit": "IN"
    },
    "DeclaredValue": null,
    "ShipDate": "2026-04-01",
    "ExtraServices": null,
    "Notes": "",
    "Quote": {
      "QuotationType": "Basic",
      "Fees": [
        {
          "FeeType": "BASE",
          "Amount": 23.16
        },
        {
          "FeeType": "REGISTRATION",
          "Amount": 5.0
        },
        {
          "FeeType": "NON_STANDARD_LENGTH",
          "Amount": 4.5
        }
      ],
      "Total": 32.66,
      "Weight": 1.3,
      "DimensionalWeight": 14.808,
      "FeeWeight": 14.808,
      "FeeWeightType": "DimensionalWeight",
      "PriceZone": "8",
      "WeightUnit": "LB",
      "LengthUnit": "IN",
      "CurrencyCode": "USD"
    },
    "Carrier": {
      "Status": "Processing",
      "Barcode": "",
      "Message": ""
    },
    "TrackingNumber": "",
    "CreateAt": "2026-03-24T03:36:31Z"
  },
  "Succeeded": true,
  "Error": null,
  "CapturedValues": {}
}