Biblioteca de Webservices

API TM Land — Introducción

El propósito de este manual es guiar al usuario en la correcta implementación y uso de la API, proporcionando detalles sobre su configuración, autenticación, estructura de las solicitudes y respuestas, así como ejemplos prácticos para facilitar su integración en los sistemas del cliente.

A lo largo de este documento se hará referencia a la variable URL_BASE, la cual corresponde al siguiente endpoint base de producción:

Verbos HTTP soportados

La API soporta los siguientes verbos, de acuerdo a lo que requiera hacer:

Autenticación

Todo endpoint de la API requiere el header Authorization en el estándar Bearer. Para obtenerlo deberá consumir nuestro servicio de autenticación.

{
  "code": 200,
  "message": "Login Success",
  "result": {
    "refresh_token": "1234",
    "token_empresa": "abcd",
    "cedula": "us123",
    "user": {
      "activo": true,
      "fechaAceptacion": "2018-12-09T22:22:19.802Z[UTC]",
      "fecha_renovar_pass": "2025-10-13Z",
      "id": "111US",
      "object_User_Code": "tms-prueba",
      "object_User_Email": "prueba@correo.com",
      "object_user_Password": "123",
      "persona": "111",
      "puedefirmar": true,
      "puedemodificarcontable": false,
      "restringirvehiculos": false,
      "selected": false,
      "superUser": true,
      "terminosCondiciones": true,
      "usuario_ventas_web": false,
      "usuariotracker": false
    },
    "token": "e5ACb2JYqcDnAQMU750miTB3Lopdb_tTBCw"
  }
}

Métodos Genéricos CRUD

Generalidades

Los datos de tipo Date se enviarán en el siguiente formato: año-mes-día hora:minutos:segundos. Ejemplo: "2025-10-16 13:40:30".

Todos los métodos llevarán los siguientes headers:

{
  "nombre": "prueba",
  "telefono": "1234567",
  "activo": true
}

{
  "id": "123",   // requerido — identificador de la clase
  "nombre": "prueba",
  "telefono": "9876541",
  "activo": true
}

{
  "first": 0,          // requerido — index del primer item a traer
  "size": 10,          // requerido — número total de items a traer
  "filteredBy": {
    "apellido": "Lopez"  // Parámetro:Valor para filtrar
  },
  "sortedBy": "apellido",   // parámetro para ordenar
  "isAscending": true      // orden ascendente (true) o descendente (false)
}

{
  "id": "123"   // requerido — identificador de la clase
}

Otros métodos

{
  "first": 0,
  "size": 10,
  "filteredBy": {
    "apellido": "Lopez",
    "matchMode_apellido": "EXACT"
  },
  "sortedBy": "apellido",
  "isAscending": true
}

{
  "first": 0,
  "size": 10,
  "filteredBy": {
    "apellido": "Lopez"
  },
  "sortedBy": "apellido",
  "isAscending": true
}

[
  {
    "descripcion": "EQUIPO PORTATIL",
    "firmware": "H02",
    "id": "1458",
    "nombre": "G200",
    "parser": "H02",
    "protocolo": "GPRS",
    "puerto": 5013,
    "sensor_bateria": false,
    "sensor_combustible": false,
    "sensor_ignicion": false,
    "sensor_temperatura1": false,
    "soporte_can": false,
    "soporte_ping": false,
    "soporte_pnd": false,
    "soporte_video": false,
    "umbral_de_ignicion": 0.00,
    "usar_hora_motor_dispositivo": false,
    "usar_odometro_dispositivo": false,
    "uuid": "3c0ecee7-f10e-4aab-8aa9-ed67abc1234"
  }
]

{
  "data": {
    "numeroejes": 2,
    "code": 9,
    "ejesremolque": 0,
    "pesobruto": 1500.0,
    "tiporemolque": "",
    "nombre": "prueba"
  }
}

{
  "odometro": 0.0,
  "placa": "GTY086"
}

Vehículos — Métodos CRUD

Un vehículo se compone de múltiples entidades relacionadas que deben guardarse secuencialmente usando los métodos genéricos: Intervalo, Vehículo, Seguros (SOAT, todo riesgo, responsabilidad civil contractual y extracontractual, hidrocarburos), Tanques de combustible y Cámaras.

Crear Intervalo

Se guarda el intervalo con el método Crear y la clase:

Crear Vehículo

Se guarda el vehículo con el método Crear y la clase:

Crear Seguros

Los seguros se guardan con el método Crear y la clase:

Body para guardar SOAT

Body para guardar Póliza todo riesgo

Body para guardar Responsabilidad Civil Contractual

Body para guardar Responsabilidad Civil Extracontractual

Body para guardar Póliza de Hidrocarburos

Crear Tanques de combustible

Se guardan los tanques con el método Crear y la clase:

Crear Cámaras

Se guardan las cámaras con el método Crear y la clase:

Actualizar Vehículo

Para actualizar, se deben enviar los mismos objetos enviados al crear, más el identificador de cada clase. Ejemplo de identificadores por clase:

Documentos Vehículos — CRUD

Previamente se crean el vehículo y sus seguros con los genéricos (ver sección Vehículos). Posteriormente, otros documentos se crean con el método Crear y la clase:

Body — Crear documento controlado

Leer documentos de un vehículo

Se utiliza el método Get View con la vista:

{
  "first": 0,
  "size": 10,
  "filteredBy": {
    "vehiculo": 123
  }
}

Actualizar documentos

Se envían los mismos objetos del crear + el identificador de la clase. El id se obtiene de la vista documentocontrolado_x_persona_vehiculo_view filtrando por el id del vehículo.

Organizaciones — Métodos CRUD

Para crear una organización se deben guardar secuencialmente varias entidades: condiciones de facturación, otra información comercial, la organización propiamente dicha, sus relaciones, sedes, plazos, documentos exigidos y anexos.

1. Condiciones de facturación

Clase: co.com.tmsolutions.tmland.contabilidad.model.Obj_CondicionesFacturacion

2. Otra información comercial

Clase: co.com.tmsolutions.tmland.operaciones.carga.model.Obj_OtraInformacionComercial

3. Guardar relaciones de información comercial

4. Guardar la organización

Clase: co.com.tmsolutions.tmland.maestros.model.Obj_Organization

5. Guardar relaciones de la organización

6. Sedes

Clase: co.com.tmsolutions.tmland.maestros.model.Obj_Sede

7. Plazos por tipo de contrato

Clase: co.com.tmsolutions.tmland.contabilidad.model.Obj_PlazoPorTipoDeContrato

8. Documentos exigidos

Clase: co.com.tmsolutions.tmland.operaciones.carga.model.Obj_DocumentoExigido

9. Otros documentos (anexos)

Clase: co.com.tmsolutions.tmland.gestionhumana.model.Obj_Anexos

10. Productos por cliente

Clase: co.com.tmsolutions.tmland.operaciones.carga.model.Obj_ProductoPorCliente

Actualizar Organizaciones

Se envían los mismos objetos que al crear + el identificador de cada clase:

Personas — Métodos CRUD

Una persona se compone de cuatro entidades que se guardan secuencialmente con los métodos genéricos: la persona propiamente dicha, sus referencias (laborales/familiares), verificaciones de antecedentes y anexos.

1. Persona

Clase: co.com.tmsolutions.tmland.maestros.model.Obj_Persona

2. Referencias

Clase: co.com.tmsolutions.tmland.gestionhumana.model.Obj_ReferenciaPersona

3. Verificación de antecedentes

Clase: co.com.tmsolutions.tmland.maestros.model.Obj_VerificacionAntecedente

4. Otros documentos (anexos)

Clase: co.com.tmsolutions.tmland.gestionhumana.model.Obj_Anexos

Actualizar Personas

Se envían los mismos objetos que al crear, más el identificador de cada clase:

Usuarios — Método CRUD

Previamente debe existir una persona (ver Personas). Luego se crea el usuario con el método Crear y la clase:

Grupos de seguridad por usuario

Body raw (JSON):

{
  "id": "<object_User_Code del usuario creado>",
  "gruposdeseguridad": [
    { "data": { "id": 15 } },
    { "data": { "id": 25 } }
  ]
}

Actualizar usuario

Se envían los mismos objetos del crear + el identificador de la clase:

Planillas de viaje

Leer

Se consume el método genérico Get View/Function data con la siguiente función:

Parámetros de la función

Body

JSON para filtrar por número de viaje:

{
  "first": 0,
  "size": 10,
  "filteredBy": {
    "viaje": 394,
    "matchMode_viaje": "EXACT"
  },
  "sortedBy": null,
  "isAscending": true
}

Respuesta

{
  "data": {
    "DATOS PROPIETARIO": "ALEJANDRO MORENO",
    "codigo": "000066",
    "CIUDAD ORIGEN": "MEDELLIN",
    "CREADOR": "TM SOLUTIONS S.A.S",
    "NOMBRE SEDE": "PRINCIPAL MEDELLIN",
    "valor": 9540.00,
    "PLACA": "GVV062",
    "CANTIDAD TIQUETES": 6,
    "NUMERO INTERNO": "MIMOTO",
    "detalle": "DEDUCCION FONDO DE REPOSICION",
    "fecha planilla": "2024-02-20T19:27:43.523Z[UTC]",
    "fecha viaje": "2024-02-21T03:19:00Z[UTC]",
    "viaje": 394,
    "id": "77475eb3-896c-46d5-91f9-f5d3baa51f47",
    "CIUDAD DESTINO": "CARTAGENA",
    "DATOS CONDUCTOR": "ALEJANDRO MORENO"
  }
}

A lo largo de esta sección se hará referencia a la variable URL_BASE_WS, la cual corresponde al siguiente endpoint base de producción:

Donde {empresa} corresponde al nombre de la empresa cliente (ejemplo: tmsolutions).

Autenticación Webservices

Todo endpoint requiere el header Authorization en estándar Bearer. Para obtenerlo debe consumir el servicio de autenticación.

Método para autenticación

Query Params

Respuesta

{
  "id_persona": "3b67ede9-fb9 . . .",
  "token_ms": "eyJraWQiOiJJRkx5Sk90d. . .",
  "codeuser": "5219. . .",
  "token": "eyJhbGciOiJIUzI1iOiJ0bXNvbHV0aW9. . .",
  "username": "NOMBRE . . ."
}

Códigos de respuesta

Método para refrescar el token

Query Params

Respuesta

Tendrá la misma estructura del método de login:

{
  "id_persona": "3b67ede9-fb9 . . .",
  "token": "eyJhbGciOiJIUzI1iOiJ0bXNvbHV0aW9. . .",
  "username": "NOMBRE . . ."
}

Venta de tiquetes web

La venta de tiquetes se compone de un flujo de métodos de consulta, gestión de sillas, gestión de pasajeros y generación final del tiquete. A continuación se describen todos los endpoints en el orden recomendado de consumo.

Obtener ciudades disponibles

Devuelve las ciudades disponibles para venta de tiquetes.

Headers

Respuesta 200 OK

[
  {
    "city": "BOBAL",
    "department": "Antioquia",
    "id": 3,
    "state": "Antioquia"
  },
  {
    "city": "SANTAFE DE ANTIOQUIA",
    "department": "Antioquia",
    "id": 5042000,
    "state": "Antioquia"
  }
]

Obtener rutas disponibles

Devuelve las rutas posibles para un viaje.

Headers

Respuesta 200 OK

[
  { "destination_id": 5042000, "origin_id": 5001000 },
  { "destination_id": 5656000, "origin_id": 5837000 },
  { "destination_id": 5042000, "origin_id": 5172000 }
]

Obtener viajes disponibles

Devuelve información del viaje.

Headers

Query Params

Respuesta 200 OK

[
  {
    "arrival_date": "2025-03-21",
    "arrival_time": "07:55",
    "available_sits": 18,
    "capacity_sits": 19,
    "company_id": "1",
    "company_name": "TM SOLUTIONS S.A.S",
    "departire_time": "08:30",
    "departure_date": "2025-03-20",
    "numero_interno": "7854",
    "placa": "WBF508",
    "price": 160000.0,
    "price_id": 9,
    "service_type": 17794,
    "travel_id": "1019-5001000-13001000"
  }
]

Obtener tipos de servicio de bus

Trae información sobre el vehículo y sus características.

Headers

Respuesta 200 OK

[
  {
    "aireacondicionado": 1,
    "bano": 1,
    "comida": 0,
    "dosconductores": 0,
    "id": 156,
    "nombre": "PRUEBA TMLAND 3",
    "pantalla": 0,
    "sillareclinable": 0,
    "tomacorriente": 0,
    "tvambiental": 0,
    "wifi": 1
  }
]

Obtener mapa del bus

Devuelve información detallada del viaje incluyendo las sillas disponibles para posteriormente reservar y comprar el tiquete.

Headers

Query Params

Respuesta 200 OK

[
  {
    "destination_id": 13001000,
    "origin_id": 5001000,
    "sectors": [
      {
        "category": "",
        "category_name": "",
        "cells": [
          {
            "category_id": "",
            "column": 1,
            "label": "2",
            "orientation": "",
            "price": 160000.0,
            "row": 1,
            "seat_id": "8caebb74-c793-4910…",
            "state": "disponible",
            "type": "asiento"
          }
        ],
        "columns": 4,
        "floor": "1",
        "id": "1019-1",
        "name": "PISO1",
        "rows": 5
      }
    ],
    "travel_id": "1019-5001000-13001000"
  }
]

Bloquear silla / Desbloquear silla

Permite que, una vez seleccionada la silla, esta permanezca bloqueada durante el proceso (reserva y compra del tiquete) para evitar que paralelamente se realice el mismo proceso sobre la misma silla.

Headers

Query Params

Cuerpo JSON

Array de seat_id. Cada seat_id se obtiene de getMapaBusWS.

["3d261bf6-b3e5-4be6-96c2-b9963d260e1c", "8caebb74-c793-4910-…"]

Respuesta 200 OK

status: 1 (Éxito) / 0 (Fallido).

{ "status": 1 }

Consultar tercero

Consulta si el cliente cuenta con un registro previo en la aplicación TMLand. Si el usuario ya está en la base de datos, se retorna su información para posteriormente crear el usuario.

Headers

Cuerpo JSON

{
  "isorganizacion": false,
  "document": "7890"
}

Respuesta 200 OK — Usuario encontrado

{
  "address": "r8a",
  "city": 5001000,
  "document": "1234567890",
  "document_type": "C",
  "email": "",
  "last_name": "Ochoa",
  "name": "Juan Carlos",
  "phone": ""
}

Respuesta 200 OK — Usuario no encontrado

{
  "message": "ER1",
  "status": 200,
  "valores": {}
}

Crear tercero

Crea un cliente en la aplicación TMLand cuando no existe un registro previo.

Headers

Body

{
  "isorganizacion": false,
  "document_type": "C",
  "document": "1234567890",
  "name": "Juan",
  "last_name": "Pérez",
  "phone": "3001234567",
  "email": "juan.perez@email.com",
  "address": "Calle 123 #45-67",
  "city": 5001000
}

Respuesta 200 OK — Usuario creado

{ "status": 200, "message": "OK" }

Respuesta 200 OK — Usuario ya registrado

{ "status": 200, "message": "ER0" }

Obtener ciudades (maestro)

Obtiene el listado completo de todas las ciudades disponibles en el sistema. Se utiliza principalmente para la recopilación de información de terceros.

Headers

Respuesta 200 OK

[
  {
    "city": "BOBAL",
    "codigomintransport": "",
    "department": "Antioquia",
    "id": 3,
    "state": "Antioquia"
  },
  {
    "city": "SANTAFE DE ANTIOQUIA",
    "codigomintransport": "5042000",
    "department": "Antioquia",
    "id": 5042000,
    "state": "Antioquia"
  }
]

Reservar sillas

Permite reservar sillas para un pasajero en el sistema de tiquetes.

Headers

Cuerpo JSON

{
  "seat": "12345",
  "id_sede": 1,
  "documento": "1001234567",
  "id_transaccion": "TXN123456",
  "facturar_persona": false,
  "organizacion_facturacion": null,
  "persona_facturacion": null,
  "token_talentu": null
}

Respuestas

Generar tiquete (generarTiqueteWS)

Headers

Query Params

Cuerpo JSON

{
  "reference": "TXN123456",
  "status": "APPROVED",
  "payment_link_id": null,
  "customer_email": "cliente@email.com"
}

Respuesta 200 OK — Tiquete generado correctamente

{
  "data": [
    {
      "arrival_date": "2025-12-31",
      "arrival_time": "09:25",
      "departire_time": "10:00",
      "departure_date": "2025-12-30",
      "document": "14336...",
      "number": "0000002840",
      "price": 160000.0,
      "seat": "69ba0628-447e-454f-bb7a-...",
      "travel_id": "1038-...-13001000",
      "url": ""
    }
  ],
  "dataImpresion": [
    {
      "cajero": "TM SOLUTIONS S.A.S",
      "cedula": "1143363015",
      "codigo_barras": "00000...02025",
      "codigo_viaje": "1038",
      "destino": "CARTAGENA (BOLIVAR)",
      "empresa": "TM SOLUTIONS S.A.S",
      "fecha_compra": "01/04/2025 02:16 PM",
      "fecha_viaje": "30/12/2025 10:00 AM",
      "id": 2840,
      "nit": "9003124053",
      "numero": "0000002840",
      "observaciones": "https://tmsolutions.tmsolutions.com.co/tmland",
      "origen": "MEDELLIN (Antioquia)",
      "pasajero": "MARCELA TORRES",
      "puesto": "1",
      "punto_venta": "PRINCIPAL CARTAGENA(CARTAGENA CARTAGENA)",
      "telefono": "",
      "valor": "160,000",
      "valorcontado": true
    }
  ],
  "errores": {}
}

Códigos de error

Cuando hay algún error, la respuesta sigue siendo 200 OK pero el objeto errores contiene alguna de las siguientes claves:

Generar tiquete (generarTiqueteWompi)

Procesa la respuesta de WOMPI. Solo es necesario para la integración con WOMPI y genera un tiquete si el pago fue aprobado.

Headers

Query Params

Cuerpo JSON enviado por Wompi

{
  "event": "transaction.updated",
  "data": {
    "transaction": {
      "id": "1119196-1731682339-79955",
      "amount_in_cents": 160000,
      "reference": "53661bc6b9256e824d5432f3793c…",
      "customer_email": "customer@correo.com",
      "currency": "COP",
      "payment_method_type": "NEQUI",
      "redirect_url": "https://mystore.com.co/payments/redirect",
      "status": "APPROVED",
      "shipping_address": null,
      "payment_link_id": null,
      "payment_source_id": null
    }
  },
  "sent_at": "2025-01-08T16:45:05.000Z"
}

Respuesta 200 OK

{
  "message": "Tiquete generado exitosamente.",
  "status": 1,
  "valores": {
    "id_tiquete": "TIQ123456"
  }
}

Carga

Consultar guías por documento anexo

Retorna una lista de guías que coinciden con el documento anexo ingresado y la empresa a la que pertenece el usuario autenticado.

Headers

Query Params

Retorno

Array de guías con los siguientes atributos:

Las novedades o trazabilidad están dadas por la lista TrazabilidadWS con los siguientes atributos:

Generar guía de transporte

Body

Retorno

TM Tracker

Obtener últimas alertas

Obtiene las últimas alertas generadas por los vehículos asociados a una empresa y un usuario específico. Las alertas se crean en el software TMLand y deben ser configuradas previamente en el dispositivo GPS de cada vehículo (por ejemplo: exceso de velocidad, llegada tarde, abandono de ruta, etc.).

Headers

Query Params

Respuesta 200 OK

[
  {
    "icono": "https://tmland-amazon-store.s3-us-west-2.amazonaws.com/tmland_resources/images/tracker/iconos_movimiento/Ambulance.png",
    "placa": "FNL609",
    "numeroInterno": "4357",
    "fecha": "20250827162039",
    "descripcion": "Abandono de ruta",
    "id": "b6baa58b-ae1c-497d-a5ce-3f65e3fffe98",
    "cliente": "rapidoochoa",
    "sonido": "Alarm-Synth.wav",
    "disparador": "Abandono de ruta",
    "velocidad": 46.0,
    "imei": "866750062483139"
  }
]

Obtener últimas posiciones

Consulta las últimas posiciones reportadas por los dispositivos GPS asociados a los vehículos de una empresa y usuario específico. La información incluye coordenadas, velocidad, estado de ignición, kilometraje, nivel de combustible, entre otros detalles que permiten monitorear en tiempo real la ubicación y condición del vehículo.

Headers

Query Params

Respuesta 200 OK

[
  {
    "Odometer": "480.95",
    "PositionGUID": "589299d4-7…….",
    "PositionID": "589299d4-7ce6-4…….",
    "MessageID": "589299d4-7ce6-40…….",
    "SessionID": "",
    "ClientID": "prueba",
    "ItemID": "456",
    "Lat": "10.376427",
    "Lon": "-75.496518",
    "Speed": "0.00",
    "Direction": "Punto Frío Vista Hermosa, Diagonal 29, Cartagena, Bolívar, Colombia",
    "BatteryLevel": "",
    "ActualDate": "20250710113837",
    "IsValid": "true",
    "Created": "20250710114146",
    "IgnitionStatus": "0",
    "FuelLevel": "",
    "ActualDateUTC": "20250710163837",
    "head": "0.00",
    "grupo": "NUEVO GRUPO PRUEBA",
    "placa": "MOO231",
    "numeroInterno": "N1I2",
    "icono": "https://tmland-amazon-store.s3-us-west-2.amazonaws.com/tmland_resources/images/tracker/dir-stop.png",
    "markerLabel": " N1I2 MOO231 Vel: 0",
    "markerTitle": "2025-07-10 11:38:37 ",
    "protocol": "osmand",
    "tiene_despacho": "N",
    "fuera_zona_disponibilidad": "N",
    "idVehiculo": 159
  }
]