Cómo integrar la API de Maersk en tu TMS

Por qué automatizar el seguimiento de contenedores Maersk (y qué solucionará esta guía)

Si tu equipo revisa el portal de Maersk contenedor por contenedor cada mañana, ya conoces el problema: no escala. Con treinta, cuarenta o cien importaciones activas desde Asia o Europa hacia México, Colombia o España, ese proceso manual consume horas de un analista que podría estar gestionando excepciones reales en lugar de copiar timestamps a un Excel. Esta guía explica cómo integrar la API de Maersk en tu TMS para que la visibilidad de contenedores llegue sola, sin que nadie tenga que iniciar sesión en maersk.com/tracking.

La diferencia entre el portal y la API no es cosmética. La API añade sobre el portal búsquedas masivas, notificaciones tipo webhook, acceso programático a timestamps de eventos y detalles de buque, y la capacidad de integrar los datos de seguimiento directamente en tu TMS o plataforma de visibilidad. Para un cargador con presupuesto de transporte superior a 5 millones de euros, eso se traduce en algo muy concreto: poder calcular demurrage y detention en tiempo real, y dejar de depender de que alguien "vaya a mirar" si el contenedor ya llegó a puerto.

Qué necesitas antes de empezar

Antes de tocar una sola línea de código, necesitas tres cosas resueltas: una cuenta corporativa, un código de cliente Maersk válido, y claridad sobre qué API vas a consumir.

El primer bloqueo habitual es el tipo de cuenta. Si te registras con una cuenta de email gratuita, no podrás usar las Customer APIs de Maersk; hay que registrarse con la dirección de correo corporativa oficial y aportar al menos un código de cliente Maersk. Ese código de cliente no es un capricho burocrático: permite a Maersk confirmar que la solicitud es legítima y está vinculada a una parte autorizada antes de conceder el acceso. Si no lo tienes a mano, puedes obtenerlo contactando a tu contacto comercial local, al equipo de atención al cliente, o a tu Client Program Management partner.

También conviene decidir de entrada el método de conexión. La versión más reciente del estándar DCSA ya incorpora notificaciones push vía Subscription Callback API, así que si tu TMS puede exponer un endpoint propio o una cola de mensajes para recibir eventos entrantes, esa es la ruta recomendada. Si tu operación ya corre sobre flujos EDI consolidados con Maersk, no hace falta migrar todo de golpe: ambos métodos conviven donde el producto lo soporta.

Paso a paso: conectar la API de Maersk a tu TMS

Con la cuenta y el código de cliente listos, el proceso técnico tiene siete pasos bien definidos. Ninguno es trivial, pero tampoco requiere un equipo de integración dedicado durante meses.

1. Registra la app en developer.maersk.com. Cuando creas una app, se genera automáticamente un Consumer Key, que hará las veces de client ID. Al crear la app o añadir un nuevo Consumer Key, puedes vincular hasta 5 códigos de cliente Maersk desde el primer momento. Puedes copiar el Consumer Key al portapapeles, y también ver y copiar su client secret.
2. Solicita el token OAuth 2.0. Maersk usa el flujo de client credentials de OAuth 2.0 para proteger el acceso a sus recursos API, así que envías un POST al endpoint customer-identity/oauth/v2/access_token sobre el host api.maersk.com. La petición incluye el header Consumer-Key con tu client ID, y en el body client_id, client_secret y grant_type=client_credentials. La respuesta devuelve un access_token de tipo Bearer junto con expires_in: 7199, es decir, algo menos de dos horas de validez.
3. Elige la API de tracking adecuada. Maersk ofrece dos APIs de tracking principales: Track and Trace Plus, con historial detallado de hitos por contenedor o B/L, y MEC Tracking, con datos a nivel de evento para contenedores Maersk, Hamburg Süd y Sealand. Si trabajas con contenedores de prefijo SUDU o SEAU heredados de esas marcas legacy, MEC Tracking es la que necesitas.
4. Mapea los hitos DCSA en tu TMS. Booking, gate-in, load, discharge, gate-out: usa el modelo estándar en lugar de inventar tu propia nomenclatura interna. El estándar Track & Trace incluye Information Model, Interface Standard, API Definitions y una Self-Certification Checklist descargables desde DCSA, lo que garantiza consistencia en las definiciones de datos.
5. Configura la suscripción a eventos push. En lugar de que tu TMS haga polling cada hora, activa la Subscription Callback API. La versión 2.2 del estándar incluye la DCSA Subscription Callback API, que permite a los clientes (shippers/consignees) suscribirse para recibir actualizaciones automáticas de eventos de envío por parte de los transportistas. La seguridad se refuerza con headers de subscription-ID y notification-signature, así que valida ambos en tu endpoint receptor antes de procesar el payload.
6. Prueba en sandbox. Usa el API Catalogue, Postman o Swagger Editor para probar las APIs y confirmar que todo funciona antes de construir tu integración. Compara los hitos que devuelve la API contra lo que ves manualmente en el portal, contenedor a contenedor, durante al menos una semana de tráfico real.
7. Activa en producción y verifica. Una vez el sandbox valida correctamente, pasa el flujo a producción y confirma que el TMS actualiza el estado de cada contenedor sin que nadie toque un teclado.

¿Cómo sabes que funcionó? Los eventos de discharge o gate-out deben aparecer en tu TMS en minutos, no en horas, después de que cambien en el portal de Maersk. El desfase entre el evento físico y su reflejo digital suele rondar 2-8 horas para hitos oceánicos, así que si tu integración añade una demora adicional notable sobre ese margen, algo en la suscripción o el polling no está bien configurado.

Errores comunes y cómo resolverlos

Tres fallos aparecen con más frecuencia que el resto, y los tres tienen solución conocida.

Token expirado a mitad de sincronización. Como el token dura 7199 segundos (poco menos de dos horas), cualquier proceso batch que tarde más que eso empezará a fallar con 401 a mitad de camino. La solución es implementar refresco automático antes de cada lote de llamadas, no esperar a que expire para reaccionar.

Eventos de transbordo mal enlazados. Cuando un contenedor pasa por un puerto hub, Maersk no siempre da el mismo nivel de detalle que otras navieras. Los eventos de transbordo aparecen condensados: Maersk típicamente muestra llegada y salida en el hub, pero con menos detalle que carriers como ZIM. Verifica que tu TMS respeta el orden de los tramos: la continuidad de los tramos de transbordo enlazados en orden es uno de los criterios que deberías validar antes de dar por buena la integración.

Código de cliente mal vinculado al Consumer Key. Este es el que más tickets de soporte genera. Maersk actualmente no permite añadir o quitar códigos de cliente de un Consumer Key existente; hay que crear uno nuevo si necesitas ampliar la cobertura. Planifica esto desde el diseño: si sabes que vas a incorporar más filiales o códigos de cliente en los próximos meses, negocia de entrada cuántos códigos necesitas vincular.

Multi-naviera: qué pasa cuando trabajas con Hapag-Lloyd, CMA CGM o MSC además de Maersk

La ventaja real de haber construido esto sobre DCSA en lugar de sobre el formato propietario de Maersk es que el trabajo no se multiplica por cada naviera nueva. Maersk es miembro fundador de DCSA y su output de API mapea de forma limpia al modelo de eventos DCSA; si estás construyendo una integración multi-transportista, sus datos están entre los más fáciles de normalizar junto a Hapag-Lloyd, CMA CGM y ONE.

Esto no es exclusivo de Maersk. Los miembros de DCSA incluyen a MSC, Maersk, CMA CGM, Hapag-Lloyd, ONE, Evergreen, Yang Ming, HMM y ZIM, y la mayoría ya camina en la misma dirección. Ya en 2021, nueve de los principales carriers del sector habían adoptado los estándares abiertos de track and trace desarrollados por DCSA, con cinco de ellos con la API en producción o pruebas. El propio DCSA lo resumía así: una mayoría de sus transportistas miembros ha adoptado los estándares Track & Trace y está proporcionando, o pronto proporcionará, acceso a la API basada en estándares.

En la práctica, esto significa que una vez tienes el mapeo DCSA resuelto para Maersk, añadir Hapag-Lloyd o CMA CGM es repetir el mismo patrón de autenticación y el mismo modelo de eventos, no reinventar la traducción de campos desde cero. Plataformas de gestión de transporte multi-transportista como Cargoson, MercuryGate, Descartes o project44 ya vienen con conectores DCSA preconstruidos, lo que evita mantener internamente esa capa de normalización para cada naviera nueva que sume a tu red.

Construir vs. comprar: cuándo tiene sentido una integración propia

La pregunta real no es si la API de Maersk funciona (funciona), sino quién mantiene la integración cuando cambie de versión, cuando roten los tokens o cuando un webhook empiece a fallar silenciosamente un viernes por la tarde. Los carriers pueden caerse o limitar peticiones en temporada alta, y tu integración necesita lógica de reintento y un plan de respaldo manual para que el tracking no se quede obsoleto sin que nadie lo note. Eso es trabajo de ingeniería continuo, no un proyecto que se cierra una vez.

La integración directa tiene sentido si tu carga está concentrada en dos o tres carriers principales y tienes ancho de banda de ingeniería para mantener las conexiones. Si en cambio tu red incluye una cola larga de navieras, algunas sin API pública, un TMS con conectividad ya construida como Cargoson te ahorra la parte menos visible del trabajo: la que aparece seis meses después, cuando Maersk actualiza su Consumer-Key o DCSA publica una nueva versión del estándar.

Próximos pasos

Antes de dar por cerrada la integración, revisa esta checklist: token OAuth 2.0 funcionando con refresco automático, hitos DCSA mapeados correctamente en tu TMS, suscripción webhook activa y validada contra el sandbox, y al menos una semana de comparación entre lo que muestra la API y lo que muestra el portal manual.

Una vez que Maersk fluye sin intervención manual, el mismo patrón de autenticación OAuth 2.0 y el mismo modelo de eventos DCSA te sirven de plantilla para conectar la siguiente naviera. La parte más pesada del trabajo, entender el estándar, ya está hecha.