Comprar una etiqueta de envío

Compra una etiqueta de envío y devuelve inmediatamente el número de seguimiento y la URL de la etiqueta. Flujo de trabajo recomendado: 1. Primero llama a `POST /v1/rates` para obtener las tarifas disponibles 2. Selecciona una tarifa y usa su `rate_id` para comprar la etiqueta Flujo de trabajo alternativo: - Especifica `carrier` y `service` directamente (se usará la tarifa coincidente más económica) El costo de la etiqueta se deduce automáticamente del saldo de tu cuenta.

Parámetros

Cuerpo de la solicitud

rate_id string

ID de tarifa de la respuesta de `POST /v1/rates` (recomendado). Si se proporciona, carrier y service se derivan de la tarifa.

from_address object Obligatorio

Dirección del remitente

to_address object Obligatorio

Dirección del destinatario

parcel object Obligatorio

Dimensiones y peso del paquete.

weight (number, obligatorio): Peso del paquete
length (number, opcional): Largo del paquete
width (number, opcional): Ancho del paquete
height (number, opcional): Alto del paquete
weight_unit (string, opcional, por defecto oz): oz | lb | g | kg
dimension_unit (string, opcional, por defecto in): in | cm

Ejemplo imperial: { "weight": 16, "length": 10, "width": 8, "height": 4, "weight_unit": "oz", "dimension_unit": "in" }
Ejemplo métrico: { "weight": 0.5, "length": 25, "width": 20, "height": 10, "weight_unit": "kg", "dimension_unit": "cm" }

carrier string (USPS | FEDEX | UPS | DHL)

Código del transportista. Obligatorio si no se proporciona `rate_id`.

service string

Nombre del servicio (legible por humanos). Obligatorio si no se proporcionan `rate_id` ni `service_code`. Usa `service` O `service_code`, no ambos.

service_code string

Código del servicio (legible por máquina). Alternativa a `service`. Obtenlo del campo `service_code` en la respuesta de `/v1/rates`.

carrier_account_id string

El ID de tu cuenta de transportista BYOCA (para tarifas negociadas)

label_format string (pdf | png | zpl)

Formato de archivo de la etiqueta

label_size string (4x6 | 4x8)

Dimensiones de la etiqueta

reference string

Tu referencia interna (por ejemplo, el ID del pedido)

label_custom_fields object

Campos personalizados para imprimir en la etiqueta de envío. Lo que llega a la etiqueta impresa depende del transportista y del servicio: la mayoría imprime los campos de referencia y muestra el SKU/UPC en la descripción del contenido; cuando un campo no es compatible, se guarda junto con la etiqueta y la API lo devuelve, pero no aparece en la etiqueta. Mantén cada valor dentro del maxLength documentado — los transportistas que sí imprimen estos campos truncan silenciosamente al superar su propio límite.

options object

Opciones de envío que incluyen seguro, firma y materiales peligrosos

ship_date string

Fecha de envío. Se acepta tanto en el nivel superior como dentro de options (si se envían ambos, prevalece options), para poder reutilizar la misma forma de la petición POST /v1/rates. Debe coincidir con la fecha con la que se cotizó la tarifa: si es distinta, la etiqueta se vuelve a tarificar y el cargo deja de coincidir con la tarifa que aceptaste. Si la enviaste al cotizar pero no aquí, la etiqueta sale con fecha de hoy: la cotización no arrastra la fecha a la compra, hay que repetirla.

billing object

Parte responsable del pago para cuentas de transportista BYOCA (por ejemplo, tu propia cuenta de UPS). Requiere que carrier_account_id esté configurado.

payer (obligatorio): shipper (por defecto — se factura a tu cuenta BYOCA) | recipient | third_party
accountNumber: Obligatorio para recipient y third_party
countryCode: ISO de 2 letras. Obligatorio para third_party
postalCode: Obligatorio para third_party

Devuelve

201 Etiqueta comprada correctamente

400 Datos de solicitud no válidos

401 Se requiere autenticación

402 Fondos insuficientes

404 Tarifa no encontrada

Relacionado

Labels

POST/api/v1/labels