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

GET /vehiculos

Parametros query:

• activo: boolean - Filtrar por activos
• grupo_id: integer - Filtrar por grupo
• search: string - Buscar por nombre/placa
• page: integer - Pagina (default: 1)
• per_page: integer - Items por pagina (default: 20)

Respuesta:

{
  "items": [
    {
      "id": 1,
      "nombre": "Camion-01",
      "placa": "ABC-123",
      "marca": "Kenworth",
      "modelo": "T680",
      "ano": 2021,
      "tipo": "camion",
      "conductor": {
        "id": 1,
        "nombre": "Juan Perez"
      },
      "grupo": {
        "id": 1,
        "nombre": "Ruta Norte"
      },
      "estado": "en_ruta",
      "ultima_ubicacion": {
        "lat": 19.4326,
        "lng": -99.1332,
        "velocidad": 45,
        "tiempo": "2026-01-21T10:30:00Z"
      }
    }
  ],
  "total": 12,
  "page": 1,
  "per_page": 20
}

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

GET /conductores

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
• desde: datetime
• hasta: datetime
• estado: string - "en_curso", "completado"

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:

• atendida: boolean
• severidad: string - "info", "media", "critica"
• tipo: string
• vehiculo_id: integer
• desde: datetime
• hasta: datetime

Obtener Alertas Pendientes

GET /alertas/pendientes

Marcar como Atendida

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

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

---

Geocercas

Listar Geocercas

GET /geocercas

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

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

---

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