ATLAS/docs/guias/api-reference.md

Referencia de API

Documentacion de la API REST de ATLAS.

Informacion General

• Base URL: https://atlas.tudominio.com/api/v1
• Autenticacion: JWT Bearer Token
• Formato: JSON
• Documentacion interactiva: https://atlas.tudominio.com/api/docs

Autenticacion

Login

POST /auth/login
Content-Type: application/json

{
  "email": "admin@ejemplo.com",
  "password": "tu_password"
}

Respuesta:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 86400
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJ..."
}

Usar Token

Incluir en todas las peticiones:

Authorization: Bearer eyJ...

---

Vehiculos

Listar Vehiculos (Paginado)

GET /vehiculos

Parametros query:

• activo: boolean - Filtrar por activos
• en_servicio: boolean - Filtrar por en servicio
• grupo_id: integer - Filtrar por grupo
• buscar: string - Buscar por nombre/placa
• skip: integer - Registros a saltar (default: 0)
• limit: integer - Limite de registros (default: 50, max: 100)
• page: integer - Pagina (alternativa a skip)
• pageSize: integer - Items por pagina (alternativa a limit)

Respuesta:

{
  "items": [
    {
      "id": 1,
      "nombre": "Camion-01",
      "placa": "ABC-123",
      "marca": "Kenworth",
      "modelo": "T680",
      "ano": 2021,
      "tipo": "camion",
      "activo": true,
      "en_servicio": true
    }
  ],
  "total": 12,
  "page": 1,
  "pageSize": 50
}

Listar Todos los Vehiculos (Sin paginacion)

GET /vehiculos/all

Retorna todos los vehiculos activos sin paginacion. Util para mapas y selectores.

Respuesta:

[
  {
    "id": 1,
    "nombre": "Camion-01",
    "placa": "ABC-123",
    "activo": true
  }
]

Estadisticas de Flota

GET /vehiculos/fleet/stats

Respuesta:

{
  "total": 12,
  "activos": 10,
  "inactivos": 2,
  "mantenimiento": 1,
  "enMovimiento": 5,
  "detenidos": 4,
  "sinSenal": 1,
  "alertasActivas": 3
}

Ubicaciones Actuales

GET /vehiculos/ubicaciones/actuales

Retorna las ubicaciones actuales de todos los vehiculos.

Obtener Vehiculo

GET /vehiculos/{id}

Crear Vehiculo

POST /vehiculos
Content-Type: application/json

{
  "nombre": "Camion-02",
  "placa": "DEF-456",
  "marca": "Freightliner",
  "modelo": "Cascadia",
  "ano": 2022,
  "tipo": "camion",
  "color": "Blanco",
  "capacidad_carga": 20000,
  "capacidad_combustible": 400,
  "grupo_id": 1,
  "conductor_id": 2
}

Actualizar Vehiculo

PUT /vehiculos/{id}
Content-Type: application/json

{
  "nombre": "Camion-02 Actualizado",
  "conductor_id": 3
}

Eliminar Vehiculo

DELETE /vehiculos/{id}

Obtener Ubicacion Actual

GET /vehiculos/{id}/ubicacion

Respuesta:

{
  "vehiculo_id": 1,
  "lat": 19.4326,
  "lng": -99.1332,
  "velocidad": 45,
  "rumbo": 180,
  "altitud": 2240,
  "motor_encendido": true,
  "bateria": 85,
  "combustible": 72,
  "tiempo": "2026-01-21T10:30:00Z",
  "direccion": "Av. Insurgentes Sur 1234, CDMX"
}

Obtener Historial de Ubicaciones

GET /vehiculos/{id}/historial

Parametros query:

• desde: datetime - Fecha inicio (ISO 8601)
• hasta: datetime - Fecha fin
• intervalo: integer - Segundos entre puntos (para reducir datos)

---

Conductores

Listar Conductores (Paginado)

GET /conductores

Parametros query:

• activo: boolean - Filtrar por activos
• buscar: string - Buscar por nombre, apellido o licencia
• skip: integer - Registros a saltar
• limit: integer - Limite de registros

Listar Todos los Conductores

GET /conductores/all

Retorna todos los conductores activos.

Listar Conductores Disponibles

GET /conductores/disponibles

Retorna conductores activos sin vehiculo asignado.

Crear Conductor

POST /conductores
Content-Type: application/json

{
  "nombre": "Maria",
  "apellido": "Garcia",
  "telefono": "+525512345678",
  "email": "maria@ejemplo.com",
  "licencia_numero": "LIC-123456",
  "licencia_tipo": "C",
  "licencia_vencimiento": "2027-06-15"
}

Generar Codigo de Acceso

POST /conductores/{id}/generar-codigo

Respuesta:

{
  "codigo": "123456",
  "expira": "2026-01-22T10:30:00Z"
}

Obtener Estadisticas

GET /conductores/{id}/estadisticas

Parametros query:

• periodo: string - "hoy", "semana", "mes", "ano"

---

Ubicaciones

Enviar Ubicacion (desde app/dispositivo)

POST /ubicaciones
X-Device-ID: device_123
X-API-Key: api_key_xxx

{
  "lat": 19.4326,
  "lng": -99.1332,
  "velocidad": 45,
  "rumbo": 180,
  "altitud": 2240,
  "precision": 10,
  "bateria": 85
}

Enviar Batch de Ubicaciones

POST /ubicaciones/batch
X-Device-ID: device_123
X-API-Key: api_key_xxx

{
  "ubicaciones": [
    {
      "lat": 19.4326,
      "lng": -99.1332,
      "velocidad": 45,
      "tiempo": "2026-01-21T10:30:00Z"
    },
    {
      "lat": 19.4327,
      "lng": -99.1333,
      "velocidad": 47,
      "tiempo": "2026-01-21T10:30:10Z"
    }
  ]
}

---

Viajes

Listar Viajes

GET /viajes

Parametros query:

• vehiculo_id: integer
• conductor_id: integer
• estado: string - "en_curso", "completado"
• desde: datetime
• hasta: datetime
• skip: integer
• limit: integer

Listar Viajes Activos

GET /viajes/activos

Retorna viajes actualmente en curso.

Iniciar Viaje Manual

POST /viajes/iniciar
Content-Type: application/json

{
  "vehiculo_id": 1,
  "conductor_id": 1,
  "proposito": "Entrega a cliente",
  "lat": 19.4326,
  "lng": -99.1332
}

Obtener Viaje

GET /viajes/{id}

Respuesta:

{
  "id": 1,
  "vehiculo_id": 1,
  "conductor_id": 1,
  "inicio_tiempo": "2026-01-21T06:30:00Z",
  "fin_tiempo": "2026-01-21T11:45:00Z",
  "inicio_lat": 19.4326,
  "inicio_lng": -99.1332,
  "inicio_direccion": "Base Central",
  "fin_lat": 19.5000,
  "fin_lng": -99.2000,
  "fin_direccion": "Cliente Norte",
  "distancia_km": 89.3,
  "duracion_minutos": 315,
  "velocidad_promedio": 48,
  "velocidad_maxima": 82,
  "paradas": 3
}

Obtener Datos para Replay

GET /viajes/{id}/replay

Respuesta:

{
  "viaje_id": 1,
  "puntos": [
    {
      "lat": 19.4326,
      "lng": -99.1332,
      "velocidad": 0,
      "tiempo": "2026-01-21T06:30:00Z"
    },
    {
      "lat": 19.4330,
      "lng": -99.1335,
      "velocidad": 25,
      "tiempo": "2026-01-21T06:30:10Z"
    }
  ],
  "eventos": [
    {
      "tipo": "alerta",
      "tiempo": "2026-01-21T08:45:00Z",
      "descripcion": "Exceso de velocidad: 82 km/h"
    }
  ],
  "paradas": [
    {
      "inicio": "2026-01-21T07:15:00Z",
      "fin": "2026-01-21T07:30:00Z",
      "lat": 19.4500,
      "lng": -99.1500,
      "tipo": "programada"
    }
  ]
}

---

Alertas

Listar Alertas

GET /alertas

Parametros query:

• vehiculo_id: integer - Filtrar por vehiculo
• tipo_alerta_id: integer - Filtrar por tipo
• severidad: string - "baja", "media", "alta", "critica"
• atendida: boolean - Filtrar por estado
• desde: datetime - Fecha inicio
• hasta: datetime - Fecha fin

Obtener Alertas Pendientes

GET /alertas/pendientes

Obtener Estadisticas

GET /alertas/estadisticas

Obtener Configuracion de Alertas

GET /alertas/configuracion

Respuesta:

{
  "tipos": [
    {
      "id": 1,
      "codigo": "EXCESO_VELOCIDAD",
      "nombre": "Exceso de Velocidad",
      "severidad_default": "media",
      "activo": true,
      "notificar_email": true,
      "notificar_push": true,
      "notificar_sms": false
    }
  ],
  "notificaciones": {
    "email_habilitado": true,
    "push_habilitado": true,
    "sms_habilitado": false
  }
}

Actualizar Configuracion de Alertas

PUT /alertas/configuracion

Listar Tipos de Alerta

GET /alertas/tipos

Marcar como Atendida

PUT /alertas/{id}/atender
Content-Type: application/json

{
  "notas": "Contactado conductor, todo OK"
}

---

Geocercas

Listar Geocercas (Paginado)

GET /geocercas

Parametros query:

• activa: boolean - Filtrar por activas
• tipo: string - Filtrar por tipo (circular/poligono)
• categoria: string - Filtrar por categoria

Listar Todas las Geocercas

GET /geocercas/all

Retorna todas las geocercas activas sin paginacion.

Obtener Geocercas en GeoJSON

GET /geocercas/geojson

Retorna todas las geocercas en formato GeoJSON FeatureCollection.

Crear Geocerca Circular

POST /geocercas/circular

Crear Geocerca Poligonal

POST /geocercas/poligono

Crear Geocerca

POST /geocercas
Content-Type: application/json

{
  "nombre": "Zona Norte",
  "tipo": "poligono",
  "coordenadas": [
    {"lat": 19.5, "lng": -99.2},
    {"lat": 19.5, "lng": -99.1},
    {"lat": 19.4, "lng": -99.1},
    {"lat": 19.4, "lng": -99.2}
  ],
  "color": "#22c55e",
  "alerta_entrada": false,
  "alerta_salida": true,
  "velocidad_maxima": 60,
  "vehiculos": [1, 2, 3]
}

Crear Geocerca Circular

POST /geocercas
Content-Type: application/json

{
  "nombre": "Cliente ABC",
  "tipo": "circulo",
  "coordenadas": [{"lat": 19.4326, "lng": -99.1332}],
  "radio_metros": 500,
  "alerta_entrada": true,
  "alerta_salida": true
}

---

Video

Listar Camaras

GET /video/camaras

Obtener URL de Stream

GET /video/camaras/{id}/stream

Respuesta:

{
  "camara_id": 1,
  "webrtc_url": "http://servidor:8889/cam_1_frontal",
  "hls_url": "http://servidor:8888/cam_1_frontal/index.m3u8",
  "estado": "online"
}

Listar Grabaciones

GET /video/grabaciones

Parametros query:

• camara_id: integer
• vehiculo_id: integer
• tipo: string - "continua", "evento", "manual"
• desde: datetime
• hasta: datetime

Solicitar Video Historico

POST /video/grabaciones/solicitar
Content-Type: application/json

{
  "camara_id": 1,
  "desde": "2026-01-21T10:00:00Z",
  "hasta": "2026-01-21T10:30:00Z"
}

---

Combustible

Registrar Carga

POST /combustible
Content-Type: application/json

{
  "vehiculo_id": 1,
  "litros": 45.5,
  "precio_litro": 23.50,
  "odometro": 45678,
  "estacion": "Pemex Centro"
}

Obtener Consumo

GET /combustible/consumo

Parametros query:

• vehiculo_id: integer
• desde: datetime
• hasta: datetime

---

Mantenimiento

Listar Mantenimientos

GET /mantenimiento

Obtener Proximos Vencimientos

GET /mantenimiento/pendientes

Programar Mantenimiento

POST /mantenimiento
Content-Type: application/json

{
  "vehiculo_id": 1,
  "tipo_mantenimiento_id": 1,
  "fecha_programada": "2026-02-01",
  "odometro_programado": 50000,
  "notas": "Cambio de aceite y filtros"
}

Completar Mantenimiento

PUT /mantenimiento/{id}/completar
Content-Type: application/json

{
  "fecha_realizada": "2026-02-01",
  "odometro_realizado": 49850,
  "costo": 1500.00,
  "proveedor": "Taller AutoServ",
  "notas": "Se cambio aceite sintetico"
}

---

Reportes

Estadisticas de Reportes

GET /reportes/stats

Plantillas Disponibles

GET /reportes/templates

Respuesta:

[
  {"id": "viajes", "nombre": "Reporte de Viajes", "descripcion": "Detalle de viajes realizados"},
  {"id": "alertas", "nombre": "Reporte de Alertas", "descripcion": "Resumen de alertas generadas"},
  {"id": "combustible", "nombre": "Reporte de Combustible", "descripcion": "Consumo y cargas de combustible"},
  {"id": "mantenimiento", "nombre": "Reporte de Mantenimiento", "descripcion": "Estado de mantenimientos"}
]

Previsualizar Reporte

POST /reportes/preview
Content-Type: application/json

{
  "tipo": "viajes",
  "fecha_inicio": "2026-01-01",
  "fecha_fin": "2026-01-25"
}

Reportes Programados

GET /reportes/programados

Programar Reporte

POST /reportes/programar
Content-Type: application/json

{
  "tipo": "viajes",
  "frecuencia": "semanal",
  "email_destino": "admin@atlas.com"
}

Obtener Datos de Dashboard

GET /reportes/dashboard

Respuesta:

{
  "vehiculos": {
    "total": 12,
    "en_ruta": 8,
    "detenidos": 2,
    "offline": 1,
    "con_alerta": 1
  },
  "hoy": {
    "km_recorridos": 847,
    "viajes_completados": 8,
    "alertas": 5,
    "combustible_cargado": 250
  },
  "tendencias": {
    "km_vs_ayer": 12,
    "alertas_vs_ayer": -5
  }
}

Generar Reporte

POST /reportes/generar
Content-Type: application/json

{
  "tipo": "recorridos",
  "desde": "2026-01-01",
  "hasta": "2026-01-21",
  "vehiculos": [1, 2, 3],
  "formato": "pdf"
}

Respuesta:

{
  "reporte_id": 1,
  "estado": "procesando",
  "url": null
}

Descargar Reporte

GET /reportes/{id}/descargar

---

POIs (Puntos de Interes)

Listar POIs

GET /pois

Parametros query:

• categoria: string - Filtrar por categoria
• activo: boolean - Filtrar por activos

Listar Todos los POIs

GET /pois/all

Crear POI

POST /pois
Content-Type: application/json

{
  "nombre": "Cliente ABC",
  "categoria": "cliente",
  "latitud": 19.4326,
  "longitud": -99.1332,
  "direccion": "Av. Insurgentes 123"
}

---

Configuracion del Sistema

Obtener Configuracion

GET /configuracion

Respuesta:

{
  "nombre_empresa": "Atlas GPS",
  "timezone": "America/Mexico_City",
  "unidad_distancia": "km",
  "unidad_velocidad": "km/h",
  "limite_velocidad_default": 120,
  "alerta_bateria_baja": 20,
  "alerta_sin_senal_minutos": 30
}

Actualizar Configuracion

PATCH /configuracion
Content-Type: application/json

{
  "nombre_empresa": "Mi Empresa GPS",
  "limite_velocidad_default": 100
}

---

WebSocket

Conexion

const ws = new WebSocket('wss://atlas.tudominio.com/ws/v1/ubicaciones');

ws.onopen = () => {
  // Autenticar
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'eyJ...'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

Eventos de Ubicacion

{
  "type": "vehiculo_ubicacion",
  "vehiculo_id": 1,
  "lat": 19.4326,
  "lng": -99.1332,
  "velocidad": 45,
  "rumbo": 180,
  "tiempo": "2026-01-21T10:30:00Z"
}

Eventos de Alerta

{
  "type": "nueva_alerta",
  "alerta": {
    "id": 123,
    "vehiculo_id": 1,
    "tipo": "exceso_velocidad",
    "severidad": "media",
    "mensaje": "Exceso de velocidad: 87 km/h",
    "tiempo": "2026-01-21T10:30:00Z"
  }
}

---

Codigos de Error

Codigo	Descripcion
400	Bad Request - Datos invalidos
401	Unauthorized - Token invalido o expirado
403	Forbidden - Sin permisos
404	Not Found - Recurso no existe
422	Validation Error - Error de validacion
429	Too Many Requests - Rate limit excedido
500	Internal Server Error

Formato de error:

{
  "detail": "Mensaje de error",
  "code": "ERROR_CODE",
  "errors": [
    {
      "field": "email",
      "message": "Email invalido"
    }
  ]
}

---

Rate Limits

Endpoint	Limite
General	100 req/min
Auth	5 req/min
Ubicaciones	60 req/min
Video Stream	10 req/min

Headers de respuesta:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642771200