Cómo integrar la API de UPS en tu TMS paso a paso

Si tu empresa factura más de €5M anuales en transporte y trabaja con UPS como transportista principal de paquetería o carga LTL, probablemente ya tengas cotizaciones, generación de etiquetas o seguimiento funcionando a través de alguna integración puntual, un plugin de e-commerce o, peor, hojas de cálculo manuales. Integrar la API de UPS directamente en tu TMS corporativo es otra cosa: implica OAuth 2.0, credenciales de producción separadas por API, y una capa de autenticación adicional (AIA) si quieres ver tus tarifas negociadas en lugar de las publicadas. Esta guía cubre los siete pasos concretos para conectar Rating, Shipping y Tracking a tu sistema, y los dos errores de producción que más tiempo hacen perder a los equipos de IT de cargadores.

Qué necesitas antes de empezar la integración con UPS

Necesitas tres cosas antes de tocar una línea de código: una cuenta UPS con contrato comercial activo, acceso al Developer Portal de UPS para generar credenciales, y una factura reciente para activar la autenticación por factura (AIA). Sin esto último, tu Rating API devolverá tarifas publicadas, no las negociadas que tu empresa pactó con UPS.

• Número de cuenta UPS válido, idealmente con el mismo Payment Method vinculado en el apartado Accounts and Payment de ups.com.
• Registro en el Developer Resource Center de UPS para solicitar Client ID y Client Secret.
• Copia de una de tus facturas más recientes: "Account Invoice Authentication (AIA) is required for you to see your negotiated rates via the Shipping and Rating APIs. Ensure that you have a copy of your most recent invoice (within the last 45 days)" para completar la autenticación en My UPS.
• Decisión interna sobre qué equipo mantiene las credenciales: IT, compras de transporte o el proveedor de tu TMS.

Si gestionas varios transportistas además de UPS (DHL Express, SEUR, Maersk para marítimo), vale la pena preguntarte si quieres mantener este trabajo de credenciales, SubVersions y renovaciones de token por cada transportista por separado, o si prefieres un TMS con conectores ya certificados que te ahorre ese mantenimiento recurrente.

Los 7 pasos para conectar la API de UPS a tu TMS

El proceso completo, desde el registro de la aplicación hasta el primer evento de tracking, sigue esta secuencia. Sáltate pasos y acabarás con tokens caducados o envíos a México rechazados en producción.

1. Registra la aplicación en el Developer Kit. Entra en developer.ups.com, crea una nueva aplicación y anota tu Client ID y Client Secret. Estas credenciales son distintas para el entorno sandbox (CIE) y para producción.
2. Solicita el token de acceso vía OAuth 2.0. El flujo es Client Credentials contra el endpoint POST https://onlinetools.ups.com/security/v1/oauth/token, con Content-Type application/x-www-form-urlencoded y el Client ID y Secret codificados en Base64 en el header Authorization. Cachea el token en tu TMS y renuévalo antes de su expiración; no lo solicites en cada llamada, el límite diario de solicitudes de token existe precisamente para evitar ese patrón.
3. Solicita acceso de producción explícito para las APIs que lo requieren. No todas las APIs pasan de sandbox a producción automáticamente. UPS envía notificación por correo indicando qué APIs pueden requerir una segunda solicitud de acceso a producción, algo que suele afectar a Rating LTL Freight, Shipping, Pickup y Locator. Si tu equipo de IT no revisa ese correo, el proyecto se queda bloqueado en sandbox sin explicación aparente.
4. Integra primero la Address Validation API. No es opcional si tu volumen es alto. La validación de direcciones, aunque a menudo se pasa por alto, es crítica para prevenir fallos de entrega y los costes asociados antes de generar una cotización o una etiqueta. Es más barato rechazar una dirección mala en el formulario interno que pagar una devolución o un reintento de entrega.
5. Integra la Rating API. Aquí decides entre dos modos: la opción "Shop" presenta todos los servicios disponibles, mientras que la opción "Rate" devuelve tarifas para un servicio específico. Si tu objetivo es comparar servicios de UPS en tiempo real dentro del TMS, usa Shop. Y confirma que AIA esté activo, porque las tarifas publicadas se entregan por defecto; las tarifas negociadas específicas de cuenta solo se habilitan mediante Account Invoice Authentication.
6. Integra la Shipping API. El proceso funciona en dos fases: la fase Ship Confirm seguida de la fase Ship Accept, con un par de petición/respuesta intercambiado en cada una. Ten en cuenta que anular o anular un envío requiere su propio procedimiento y tipos de mensaje, no reutilices el mismo payload de creación. Apunta tus llamadas primero contra el entorno sandbox (wwwcie.ups.com) y solo después contra producción (onlinetools.ups.com).
7. Integra la Tracking API. Esta alimenta los estados de envío dentro del TMS: recogida, en tránsito, entregado. Si tu organización ya consume mensajes IFTSTA de otros transportistas marítimos o terrestres, el patrón de integración es equivalente: un identificador de envío entra, un estado normalizado sale, y tu TMS actualiza la vista del cliente interno o externo.

Cómo saber que la integración funciona correctamente

La integración funciona cuando obtienes tres respuestas concretas desde el entorno correcto: una cotización con desglose de cargos y tarifa negociada visible, una confirmación de envío con número de tracking y etiqueta en base64, y un evento de tracking con estado actualizado. Antes de mover nada a producción, valida todo esto en el entorno de pruebas.

UPS separa claramente ambos entornos: el sandbox (CIE) vive en wwwcie.ups.com para pruebas y desarrollo, mientras que onlinetools.ups.com recibe el tráfico real de producción. Un detalle que se pasa por alto: si tu cuenta tiene activado ABR (Account Based Rating), tanto las tarifas publicadas como las negociadas se devuelven en una misma respuesta cuando el indicador NegotiatedRatesIndicator se incluye en la petición. Si en sandbox ves solo tarifas publicadas pese a tener AIA activo, revisa que ese indicador esté presente en tu payload antes de abrir un ticket de soporte.

Un error común en producción (y cómo solucionarlo)

El fallo más frecuente que reportan equipos de cargadores con operación en México: envíos rechazados con el código de error 121984. La causa es regulatoria, no técnica. Desde 2022, el Servicio de Administración Tributaria mexicano implementó las regulaciones de Carta Porte, que exigen descripción de mercancía para todos los paquetes hacia, desde y dentro de México. UPS lo empezó a aplicar en sus APIs a partir del 6 de marzo de 2023, y desde entonces los envíos que no incluyen la descripción a nivel de paquete fallan con el error "121984 – A parcel in a Mexico shipment must have a Merchandise Description".

La solución es sencilla una vez identificada: añade el campo Description dentro del objeto Parcel en tu payload del Shipping API, con un valor descriptivo real del contenido (no genérico tipo "mercancía"). Si tu TMS genera el payload a partir de un ERP como SAP o Dynamics, confirma que ese campo esté mapeado desde el pedido de venta, no hardcodeado, porque auditorías posteriores de Carta Porte sí revisan la coherencia del dato.

El segundo fallo típico, menos visible pero más disruptivo: tokens OAuth caducados por no implementar refresco automático. Esto rompe silenciosamente los flujos de cotización en caliente durante la asignación de transportista o el checkout interno, y el síntoma suele ser un error de autenticación genérico que nada tiene que ver con el payload del envío. Revisa primero el ciclo de vida del token antes de depurar el resto de la integración.

UPS API vs EDI: cuándo usar cada modelo de conectividad

UPS sigue soportando ambos modelos en paralelo y no es casualidad: cada uno resuelve un problema distinto. La integración vía API y EDI permite automatizar cotización, reserva, etiquetado, seguimiento e intercambio de documentos, pero la elección depende de si necesitas respuesta en tiempo real o procesamiento por lotes.

Si tu empresa ya tiene infraestructura EDI instalada para facturación con otros transportistas, no tiene sentido migrar ese flujo a API solo por modernizarlo. Pero para rating, booking y tracking en tiempo real dentro de un TMS, la API es la opción natural. Plataformas de conectividad multi-transportista como Cargoson, Transporeon, EasyPost o Shippo mantienen conectores ya certificados con UPS y otros transportistas, lo que evita que tu equipo de IT desarrolle y mantenga uno a uno estos puentes de autenticación y mapeo de campos.

Mantenimiento de la integración a largo plazo

Una integración que funciona hoy puede romperse en el próximo release trimestral de UPS. Suscríbete a las actualizaciones del Developer Kit, porque los cambios llegan sin previo aviso en tu panel de administración: por ejemplo, el soporte para cotización con fecha futura cuando se envía el SubVersion 2205 en la petición apareció como actualización de enero sin romper compatibilidad hacia atrás, pero no todos los cambios son igual de amables. UPS también ha migrado servicios completos de API: TForce Freight lanzó Pickup, Shipping, Rating y Tracking en su propio portal, y UPS dejó de dar soporte a esas integraciones relacionadas con TForce Freight a partir de mayo de 2024. Si tu TMS dependía de esos endpoints, la migración no era opcional.

Revisa también los modelos de negocio no aprobados por UPS antes de construir algo que incumpla el acuerdo de API. Un ejemplo documentado: mostrar tarifas de UPS lado a lado con tarifas de la competencia aparece listado entre las limitaciones de uso de la Rating API, así que si tu plan es construir un comparador interno multitransportista con tarifas visibles al usuario final, confirma primero con tu Account Representative que ese caso de uso está permitido en tu contrato.

El siguiente paso práctico es simple: antes de escribir una línea de integración, pide a tu Account Representative de UPS confirmación por escrito de qué APIs tiene aprobadas tu cuenta y en qué países, y programa ya en tu calendario una revisión trimestral de las notas de release del Developer Kit. Esa única rutina evita la mayoría de los incidentes de producción que no son culpa del código, sino de un cambio que nadie leyó a tiempo.