Bearer Token

Incluye el header Authorization en cada request:

Authorization: Bearer <tu_api_key>

Respuestas de error de autenticación

Dónde obtener tu API Key

Inicia sesión en la plataforma GPS → Menú de perfil → User Settings → campo API Hash. Ese valor es tu API Key.

{
  "object": "list",
  "count": 3,
  "data": [
    {
      "id": 200,
      "name": "Camion Ruta Norte",
      "status": "moving",
      "protocol": "teltonika",
      "lat": 4.710989,
      "lng": -74.072092,
      "speed": 68,
      "course": 45,
      "altitude": 2600,
      "last_seen": "2026-06-02 10:35:00",
      "driver": "Juan Perez",
      "address": "Autopista Norte Km 12, Bogota",
      "sensors": [
        { "type": "engine_hours", "name": "Horas motor", "value": "1240 h" },
        { "type": "battery", "name": "Bateria", "value": "13.2 V" }
      ],
      "group": "Flota Bogota"
    }
  ]
}

{ "error": "not_found", "message": "Dispositivo 999 no encontrado." }

Objeto Device

{
  "object": "location",
  "device_id": 200,
  "lat": 4.710989,
  "lng": -74.072092,
  "speed": 68,
  "course": 45,
  "altitude": 2600,
  "status": "moving",
  "address": "Autopista Norte Km 12, Bogota",
  "timestamp": 1748870100,
  "last_seen": "2026-06-02 10:35:00"
}

Objeto Location

Formato de error

{
  "error": "not_found",
  "message": "Dispositivo 999 no encontrado.",
  "docs": "https://developers.gpssoftwarenumberone.com"
}

Códigos HTTP

Rate Limits

La API acepta 100 requests por minuto por IP. Los headers de respuesta indican el estado del límite:

Python — Cliente completo

import requests
from typing import Optional

class GPSClient:
    BASE = "https://developers.gpssoftwarenumberone.com/api"

    def __init__(self, api_key: str):
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Accept": "application/json"
        })

    def get_devices(self) -> list:
        resp = self.session.get(f"{self.BASE}/v1/devices")
        resp.raise_for_status()
        return resp.json()["data"]

    def get_location(self, device_id: int) -> dict:
        resp = self.session.get(f"{self.BASE}/v1/devices/{device_id}/location")
        resp.raise_for_status()
        return resp.json()

    def get_events(self, device_id: Optional[int] = None, limit: int = 50) -> list:
        params = {"limit": limit}
        if device_id:
            params["device_id"] = device_id
        resp = self.session.get(f"{self.BASE}/v1/events", params=params)
        resp.raise_for_status()
        return resp.json()["data"]


# Uso
client = GPSClient("TU_API_KEY")

devices = client.get_devices()
for d in devices:
    loc = client.get_location(d["id"])
    print(f"{d['name']}: {loc['lat']}, {loc['lng']} — {loc['speed']} km/h")

JavaScript (Node.js) — Cliente completo

class GPSClient {
  constructor(apiKey) {
    this.baseUrl = "https://developers.gpssoftwarenumberone.com/api";
    this.headers = {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    };
  }

  async fetch(path, params = {}) {
    const url = new URL(this.baseUrl + path);
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
    const res = await fetch(url, { headers: this.headers });
    if (!res.ok) throw await res.json();
    return res.json();
  }

  getDevices()                    { return this.fetch("/v1/devices"); }
  getDevice(id)                   { return this.fetch(`/v1/devices/${id}`); }
  getLocation(id)                 { return this.fetch(`/v1/devices/${id}/location`); }
  getEvents(params = {})          { return this.fetch("/v1/events", params); }
  getGeofences()                  { return this.fetch("/v1/geofences"); }
}

// Uso
const client = new GPSClient("TU_API_KEY");
const { data: devices } = await client.getDevices();

for (const device of devices) {
  try {
    const loc = await client.getLocation(device.id);
    console.log(`${device.name}: ${loc.lat}, ${loc.lng}`);
  } catch (e) {
    if (e.error === "no_location") console.log(`${device.name}: sin posición`);
  }
}

v1.0.0 — Junio 2026

Lanzamiento inicial de la API pública GPS Tracking.

• Endpoint GET /v1/devices — lista de dispositivos
• Endpoint GET /v1/devices/:id — detalle de dispositivo
• Endpoint GET /v1/devices/:id/location — última posición
• Endpoint GET /v1/geofences — lista de geocercas
• Endpoint GET /v1/events — historial de eventos
• Autenticación Bearer token
• Rate limiting 100 req/min
• Sandbox interactivo

Selecciona un recurso en el menú lateral para ver su documentación detallada.

Generar una API Key

curl -X POST "https://developers.gpssoftwarenumberone.com/api/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"platform_hash":"TU_USER_API_HASH","label":"Mi integracion","expires_in_days":365}'

{
  "object": "api_key",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "gps_live_a1b2c3d4e5f6...",
  "label": "Mi integracion",
  "created_at": 1748822400000,
  "expires_at": 1780358400000,
  "platform_email": "usuario@empresa.com",
  "message": "Guarda esta clave — no se volvera a mostrar completa."
}

Listar tus API Keys

curl "https://developers.gpssoftwarenumberone.com/api/v1/keys" \
  -H "Authorization: Bearer TU_PLATFORM_HASH"

Revocar una API Key

curl -X DELETE "https://developers.gpssoftwarenumberone.com/api/v1/keys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer TU_PLATFORM_HASH"

Formato de las keys

Todas las keys generadas tienen el prefijo gps_live_ seguido de 48 caracteres hexadecimales aleatorios:

gps_live_a1b2c3d4e5f6789012345678901234567890123456789012

Generar una key ahora

Descargar

Importar en Postman

1. Descarga el archivo gps-tracking-api-openapi.yaml
2. Abre Postman → Import → arrastra el archivo
3. Configura la variable api_key con tu user_api_hash
4. Usa demo_gps2024 para probar sin cuenta real

Importar en Swagger UI

Pega la URL de la especificación en editor.swagger.io:

https://developers.gpssoftwarenumberone.com/openapi.yaml

Contenido de la colección

• GET /health — Estado del servicio (sin auth)
• GET /v1/devices — Listar todos los dispositivos
• GET /v1/devices/:id — Detalle de un dispositivo
• GET /v1/devices/:id/location — Última posición GPS
• GET /v1/geofences — Listar geocercas
• GET /v1/events — Historial de eventos con filtros

Base URL

https://developers.gpssoftwarenumberone.com/api

Métodos HTTP

Formato de respuesta

Todas las respuestas son Content-Type: application/json. Las listas incluyen object, count y data. Los errores incluyen error (código), message (descripción) y docs (enlace a documentación).

{ "object": "list", "count": 3, "data": [...] }

{ "error": "not_found", "message": "Dispositivo 999 no encontrado.", "docs": "https://developers.gpssoftwarenumberone.com" }

Headers de respuesta

Cuando se supera el límite

El servidor responde con HTTP 429 Too Many Requests:

{ "error": "rate_limit_exceeded", "message": "Demasiadas solicitudes. Maximo 100 por minuto." }

Buenas prácticas

• Implementa exponential backoff cuando recibas un 429.
• Usa caching local para datos que no cambian frecuentemente (geocercas, lista de dispositivos).
• Prefiere polling de posiciones a intervalos de 30+ segundos.

Parámetros

Ejemplo

curl "https://developers.gpssoftwarenumberone.com/api/v1/events?limit=20&offset=40" \
  -H "Authorization: Bearer TU_API_KEY"

Cuando count en la respuesta es mayor que limit, hay más páginas disponibles.

Filtros disponibles por endpoint

Filtros de fecha

Los campos from y to aceptan ISO 8601:

curl "https://developers.gpssoftwarenumberone.com/api/v1/events?from=2026-06-01T00:00:00Z&to=2026-06-01T23:59:59Z" \
  -H "Authorization: Bearer TU_API_KEY"

Versión actual

Todos los endpoints de la API v1 están bajo el prefijo /v1/:

https://developers.gpssoftwarenumberone.com/api/v1/

Política de versiones

• Las versiones mayores (v1 → v2) pueden tener cambios que rompen compatibilidad.
• Las versiones anteriores se mantienen activas por mínimo 12 meses después de publicar una nueva.
• Los cambios menores (nuevos campos, nuevos endpoints) se agregan sin cambiar la versión.
• Se notifica por Changelog y correo a integradores registrados con 90 días de anticipación.

Niveles del programa

Casos de uso de partners

Sandbox de Technology Partner

Los partners certificados reciben un sandbox dedicado con:

• Flota simulada de 50 dispositivos con posiciones GPS en movimiento
• Historial de eventos de los últimos 90 días
• Geocercas preconfiguradas para pruebas de alertas
• Credenciales independientes de producción
• Reseteo de datos disponible en cualquier momento

Para solicitar acceso, sigue el proceso de aplicación.

Cómo funcionarán

Registras una URL en tu servidor. Cuando un evento ocurre (posición fuera de geocerca, velocidad excedida, ignición activada), la API envía un POST HTTP a tu URL con el detalle del evento en JSON.

{
  "event": "geofence.exit",
  "timestamp": "2026-06-02T14:30:00Z",
  "device": { "id": 1001, "name": "Camion Bogota-01" },
  "geofence": { "id": 42, "name": "Zona Bogota Centro" },
  "location": { "lat": 4.7110, "lng": -74.0721, "speed": 68 }
}

Tipos de eventos planeados

• geofence.enter / geofence.exit — Entrada/salida de geocerca
• speed.exceeded — Velocidad excedida
• ignition.on / ignition.off — Ignición
• device.offline — Dispositivo sin señal
• alarm.triggered — Alarma de pánico o robo

Datos disponibles

• Velocidad — campo speed en km/h en cada posición
• Frenadas y aceleraciones bruscas — eventos de tipo harsh_brake y harsh_accel
• Exceso de velocidad — eventos speed_exceeded con umbral configurable
• Horas de conducción — calculable a partir de eventos de ignición on/off

Ejemplo — calcular km del día

events = client.get_events(device_id=1001, from_date="2026-06-02T00:00:00Z")
km_today = sum(e.get("distance", 0) for e in events)

Patrón recomendado

Consulta GET /v1/events?type=maintenance_due periódicamente y dispara notificaciones en tu sistema cuando el odómetro supere el umbral configurado.

Fuentes de datos

• GET /v1/events con filtro de fecha — historial completo de posiciones
• Campo distance en cada evento de posición
• Acumula por device_id para reporte por vehículo

Flujo típico

1. Llama GET /v1/devices para obtener el estado actual de la flota
2. Para cada dispositivo moving, consulta /location con un intervalo de 30 segundos
3. Usa GET /v1/geofences para mostrar zonas en el mapa
4. Almacena las posiciones en tu base de datos para histórico y reportes

Datos que procesamos vía API

• Posiciones GPS (lat, lng, velocidad, altitud) de dispositivos registrados en tu cuenta
• Eventos de dispositivos (ignición, alertas, geocercas)
• Información de conductores asignados a dispositivos

Tus responsabilidades como integrador

Al usar la API, confirmas que tienes las autorizaciones necesarias de los propietarios y conductores de los vehículos para recopilar y procesar su información de ubicación, de acuerdo con las leyes de protección de datos aplicables en tu jurisdicción.

Para la política completa de privacidad de la plataforma GPS, visita gpssoftwarenumberone.com.

Uso aceptable

• La API es exclusiva para uso con dispositivos registrados en tu cuenta.
• No puedes revender el acceso a la API como un servicio independiente.
• El uso de la API para acceder a datos de otros tenants está prohibido y puede resultar en suspensión inmediata.
• Los integradores deben respetar los rate limits y no implementar mecanismos para eludirlos.

Suspensión de acceso

Nos reservamos el derecho de suspender o revocar credenciales de API en caso de violación de estos términos, abuso del servicio, o actividad que ponga en riesgo la estabilidad de la plataforma.

Mantenimientos programados

Los mantenimientos se notifican con al menos 48 horas de anticipación por correo a integradores registrados. Se realizan preferentemente los domingos entre 02:00-04:00 UTC.