JSON API V3.0- SATELITALES DE COLOMBIA

La API de Satelitales de Colombia es desarrollada con el fin de permitir que los contratantes o cualquier tercero autorizado por nuestros clientes pueda obtener información en tiempo real de la posición y cualquier otro evento monitoreado por nuestra plataforma de rastreo.

Para tener acceso al servicio el cliente titular del, o los vehículos debe realizar la solicitud con plataforma o en nuestras oficinas donde nos brindará la información correspondiente para entablar comunicación con el área encargada de la integración y las placas que se homologarán mediante la API.

Posteriormente se enviará un correo desde el área de soporte <soporte@satelitalesdecolombia.com>, este contendrá la información correspondiente para la identicificación de usuario <id>, la llave de acceso a la API <key> y los los dispositivos autorizados por el cliente, caracterizados mediante el número de placa y el identificador único del dispositivo <imei>. Adjunto se encontrará un archivo tipo JSON con la codificación y el nombre de los eventos monitoreados por nuestro sistema. A continuación se describirá el contenido del correo.

Como se puede observar en el recuadro anterior, el mensaje contiene las credenciales necesarias para realizar las solicitudes a nuestra API web. Dependiendo de la solicitud podrá tener alguno de los siguientes formatos:

SEGUIMIENTO EN TIEMPO REAL (TRACKING)

Vemos que la consulta de seguimiento (tracking) a nuestra API se realiza mediante una solicitud tipo GET convencional, como parámetros de la solicitud están las credenciales y la <placa> o el <imei> correspondiente al vehículo del cual se desea conocer su ubicación y estado. Cabe resaltar que solo es posible obtener la ubicación de un vehículo por consulta. Además, el tiempo mínimo entre cada consulta dela misma <placa>, <imei> o vehículo es de 30 segundos.

También es importarte aclarar que la API solo enviará información recibida en tiempo real, los datos que se obtienen cuando el GPS se sincroniza luego de salir de zonas sin cobertura se almacenan en nuestros servidores pero no son accesibles mediante esta solicitud.

En caso de que alguna de las credenciales sean incorrectas,el IMEI o la Placa no sean válido o el vehículo no se encuentre autorizado por el titular podría recibir como respuesta un error HTTP/1.1 y además una respuesta JSON dando una descripción del error, a continuación se muestran los posible valores que puede tomar.

RESPUESTA A POSIBLES ERRORES

En caso de que la información sea correcta y la solicitud a nuestra API exitosa, la respuesta recibirá como respuesta un objeto JSON con el mismo formato que se muestra a continuación, el primer elemento puede ser "imei" o "placa" dependiendo del formato de la consulta realizada.

POSICIÓN COMO OBJETO (JSON)

➞ "plate" Es el número de placa correspondiente al vehículo del cual se ha consultado su posición.

➞ "imei" es el identificador único de cada dispositivo GPS instalado en el vehículo de interés.

➞ "event" corresponde al código único asignado a cada uno de los eventos monitoreados por nuestro sistema de rastreo. Dicho valor ya ha pasado por un proceso de decodificación y es independiente de la marca o modelo del dispositivo GPS.

➞ "time" hace referencia a la fecha y hora a la cual el dispositivo GPS generó el evento, este dato es representado en formato ISO 8601 y zona horaria "America/Bogota".

➞ "valid" es un valor booleano para identificar si la información capturada en el evento es válida o inválida, lo cual se representa con 1 y 0 respectivamente. Ser inválida significa que pueden haber interferencias, ruido o manipulación del equipo y no permita obtener datos verídicos.

➞ "ignition" representa la intención de encender o apagar el vehículo tomando los valores de "true" cuando el switch es abierto y "false" cuando es cerrado.

➞ "speed" corresponde a la velocidad en km/h que tenía el vehículo a la hora de capturar el evento, este valor es un número entero.

➞ "motion" hace referencia al movimiento del vehículo, tomando los valores de "true" o "false" dependiendo si estaba en movimiento o detenido cuando ocurre el evento.

➞ "distance" corresponde a la distancia recorrida por el vehículo desde el último evento generado representada en kilómetros, valor el cual es un número real.

➞ "course" refiere la dirección en la cual se encuentra el vehículo en relación al norte geográfico, este valor se encuentra en grados de 0 a 359 en sentido horario.

➞ "latitude", la latitud representa una de las coordenadas geográficas usadas para representar la posición de un punto en la superficie terrestre.

➞ "longitude", la longitud junto con la latitud conforman la posición de un objeto o lugar sobre superficie terrestre respecto al meridiano de greenwich y la línea ecuatorial respectivamente.

➞ "gsmsignal" corresponde a la intensidad de la señal del dispositivo GPS en el momento que envía el evento, este valor númerico puede ir de 0 a 100.

➞ "power" representa el voltaje de la batería del vehículo, este valor puede emplearse para determinar si el GPS se encuentra conectado a alimentación externa o si la batería se encuentra descargada.

Es importante aclarar, que cuando el valor de la etiqueta "valid" es "false" no debería tenerse en cuenta para realizar operaciones o cualquier tipo de análisis respecto a los eventos generados por el GPS.

A continuación se presentará los posibles valores puede tomar la etiqueta "event" y su respectiva descripción o mensaje correspondiente. De igual forma en el correo enviado encotrará como archivo adjunto esta información.

De la información anterior es importante resaltar que la etiqueta con el código "RNI" encapsula cualquier evento generado por los dispositivos GPS que no empleamos como referente para la generación de alertas o señales, sin embargo contiene información característica como ignición, velocidad, ubicación y movimiento que son de interés para el rastreo de los vehículos.

HISTORIAL DE RASTREO (HISTORY)

También podemos realizar consulta de historial (history) a nuestra API, esto se realiza mediante una solicitud tipo GET convencional, como parámetros de la solicitud están las credenciales y la <placa> o el <imei> correspondiente al vehículo del cual se desea conocer su ubicación y estado. Tambien los parámetros <startDate>, <startHour>,<endDate> y <endHour>, correspondientes al inicio y finalización del intervalo de la consulta, lo cual no debería superar los 90 minutos y deberá tener el siguiente formato para la fecha 2026-01-15 (AAAA-MM-DD) y el siguiente formato para hora 05:00:05 (HH:MM:SS). Es importante mencionar que solo es posible obtener el historial de un vehículo por consulta. Este mecanismo se implementa para permitir la consulta de información obtenida mediante buffer o almacenamiento en periodos fuera de cobertura.

En caso de que alguna de las credenciales sean incorrectas,el IMEI o la Placa no sean válido o el vehículo no se encuentre autorizado por el titular podría recibir como respuesta un error HTTP/1.1 y además una respuesta JSON dando una descripción del error como se indica en la sección anterior "RESPUESTA A POSIBLES ERRORES".

En caso de que la solicitud sea procesada correctamente obtenda una respuesta como en el siguiente recuadro, la cual corresponde a un array o lista de objetos JSON cada uno con los mismos atributos que el objeto descrito en la sección "POSICIÓN COMO OBJETO JSON".

HISTORIAL COMO LISTA DE OBJETOS DE POSICIÓN (JSON)

Con esta información debería poder interactuar con nuestro servicio de API e interpretar las diferentes respuestas que podrá obtener al realizar una consulta. En caso de tener dificultades o presentar algún error por favor comunicarse con <soporte@satelitalesdecolombia.com>