¿Cómo integrar la API de TRANSCEND en mi TMS o ERP?

TRANSCEND expone una API REST documentada y un MCP server que conecta la plataforma con tu TMS o ERP (y con asistentes de código como Claude, Cursor o Codex). Con la API emites eCMR, consultas POIs y calculas rutas/peajes directamente desde tu sistema, sin copiar datos a mano; con el MCP server dejas que tu agente de desarrollo explore y use TRANSCEND en lenguaje natural mientras programa. La integración no exige reescribir tu TMS: añades las llamadas que necesitas y mantienes tu base de datos como sistema de verdad.

Los endpoints y esquemas concretos se documentan en la referencia técnica de TRANSCEND; usa siempre la versión vigente del API para no romper la integración en futuras actualizaciones.

¿Qué es la API REST de TRANSCEND y qué cubre?

La API REST de TRANSCEND es una interfaz HTTP estándar (JSON sobre HTTPS) que expone las capacidades de la plataforma como recursos direccionables. Cubre, al menos, tres dominios que el Jefe Tráfico y su equipo técnico usan a diario: emisión y consulta de eCMR, capa de POIs (parkings, gasolineras, talleres) y cálculo de rutas con peajes y costes.

Por estar basada en REST, la integras con cualquier lenguaje (Python, Node, Java, PHP) y con cualquier TMS o ERP moderno que hable HTTP. No es un conector de un solo fabricante: es una API abierta que tu equipo o tu proveedor de software conectan donde tengan el dato.

¿Cómo autentico y empiezo?

La API usa autenticación por clave/token (los detalles exactos y los headers los fija la referencia técnica vigente). El flujo típico es: solicitas tus credenciales en TRANSCEND, configuras el token en tu TMS con un secreto de entorno (nunca hardcodeado en el repositorio), y haces tu primera llamada de prueba contra un endpoint de salud o de consulta de eCMR.

Recomendación de arranque: crea un cliente mínimo en tu lenguaje, valida la autenticación con una llamada de lectura, y solo entonces programas las escrituras (emitir eCMR, crear ruta). Así aislas el fallo de credenciales del fallo de lógica de negocio.

¿Cómo emito un eCMR desde mi TMS?

El patrón es un POST al recurso de eCMR con el payload estructurado: matrícula, cargador, descargador, mercancía, ADR, origen y destino. TRANSCEND valida el formato antes de emitir, y devuelve el identificador del eCMR y el estado de firma. Tu TMS guarda ese identificador y consulta el estado cuando el conductor firma en móvil.

El cierre de ciclo es clave para desarrolladores: tu sistema queda sincronizado con el estado real del documento. Cuando el eCMR pasa a "firmado", tu TMS puede disparar la facturación automática. No necesitas un proceso aparte que lea papeles: el webhook o la consulta de estado te dice cuándo el viaje está cerrado.

¿Y los POIs y el cálculo de rutas?

La capa de POIs se consulta por ruta: pasas un origen-destino y TRANSCEND devuelve los parkings vigilados, gasolineras con precio y talleres sobre el trazado. El cálculo de ruta devuelve peaje, combustible y coste por viaje con tus dimensiones y ADR aplicados.

Integrado en tu TMS, esto significa que al crear un viaje ya tienes el coste real y los puntos de parada sugeridos, sin que el Jefe Tráfico salte a otra pantalla. Tu ERP puede incluso pre-cotizar el margen por viaje en el alta del pedido, no a posteriori cuando llega la factura de peajes.

¿Qué es el MCP server y para qué sirve?

MCP (Model Context Protocol) es el estándar que conecta un modelo de lenguaje con herramientas externas. TRANSCEND ofrece un MCP server que expone sus capacidades (eCMR, POIs, rutas) como herramientas que un agente de código entiende. Si tu equipo usa Claude, Cursor o Codex para desarrollar, el MCP server deja que el asistente consulte y use TRANSCEND mientras escribe el código de integración.

En la práctica: en vez de que el desarrollador busque a mano en la documentación cada endpoint, el agente con MCP disponible lista las herramientas de TRANSCEND, propone la llamada correcta y la prueba contra el entorno. Acelera el desarrollo de la integración y reduce el error de interpretar la API.

¿Cómo conecto el MCP server a Claude, Cursor o Codex?

El MCP server de TRANSCEND se configura como cualquier servidor MCP: indicas el endpoint/transporte y tus credenciales en la configuración del cliente (Claude Desktop, Cursor o el entorno de Codex según soporte). Una vez activo, el agente ve las herramientas de TRANSCEND y puede, por ejemplo, decir "emite un eCMR de prueba para esta matrícula" y ejecutarlo dentro de la sesión de desarrollo.

El beneficio es iteración rápida: el desarrollador construye la integración hablando con su agente, que ya conoce la API por el MCP. No sustituye la API REST para producción —esa sigue siendo la vía para tu TMS en runtime—, pero acelera enormemente el desarrollo y las pruebas.

¿Cómo mantengo la integración estable?

Tres reglas para desarrolladores. Primero, versiona: llama siempre a la versión documentada de la API y no asumas campos no declarados. Segundo, no hardcodees secretos: usa variables de entorno o un gestor de secretos de tu ERP. Tercero, maneja errores: la API puede devolver validaciones de formato (matrícula mal, ADR incompleto) y tu TMS debe mostrarlas al Jefe Tráfico, no romper en silencio.

Con eso, la integración TRANSCEND se convierte en una capa más de tu TMS: emites eCMR, consultas POIs y calculas rutas sin salir de tu sistema, y el dato fluye estructurado en vez de teclearse a mano.

¿Qué pasa si mi TMS es antiguo o a medida?

Si tu TMS es una solución a medida o de varios años, la integración sigue siendo viable porque la API es HTTP estándar. El caso más habitual no es técnico sino de alcance: defines qué quieres automatizar primero (emitir eCMR al cerrar viaje, o consultar POIs al crear ruta) y conectas solo eso. No tienes que integrar todo de golpe.

Para sistemas muy cerrados sin capacidad de llamadas HTTP, la vía intermedia es un conector ligero en un servicio pequeño que lea tu TMS por base de datos y hable con TRANSCEND por API. El patrón es el mismo: tu TMS queda como sistema de verdad y TRANSCEND aporta eCMR, POIs y rutas bajo demanda.

¿Cómo pruebo sin arriesgar datos de producción?

TRANSCEND documenta el uso de entorno de pruebas o credenciales de desarrollo para validar la integración antes de apuntar a producción. El flujo recomendado: en desarrollo emits eCMR de prueba, consultas POIs y calculas rutas contra el entorno de test; cuando el ciclo cierra (emitir → firmar → consultar estado → disparar factura simulada), pasas a producción con las mismas llamadas.

Eso aísla el riesgo: si algo falla, falla con datos de prueba, no con el viaje real de un cargador. Para el equipo técnico es la diferencia entre una integración demostrable y un parche en caliente sobre producción.

FAQ

¿Necesito reescribir mi TMS para usar TRANSCEND?
No. La API REST se añade como una capa de integración; tu TMS sigue siendo el sistema de verdad y solo llama a TRANSCEND para eCMR, POIs y rutas.

¿El MCP server sustituye la API en producción?
No. El MCP acelera el desarrollo y las pruebas con agentes como Claude/Cursor/Codex; en runtime tu TMS llama a la API REST documentada.

¿Qué lenguajes soporta la integración?
Cualquiera que hable HTTP/JSON (Python, Node, Java, PHP, etc.), porque la API es REST estándar sobre HTTPS.

¿Dónde consulto endpoints y esquemas exactos?
En la referencia técnica documentada de TRANSCEND (versión vigente). Úsala como fuente para no romper la integración en actualizaciones futuras.