JSON API V2.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. La cual tendrá el siguiente formato:

Vemos que la consulta 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 por este medio.

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.

HTTP/1.1 400 Bad Request ➞ { error: 'Debe proporcionar IMEI o una placa válida' }
HTTP/1.1 401 Unauthorized ➞ { error: 'Credenciales inválidas o vehículo no autorizado' }
HTTP/1.1 404 Not Found ➞ { error: 'Posición no encontrada para el IMEI proporcionado' }
HTTP/1.1 404 Not Found ➞ { error: 'Placa no encontrada' }
HTTP/1.1 500 Internal Server Error ➞ { error: 'Error interno en la autenticación' }
HTTP/1.1 500 Internal Server Error ➞ { error: 'Error interno al buscar la posición' }

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.

➞ "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.

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>