Cómo integrar la API de FedEx con tu TMS

Si gestionas transporte y todavía tienes una integración FedEx basada en WSDL, esta es la noticia: ese canal ya no recibe nada nuevo. Y si además mueves carga LTL con FedEx Freight, el mapa cambió por completo en 2026. Esta guía te lleva paso a paso para integrar la API de FedEx con tu TMS, cubriendo autenticación OAuth, los endpoints de Ship, Track, Rate y Address Validation, y el caso particular de FedEx Freight tras su escisión como empresa independiente.

Por qué la integración con FedEx cambió en 2026

FedEx migró de forma definitiva de sus antiguos Web Services basados en SOAP a una plataforma de API REST, y esa migración ya no es opcional. Según la comunicación oficial del fabricante, FedEx ha lanzado sus APIs RESTful que están centradas en una experiencia de cliente modernizada, y el FedEx Web Services (SOAP) está ahora en contención de desarrollo, y todas las nuevas funciones y mejoras solo estarán disponibles en las APIs RESTful. Esto no es una advertencia genérica: FedEx ha confirmado que el entorno de pruebas de Web Services (WS) se desactivará por completo el 31 de diciembre de 2026, fecha tras la cual proveedores y clientes ya no podrán probar integraciones de Web Services.

A esto se suma un segundo cambio estructural, mucho menos comentado en el mundo hispanohablante: la escisión de FedEx Freight. El 1 de junio de 2026, FedEx Freight Holding Company anunció la finalización de su escisión de FedEx Corporation, estableciéndose como una empresa independiente y cotizada públicamente, líder del sector de carga LTL en Norteamérica, operando ahora bajo el símbolo FDXF en la Bolsa de Nueva York. Para quien gestiona transporte desde España o Latinoamérica con envíos combinados de paquetería y carga LTL hacia o desde Estados Unidos, esto significa que ya no existe un único portal de desarrollador. Express y Ground siguen en developer.fedex.com; la carga LTL vive ahora en un portal propio, developer.fedexfreight.com, con credenciales distintas.

Qué necesitas antes de empezar

Antes de tocar una sola línea de código en tu TMS, necesitas tres cosas: una cuenta FedEx activa, acceso al portal de desarrollador correspondiente, y claridad sobre qué credenciales vas a generar. El proceso de registro requiere generar credenciales de API creando una integración para recibir tu Client ID y Secret tanto para sandbox como para producción, y configurar la autenticación OAuth 2.0 para asegurar tus solicitudes.

• Cuenta y Account Number: número de cuenta FedEx activo, obligatorio en cada llamada de envío o tarificación.
• API Key y Secret Key: la Key es el identificador público que acompaña cada cabecera de solicitud; la Secret solo se usa para solicitar el token OAuth y debe guardarse en un vault, nunca en el código del TMS.
• Entorno sandbox: FedEx separa claramente credenciales de prueba y de producción; no mezcles ambas.
• Si operas carga LTL: cuenta adicional en developer.fedexfreight.com, con su propio Client ID y Secret, independiente del de paquetería.
• Mapeo de campos del TMS: documenta de antemano qué campos de origen, destino, peso, dimensiones y tipo de servicio va a enviar tu TMS, porque el Ship API espera una estructura JSON específica, no el XML de SOAP.

Los pasos de la integración

Esta es la secuencia que funciona en la práctica, desde cero hasta producción.

1. Crea la integración y obtén credenciales. Entra en developer.fedex.com, crea una organización, y registra un proyecto. Ahí generas tu API Key y Secret Key, y vinculas el Account Number de facturación. Si vas a actuar como integrador para varios clientes (por ejemplo, si tu empresa centraliza el transporte de varias filiales), FedEx distingue entre un FedEx Shipper, que es una compañía que envía con FedEx e integra sus APIs en sus propias aplicaciones, y un FedEx Integrator Provider, que integra las APIs y ofrece los servicios de FedEx como parte de su propia solución, como una plataforma o un sistema de gestión de transporte.
2. Configura la autenticación OAuth 2.0. Antes de cualquier llamada a Ship, Track, Rate o Address Validation, tu TMS debe solicitar un token contra el endpoint de autenticación usando la API Key y Secret Key. El token caduca, así que tu integración necesita lógica de renovación automática. Un error frecuente aquí es pedir un token nuevo en cada llamada; la propia documentación recomienda tener en cuenta los límites de tasa, evitando solicitar nuevos tokens para cada llamada de API.
3. Mapea el Rate API y el Address Validation API. Antes de generar cualquier etiqueta, valida la dirección del destinatario y cotiza la tarifa. El Address Validation API tiene una particularidad que conviene conocer: completa las direcciones de destinatario incompletas y, en algunos casos, puede añadir información faltante dependiendo de la verificación contra datos de referencia, pero no puede añadir información secundaria faltante como apartamento o número de suite. Si tu TMS permite pedidos con direcciones parciales (habitual en e-commerce B2B), construye una validación previa en tu capa de integración para evitar rebotes en el Ship API.
4. Conecta el Ship API para generar la etiqueta. El endpoint de creación de envío soporta operaciones de una sola pieza o envíos de múltiples bultos (Multiple-Piece Shipping, MPS). En caso de error, la respuesta no es un simple fallo silencioso: si los datos del envío son inválidos o incorrectos, la salida devuelve los errores, advertencias, notas y alertas en la respuesta para que puedan corregirse y el envío pueda revalidarse. Diseña tu TMS para capturar ese bloque de errores y mostrarlo al operador, no solo un mensaje genérico de "fallo de API".
5. Configura el Track API o, mejor, webhooks de seguimiento. La API de tracking básica tiene un límite que debes conocer antes de dimensionar tu arquitectura: el límite de uso es de 100.000 llamadas de API por día, y ese límite aplica por proyecto y por capacidad, es decir, el límite por defecto de cuota Per Capability Per Project (PCPP) para la capacidad Track es de 100.000 solicitudes diarias. Si tu volumen de envíos diarios es alto, hacer polling constante te va a agotar la cuota en horas. La alternativa recomendada es registrar webhooks de Advanced Integrated Visibility para recibir eventos push cuando cambia el estado del envío, en lugar de consultar el estado activamente.
6. Prueba en sandbox antes de confirmar en producción. FedEx ofrece un endpoint de validación previa (Open Ship) que permite detectar errores de dimensión, peso o dirección antes de confirmar el envío real, y corregirlos sin perder la transacción completa.
7. Pasa a producción y monitoriza tus cuotas. Además del límite diario de Track, existe un límite de ráfaga: cada proyecto tiene un límite de tasa de transacción de 1.400 transacciones en un lapso de 10 segundos. Si tu TMS lanza cotizaciones masivas en lote (por ejemplo, al recalcular rutas de toda la flota a primera hora), reparte las llamadas para no disparar un 429.

Caso especial: si trabajas con FedEx Freight (carga LTL)

Desde la escisión, la integración de carga LTL es un proyecto aparte, no una extensión del proyecto de paquetería. El propio portal lo deja claro: el FedEx Freight Integrator Program ofrece un camino guiado a las APIs de FedEx Freight, diseñado para proveedores tecnológicos y logísticos, con acceso simplificado a capacidades de envío, seguimiento y entrega. El catálogo disponible incluye APIs de Rate, Pickup, Tracking, Shipment y Reporting, con nombres de endpoint distintos a los de Express/Ground, aunque el patrón de autenticación OAuth 2.0 es el mismo.

Si tu TMS todavía lanza llamadas SOAP heredadas contra el antiguo sistema combinado de FedEx, no las traduzcas a mano: el propio portal de Freight incluye una herramienta pensada exactamente para esto. Si ya usas SOAP de FedEx o APIs heredadas, este asistente traduce tus llamadas existentes a los nuevos endpoints REST y las valida. Es el punto de partida más rápido si tu equipo de desarrollo no quiere reconstruir el mapeo de campos desde cero.

Cómo saber que la integración funciona

No esperes a que falle un envío real para descubrir un problema de configuración. Antes de dar por cerrado el proyecto, verifica esta checklist:

• El token OAuth se renueva sin devolver error 401 en llamadas consecutivas durante al menos 24 horas de prueba.
• La cotización del Rate API coincide con la tarifa contratada real. Para validar esto en México, compara contra la guía de servicios y tarifas que incluye un resumen de los servicios y las tarifas de lista estándar de FedEx que entrarán en vigor el 5 de enero de 2026 para los servicios nacionales e internacionales de exportación e importación de México.
• La etiqueta se genera en el formato esperado por tu almacén (PDF o ZPL) sin recortes ni campos vacíos.
• El evento de tracking llega vía webhook minutos después del escaneo real, no horas después.
• Las direcciones con información incompleta devuelven un mensaje accionable, no un error genérico de sistema.

Error común y cómo solucionarlo

El fallo más repetido en 2026 no es técnico, es de planificación: seguir operando con credenciales y endpoints SOAP mientras FedEx ya no añade nada nuevo a esa vía. Es tentador posponerlo porque "todavía funciona", pero hay un plazo concreto detrás. En integraciones con sistemas como Epicor Quick Ship, FedEx Web Services será retirado efectivo el 1 de abril de 2026, y los clientes de Quick Ship deben migrar a la API REST para mantener operaciones de envío sin interrupción, y el mensaje de fondo aplica a cualquier TMS: cuando el entorno SOAP se desactive del todo, si permaneces en los Web Services SOAP heredados después de la fecha límite, la tarificación de FedEx fallará.

La solución no es dramática, pero requiere disciplina de proyecto: usa la herramienta de mapeo para traducir las llamadas existentes, corre ambos entornos (REST y legacy) en paralelo durante unas semanas con los mismos pedidos reales, y solo desactiva el canal SOAP cuando hayas confirmado tres ciclos completos de facturación sin discrepancias.

Dónde encaja un TMS multi-transportista

Mantener integraciones punto a punto con FedEx, UPS, SEUR, DHL Express y cada transportista regional que uses tiene un coste de mantenimiento que crece con cada migración de API, no solo con cada transportista nuevo. Por eso muchos cargadores con presupuestos de transporte superiores a los 5 millones de euros centralizan esta conectividad en un TMS multi-transportista que ya trae los conectores construidos y mantenidos por el proveedor, soluciones como Cargoson, Transporeon, MercuryGate o EasyPost son ejemplos habituales. La ventaja no es solo ahorrarte el trabajo de la primera integración, sino no tener que volver a repetir este ejercicio cada vez que un transportista anuncia una migración de plataforma o, como en el caso de FedEx Freight, una escisión societaria completa.

Próximo paso

Si tu equipo todavía no ha hecho el inventario de qué llamadas SOAP siguen activas en tu TMS, empieza por ahí esta semana. Haz una lista de cada endpoint que use Tracking, Address Validation o Validate Postal Codes bajo WSDL, confirma cuáles tienen equivalente directo en el catálogo REST, y fija una fecha interna de corte anterior al cierre definitivo del entorno de pruebas de FedEx. Si además mueves carga LTL, trata el registro en developer.fedexfreight.com como un proyecto independiente desde el primer día, con su propio responsable y su propio calendario de pruebas.