购买运输标签

购买运输标签并立即返回追踪号和标签 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

要打印在运输标签上的自定义字段。支持情况因承运商而异： - USPS：字段显示在内容描述中 - EasyPost：使用 print_custom_1/2/3 字段（每个最多 35 个字符） - ShipEngine：使用 label_messages reference1/2/3（每个最多 35 个字符） - Shippo：存储在 metadata 中供 API 参考 - Pitney Bowes：使用带 name/value 对的 references 数组

options object

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

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 未找到费率

购买运输标签

参数

请求体

返回

相关