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
dimension_unit (string, opcional, por defecto
Ejemplo imperial:
Ejemplo métrico:
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 | kgdimension_unit (string, opcional, por defecto
in): in | cmEjemplo 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. El soporte varía según el transportista:
- USPS: Los campos aparecen en la descripción del contenido
- EasyPost: Usa los campos print_custom_1/2/3 (hasta 35 caracteres cada uno)
- ShipEngine: Usa label_messages reference1/2/3 (hasta 35 caracteres cada uno)
- Shippo: Se almacena en metadata para referencia de la API
- Pitney Bowes: Usa el arreglo references con pares name/value
options
object
Opciones de envío que incluyen seguro, firma y materiales peligrosos
billing
object
Parte responsable del pago para cuentas de transportista BYOCA (por ejemplo, tu propia cuenta de UPS). Requiere que
payer (obligatorio):
accountNumber: Obligatorio para
countryCode: ISO de 2 letras. Obligatorio para
postalCode: Obligatorio para
carrier_account_id esté configurado.payer (obligatorio):
shipper (por defecto — se factura a tu cuenta BYOCA) | recipient | third_partyaccountNumber: Obligatorio para
recipient y third_partycountryCode: ISO de 2 letras. Obligatorio para
third_partypostalCode: 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