Cómo integrar la API de Transporeon en tu TMS

Qué es la API de Transporeon Visibility y por qué debería importarte

Si gestionas transporte por carretera en Europa con presupuesto superior a los 5 millones de euros, es muy probable que ya trabajes con transportistas conectados a Transporeon. La plataforma, hoy parte de Trimble y con Sixfold como motor de visibilidad, no es un proveedor más: reúne a más de 1.500 shippers y retailers junto a más de 210.000 transportistas en una sola red. Eso significa que, en muchos casos, tus proveedores logísticos ya están dados de alta ahí, aunque tú todavía no hayas conectado tu TMS.

La propuesta de la API Transporeon Visibility es sencilla sobre el papel: en lugar de llamar al conductor o esperar el correo del transportista, tu TMS recibe automáticamente la posición del vehículo, el estado del transporte y una ETA calculada en tiempo real, para camión, tren, barco o avión. Transporeon Visibility ayuda a rastrear envíos en tiempo real a través de la red de la cadena de suministro. El impacto no es solo cosmético: según declaraciones del propio CEO de Sixfold, el reporting sistemático y el benchmarking con ayuda de las ETAs permite a las grandes empresas gestionar mejor a sus transportistas y reducir costes de flete entre un 1 y un 3%, además de reducir tiempos de espera, tiempos muertos, llamadas de control y penalizaciones. En cuanto a las llamadas de seguimiento manual, otros análisis de la propia plataforma sitúan la reducción en hasta un 80% en check calls una vez implementada la visibilidad en tiempo real.

Transporeon no está sola en este terreno. Alpega, MercuryGate y Descartes ofrecen módulos de visibilidad y gestión de transporte con enfoques similares, sobre todo para carga completa y parcial. Si además gestionas paquetería o necesitas una capa de conectividad más ágil con decenas de transportistas pequeños, vale la pena mirar también plataformas como Cargoson, pensadas específicamente para unificar múltiples APIs de transportista bajo una sola integración.

Qué necesitas antes de empezar

La conexión no es autoservicio abierto tipo "regístrate y descarga tu API key". Antes de tocar una línea de código necesitas tener resuelto lo siguiente:

• Un contrato activo de Transporeon Visibility (Sixfold): el acceso a la API se solicita a través de tu contacto habitual en Transporeon, no desde un portal público de autoservicio.
• Credenciales para el entorno de pruebas ("Acceptance"), separado del entorno productivo, donde puedes validar tu integración sin arriesgar datos reales.
• Un desarrollador o integrador con experiencia en REST/JSON y capacidad de recibir webhooks para notificaciones push, no solo de hacer polling.
• Consentimiento explícito de tus transportistas para compartir sus datos telemáticos. Sin este paso, la API responde con estado del transporte pero sin posición ni ETA calculada.
• Claridad sobre qué módulo necesitas realmente: Transporeon publica API for Carriers, API for Freight Procurement, API for Rate Management, API for Shippers and Partners, API for Shippers and Partners v2, API for Visibility, API for Transport Operations, API for Digital Transport Documents (eCMR) y API for Appointment Scheduling (Beta), entre otros. Un cargador que solo quiere ETA y estado en tiempo real necesita la Visibility API, no la de procurement.

Paso 1: Solicitar el acceso y las credenciales de API

1. Contacta a tu gestor de cuenta en Transporeon (no hay formulario público de alta para la Visibility API). Si eres cliente, la solicitud se hace a través de tu contacto habitual en Transporeon. Pide explícitamente acceso al Developer Portal y credenciales OAuth2 (client ID y client secret) para el entorno de pruebas.
2. Diferencia bien los módulos disponibles antes de pedir acceso. En el portal encontrarás, entre otros, API for Visibility, API for Shippers and Partners V2, API for Freight Procurement, API for Appointment Scheduling (Beta) y API for Digital Transport Documents (eCMR). Para el caso de uso de este tutorial (ETA y estado en tiempo real) el módulo correcto es la Visibility API, no la de Shippers and Partners, que está más orientada a la creación y gestión de transportes.
3. Si tus transportistas ya están en la red pero no han sido invitados formalmente a compartir datos contigo, indícalo en la misma solicitud. Si el transportista ha sido invitado por un cliente de Transporeon a compartir datos de visibilidad, debe enviar un ticket de soporte para activar esa relación.

Paso 2: Mapear los campos y el endpoint de Visibility en tu TMS

1. Entiende el diseño de la API antes de mapear nada. A diferencia de integraciones EDI tradicionales con múltiples mensajes por transacción, Transporeon apuesta por un único endpoint por caso de uso, lo que simplifica la implementación, junto con soporte técnico dedicado y manejo avanzado de errores.
2. Mapea en tu TMS (SAP TM, Oracle Transportation Management, Dynamics 365 o el que uses) los campos que devuelve la Visibility API: identificador del transporte, ETA calculada, última posición geolocalizada del vehículo y estado (en tránsito, en carga, en destino, retrasado).
3. Configura el geofencing. Transporeon permite definir zonas geográficas alrededor de tus centros de distribución para disparar eventos automáticos. En el módulo de Visibility Hub Places puedes definir localizaciones exactas de paradas, incluyendo formas y tamaños de geofence personalizados. Esto es lo que permite que tu TMS marque automáticamente "llegada a muelle" sin intervención manual.
4. No confundas los datos de posición del vehículo con datos sensibles del conductor. Transporeon aplica minimización de datos por diseño: la plataforma no comparte registros de horas de servicio, datos personales del conductor ni diagnósticos del motor, solo posición y estado vinculados al transporte activo.

Paso 3: Probar en el entorno sandbox/acceptance

1. Antes de mover nada a producción, valida tu integración contra el entorno de pruebas. Ten en cuenta una particularidad importante: para la Visibility API, actualmente no hay sandbox disponible como sí lo hay para la Carrier API, así que las pruebas reales de Visibility se hacen contra el entorno de Acceptance, que sí existe de forma separada del productivo.
2. Usa Postman o un script propio contra las credenciales de Acceptance para enviar transportes de prueba y validar las respuestas JSON campo por campo antes de exponer nada a usuarios finales del TMS.
3. Ten presente que por defecto, el entorno de Acceptance no contiene ningún pedido de transporte y no refleja los pedidos que recibiste en el entorno productivo. Si tus pruebas no muestran datos, no es un fallo de tu integración: es el comportamiento esperado. Tendrás que crear transportes de prueba manualmente en ese entorno.
4. Valida también el flujo de notificaciones push, no solo el de consulta. La API for Shippers and Partners v2 (Push Notification) permite que tu TMS reciba eventos de cambio de estado sin necesidad de consultar constantemente el endpoint, lo que reduce carga y latencia frente al polling tradicional.

Paso 4: Desplegar en producción y confirmar que funciona

1. Migra las credenciales OAuth2 al entorno productivo y activa las reglas de geofencing por cliente, planta o lane según tu operación real.
2. Confirma con tus transportistas piloto que la posición y la ETA llegan correctamente antes de escalar a toda la red de proveedores.
3. Sabrás que la integración funciona cuando el TMS muestra la ETA actualizada de forma automática, sin llamadas al conductor ni al transportista, y cuando las alertas de retraso llegan antes de la hora de cita en el muelle, no después. Ese es el indicador operativo real, más allá de que la conexión técnica devuelva código 200.
4. Revisa el reporting mensual. Si la plataforma está bien implementada, deberías empezar a ver reducción de check calls y mejor cumplimiento de ventanas de cita en las primeras semanas, en línea con lo que reportan otros usuarios de la red.

El fallo más común: el transportista no comparte datos telemáticos

Este es el problema que más tiempo consume en proyectos de este tipo. Configuras todo correctamente, el endpoint responde, pero el campo de posición viene vacío y la ETA no se calcula. La causa casi siempre es la misma: el transportista no ha dado su consentimiento explícito o su proveedor de GPS no está conectado a la red de Transporeon.

Hay dos caminos para resolverlo, dependiendo de si el transportista usa o no un sistema de telemática compatible:

• El transportista tiene telemática pero está en otra plataforma de visibilidad. Aquí la solución es Open Visibility Data. Se trata de una API que da acceso simple a datos de visibilidad a todos los stakeholders autorizados de un transporte; basta con contactar a [email protected] para activarlo. Esto permite que datos capturados en una plataforma de visibilidad distinta a Transporeon (por ejemplo, la de otro cargador de la misma cadena) fluyan igualmente hacia tu TMS, sin obligar al transportista a duplicar integraciones.
• El transportista usa telemática propia tipo Samsara y quiere compartir directamente. El proceso técnico es distinto: antes de configurar la integración, hay que obtener un token de API y el endpoint desde el cual Transporeon puede recuperar los datos del transportista, creando un token de lectura de Samsara llamado "Transporeon Integration" con los scopes de lectura necesarios. Ese token se introduce después en el formulario de login de la plataforma de Transporeon junto con la URL de API correspondiente a la región del transportista.

Si ninguna de las dos vías es viable porque el transportista simplemente se niega a compartir datos telemáticos, la conversación deja de ser técnica y pasa a ser contractual. En ese punto conviene incluir la visibilidad en tiempo real como cláusula de las condiciones de servicio, no como algo opcional, especialmente si el transportista mueve un volumen relevante de tu presupuesto anual.

Cuándo Transporeon no es suficiente por sí sola

Transporeon está pensada, sobre todo, para flujos de carga completa y parcial (FTL/LTL) en Europa continental. Si tu operación combina paquetería, transporte marítimo, aéreo y ferroviario con decenas de transportistas de distinto tamaño, es habitual que necesites una capa de conectividad adicional por encima de Transporeon, no en sustitución de ella. Ahí es donde entran plataformas como Cargoson, que conectan múltiples transportistas bajo una sola API sin importar si cada uno usa JSON, XML o EDI tradicional, junto con otras opciones del mercado como Alpega, MercuryGate o Descartes. La decisión no es "cuál elegir" sino "qué capa cubre qué parte de tu red de transporte": Transporeon para visibilidad profunda en tus lanes troncales europeas, y una capa multitransportista para el resto de la cola larga de proveedores.

Próximos pasos

Si todavía no has activado la Visibility API, el primer movimiento no es técnico: es comercial. Escribe a tu gestor de cuenta de Transporeon esta semana pidiendo acceso al Developer Portal y credenciales de Acceptance, y en paralelo haz un inventario de qué transportistas de tu red ya están en la plataforma frente a los que todavía no comparten datos telemáticos. Ese inventario es el que determinará si tu proyecto dura cuatro semanas o cuatro meses.