购买运输标签

购买运输标签并立即返回追踪号和标签 URL。推荐工作流程： 1. 首先调用 `POST /v1/rates` 获取可用费率 2. 选择一个费率并使用其 `rate_id` 购买标签备选工作流程： - 直接指定 `carrier` 和 `service`（将使用最便宜的匹配费率）标签费用会自动从您的账户余额中扣除。

参数

请求体

rate_id string

来自 `POST /v1/rates` 响应的费率 ID（推荐）。如果提供，carrier 和 service 将从该费率中派生。

from_address object 必填

发件人地址

to_address object 必填

收件人地址

parcel object 必填

包裹尺寸和重量。

weight（number，必填）：包裹重量
length（number，可选）：包裹长度
width（number，可选）：包裹宽度
height（number，可选）：包裹高度
weight_unit（string，可选，默认 oz）：oz | lb | g | kg
dimension_unit（string，可选，默认 in）：in | cm

英制示例： { "weight": 16, "length": 10, "width": 8, "height": 4, "weight_unit": "oz", "dimension_unit": "in" }
公制示例： { "weight": 0.5, "length": 25, "width": 20, "height": 10, "weight_unit": "kg", "dimension_unit": "cm" }

carrier string (USPS | FEDEX | UPS | DHL)

承运商代码。如果未提供 `rate_id` 则必填。

service string

服务名称（可读）。如果未提供 `rate_id` 和 `service_code` 则必填。使用 `service` 或 `service_code` 之一，不要同时使用两者。

service_code string

服务代码（机器可读）。作为 `service` 的替代方案。从 `/v1/rates` 响应中的 `service_code` 字段获取。

carrier_account_id string

您的 BYOCA 承运商账户 ID（用于协商费率）

label_format string (pdf | png | zpl)

标签文件格式

label_size string (4x6 | 4x8)

标签尺寸

reference string

您的内部参考（例如订单 ID）

label_custom_fields object

要打印在运输标签上的自定义字段。最终能印到标签上的内容取决于承运商和具体服务：多数承运商会打印 reference 字段，并把 SKU/UPC 显示在内容描述中；某个字段不被支持时，它仍会随标签一起保存并由 API 返回，只是不出现在标签本身上。每个值请控制在文档标注的 maxLength 以内 —— 会打印这些字段的承运商，超过各自的上限时会静默截断。

options object

运输选项，包括保险、签收和危险品

ship_date string

发货日期。顶层和 options 里都可以传（两者都传时以 options 为准），方便直接沿用 POST /v1/rates 的请求结构。必须与报价时使用的日期一致 —— 不一致会重新定价，实际扣款会和你接受的那个报价对不上。报价时传了、买单时不传，面单按当天发货：报价不会自动把发货日期带到买单，需要在这里再传一次。

billing object

BYOCA 承运商账户的付款方（例如您自己的 UPS 账户）。需要设置 carrier_account_id。

payer（必填）：shipper（默认 — 向您的 BYOCA 账户收费）| recipient | third_party
accountNumber：recipient 和 third_party 时必填
countryCode：2 位 ISO。third_party 时必填
postalCode：third_party 时必填

201 标签购买成功

400 请求数据无效

401 需要身份验证

402 余额不足

404 未找到费率

购买运输标签

参数

请求体

返回

相关