UPS - Crear Envio / Etiqueta

Descripcion

Este modulo crea un envio en UPS a traves de la API Shipments v1. Recibe los datos del remitente y destinatario en formato JSON, codigo de servicio, peso, dimensiones opcionales, formato de etiqueta y referencia. Construye el payload ShipmentRequest completo incluyendo informacion de pago (cargo al remitente), especificacion de etiqueta y detalles del paquete. Realiza una peticion POST al endpoint /api/shipments/v1/ship y retorna el numero de seguimiento, etiqueta en base64, cargos totales y moneda.

Configuracion

Parametro	Tipo	Requerido	Descripcion
credentials_id	credentials	Si	Credencial UPS (provider: ups)
shipper	textarea	Si	Datos del remitente en JSON con Name, ShipperNumber y Address
ship_to	textarea	Si	Datos del destinatario en JSON con Name y Address
service_code	select	Si	Codigo de servicio: 01 (Next Day Air), 02 (2nd Day Air), 03 (Ground), 07 (Express), 08 (Expedited), 11 (Standard), 65 (Saver)
package_weight	text	Si	Peso del paquete en kilogramos
package_dimensions	textarea	No	Dimensiones en JSON (Length, Width, Height)
label_format	select	No	Formato de etiqueta: PDF (por defecto), PNG, ZPL, GIF
reference	text	No	Referencia interna del envio

Credenciales

Se requiere una credencial de tipo ups con los siguientes campos:

client_id: Client ID de la API de UPS
client_secret: Client Secret de la API de UPS
account_number: Numero de cuenta de UPS (opcional, puede ir en el JSON del shipper)

Las credenciales se obtienen desde UPS Developer Portal (https://developer.ups.com/).

Salida

{
  "success": true,
  "tracking_number": "1Z999AA10123456784",
  "shipment_id": "1Z999AA10123456784",
  "label_base64": "iVBORw0KGgo...",
  "label_format": "PDF",
  "total_charges": "25.50",
  "currency": "EUR",
  "service_code": "11",
  "status": "CREATED",
  "message": "Envio UPS creado - Tracking: 1Z999AA10123456784"
}

Ejemplo de Uso

Caso basico

{
  "credentials_id": "mi_credencial_ups",
  "shipper": "{\"Name\":\"Mi Empresa\",\"ShipperNumber\":\"ABC123\",\"Address\":{\"AddressLine\":[\"Calle Gran Via 1\"],\"City\":\"Madrid\",\"StateProvinceCode\":\"M\",\"PostalCode\":\"28001\",\"CountryCode\":\"ES\"}}",
  "ship_to": "{\"Name\":\"Cliente\",\"Address\":{\"AddressLine\":[\"Av Diagonal 100\"],\"City\":\"Barcelona\",\"PostalCode\":\"08001\",\"CountryCode\":\"ES\"}}",
  "service_code": "11",
  "package_weight": "2.5",
  "label_format": "PDF"
}

API Utilizada

Endpoint: POST /api/shipments/v1/ship
Base: UPS API (via helper _upsHelper)
Documentacion: https://developer.ups.com/api/reference

Notas

La autenticacion usa OAuth2 con client_id y client_secret
El pago se configura automaticamente como cargo al remitente (BillShipper)
Para formato ZPL, se configura automaticamente el tamano de etiqueta 6x4
El ShipperNumber puede venir del JSON del remitente o de las credenciales
La SubVersion de la API es 1801
Las dimensiones se expresan en centimetros y el peso en kilogramos