API de rastreo GPS con claves individuales por subusuario

Conectar una plataforma de rastreo GPS con aplicaciones externas exige credenciales independientes, permisos claros y respuestas que los equipos de desarrollo puedan procesar. Esta actualización de Secure GPS traslada la administración de la clave API a Mi cuenta, permite que cada subusuario genere su propia clave y limita su acceso a los dispositivos que el administrador le haya asignado.

La misma actualización amplía la API pública para autenticar al usuario mediante su clave, listar dispositivos autorizados, consultar los datos de un equipo, obtener su última ubicación y recuperar ubicaciones o alertas por periodo. Así, una empresa puede integrar Secure GPS con tableros, aplicaciones operativas o procesos de análisis sin compartir la contraseña principal ni conceder acceso a toda la flota.

Claves API individuales administradas desde Mi cuenta

Una clave API es una credencial destinada a identificar una integración. En Secure GPS, su administración pasa de la configuración general a la sección Mi cuenta, de modo que queda asociada al usuario que realizará la conexión.

Cada subusuario puede generar su propia clave. Cuando ese subusuario utiliza la API, conserva el alcance definido por el administrador: solo puede consultar los dispositivos que tiene asignados y que están habilitados. Esto aplica el mismo principio de acceso limitado que utiliza la operación diaria de la cuenta.

Qué problema resuelve

Antes, compartir una sola clave entre varias aplicaciones o personas dificultaba saber qué acceso debía retirarse cuando cambiaba un proveedor, empleado o proceso. Las claves individuales permiten separar responsabilidades. El administrador puede asignar al subusuario únicamente los vehículos necesarios, mientras el integrador utiliza una credencial que no expone la contraseña interactiva de la cuenta.

Aplicación en el mundo real

Una empresa logística puede crear un subusuario para el equipo que desarrolla su tablero de entregas y asignarle solo los vehículos de distribución. La aplicación obtiene una clave propia, consulta esos dispositivos y deja fuera los activos de otras áreas. Si finaliza el proyecto, la organización puede revocar esa clave o retirar las asignaciones sin cambiar las credenciales de los demás usuarios.

Autenticación de la API con usuario y clave API

La API incorpora un flujo de autenticación que recibe el nombre de usuario y la clave API. Cuando las credenciales son válidas, Secure GPS entrega un token temporal que se utiliza como autorización en las solicitudes posteriores.

En esta publicación, el contrato de autenticación es:

• POST /api/Auth/Token
• Cuerpo JSON con los campos obligatorios UserName y APIKey.
• Respuesta correcta con Success, Token y Expires.
• El token emitido tiene una vigencia de 24 horas en esta versión.
• Las credenciales inválidas producen una respuesta de autorización fallida; las solicitudes incompletas o con errores utilizan el formato de error de la API.

El token debe enviarse como credencial de autorización para las rutas protegidas. Un integrador debe solicitar uno nuevo al expirar, evitar exponer la clave API en aplicaciones públicas y transmitir las credenciales únicamente mediante conexiones seguras.

Listar los dispositivos disponibles para el subusuario

GET /api/devices devuelve los dispositivos que el usuario autenticado tiene autorizados. Esta ruta permite construir selectores, sincronizar catálogos operativos o conocer qué identificadores pueden utilizarse en las consultas siguientes.

Cada elemento puede incluir Id, Name, Description, MIN, Tags y Expires. La respuesta utiliza el campo Devices para la colección. El contenido depende de los datos disponibles para cada equipo y de las asignaciones realizadas por el administrador.

GET /api/device/{deviceId} recupera un dispositivo específico dentro de ese mismo alcance. Si el identificador no existe, no está habilitado o no pertenece a los dispositivos autorizados del subusuario, la API rechaza la consulta.

Consultar la última ubicación de un rastreador GPS

GET /api/device/{deviceId}/LastLocation obtiene la ubicación válida más reciente encontrada para el dispositivo autorizado. La respuesta se entrega en LastLocation y puede incluir fecha, latitud, longitud y valores adicionales que el rastreador haya enviado.

Este recurso permite que un tablero externo muestre la posición de un vehículo o que una aplicación operativa consulte el último dato conocido antes de asignar una tarea. “Última ubicación” significa el dato más reciente disponible para la consulta, no una garantía de que el rastreador esté conectado en ese instante. La aplicación debe revisar la fecha del registro para evaluar su vigencia.

Recuperar ubicaciones por un periodo

POST /api/device/{deviceId}/Locations recibe un cuerpo JSON con From y To. Ambos campos son obligatorios y definen el periodo solicitado. En esta versión, cada consulta admite un intervalo máximo de 60 minutos.

La respuesta contiene la colección Locations. Según los datos proporcionados por el rastreador, cada ubicación puede incluir:

• DateTime, Latitude y Longitude.
• Speed, Course, Battery y InactiveSeconds.
• Fuel, Fuel2, Temperature y RPM.
• SensorTime1 a SensorTime4, Milleage y Attributes cuando estén disponibles.

Los campos opcionales no deben asumirse como presentes para todos los modelos. El integrador debe aceptar valores nulos, respetar las unidades configuradas o documentadas y validar el comportamiento con el rastreador real.

Consultar alertas GPS mediante la API

POST /api/device/{deviceId}/Alerts permite recuperar alertas del dispositivo durante un periodo. El cuerpo requiere From y To, admite AlertName como filtro opcional y mantiene el intervalo máximo de 60 minutos para esta versión.

La colección Alerts puede incluir DateTime, Latitude, Longitude, Text, indicadores de notificación por correo o SMS y una lista Alerts con los tipos detectados. Esto permite relacionar el evento con su ubicación y presentar un historial operativo en otra aplicación.

Los nombres de alerta deben corresponder a los valores admitidos por el contrato. La aplicación debe tratar tipos desconocidos de forma tolerante para evitar fallos cuando Secure GPS incorpore nuevas condiciones.

Formato de respuestas, errores y límites

Las respuestas comparten los campos Success y Error, además del objeto o la colección específica de cada ruta. Las solicitudes válidas responden correctamente; datos incompletos, dispositivos no autorizados o periodos inválidos generan errores de solicitud; y un fallo no esperado utiliza una respuesta de error del servicio.

La API aplica límites de uso y puede devolver un error cuando se alcanza la capacidad permitida. Las integraciones deben evitar consultas repetitivas innecesarias, manejar reintentos con espera, registrar errores sin guardar credenciales y dividir periodos largos en intervalos aceptados.

Buenas prácticas para integrar la API de Secure GPS

1. Cree un subusuario dedicado para cada integración o responsabilidad claramente separada.
2. Asigne únicamente los dispositivos necesarios y revise las asignaciones de forma periódica.
3. Genere la clave desde Mi cuenta y guárdela en un almacén de secretos, nunca en código público, capturas, direcciones URL ni registros.
4. Solicite el token con UserName y APIKey, almacénelo solo durante su vigencia y renuévelo al expirar.
5. Valide primero GET /api/devices y utilice únicamente identificadores devueltos para ese usuario.
6. Maneje campos opcionales, respuestas de error, límites de uso y periodos máximos sin asumir que todos los dispositivos entregan los mismos datos.
7. Revoque o regenere la clave cuando cambie el responsable, finalice una integración o exista sospecha de exposición.

Resumen técnico público

• La clave API se genera y revoca desde Mi cuenta y pertenece al usuario que la administra.
• Los subusuarios pueden tener claves individuales cuyo acceso queda limitado a sus dispositivos asignados.
• La autenticación utiliza POST /api/Auth/Token con UserName y APIKey.
• La API publica rutas para listar dispositivos, consultar uno, obtener su última ubicación y recuperar ubicaciones o alertas.
• Las consultas históricas de ubicaciones y alertas admiten periodos de hasta 60 minutos en esta publicación.
• Los nombres de rutas, campos y límites descritos corresponden a esta versión histórica; una integración nueva debe contrastarlos con la documentación pública vigente de Secure GPS.

Esta actualización convierte la API de Secure GPS en una opción más controlada para integrar seguimiento GPS: cada proceso trabaja con su propia identidad, respeta los dispositivos autorizados y obtiene datos estructurados sin compartir las credenciales principales de la cuenta.