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

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

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

**Respuesta**:
```json
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 86400
}
```

### Refresh Token

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

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

### Usar Token

Incluir en todas las peticiones:
```http
Authorization: Bearer eyJ...
```

---

## Vehiculos

### Listar Vehiculos (Paginado)

```http
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**:
```json
{
  "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)

```http
GET /vehiculos/all
```

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

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

### Estadisticas de Flota

```http
GET /vehiculos/fleet/stats
```

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

### Ubicaciones Actuales

```http
GET /vehiculos/ubicaciones/actuales
```

Retorna las ubicaciones actuales de todos los vehiculos.

### Obtener Vehiculo

```http
GET /vehiculos/{id}
```

### Crear Vehiculo

```http
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

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

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

### Eliminar Vehiculo

```http
DELETE /vehiculos/{id}
```

### Obtener Ubicacion Actual

```http
GET /vehiculos/{id}/ubicacion
```

**Respuesta**:
```json
{
  "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

```http
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)

```http
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

```http
GET /conductores/all
```

Retorna todos los conductores activos.

### Listar Conductores Disponibles

```http
GET /conductores/disponibles
```

Retorna conductores activos sin vehiculo asignado.

### Crear Conductor

```http
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

```http
POST /conductores/{id}/generar-codigo
```

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

### Obtener Estadisticas

```http
GET /conductores/{id}/estadisticas
```

**Parametros query**:
- `periodo`: string - "hoy", "semana", "mes", "ano"

---

## Ubicaciones

### Enviar Ubicacion (desde app/dispositivo)

```http
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

```http
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

```http
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

```http
GET /viajes/activos
```

Retorna viajes actualmente en curso.

### Iniciar Viaje Manual

```http
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

```http
GET /viajes/{id}
```

**Respuesta**:
```json
{
  "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

```http
GET /viajes/{id}/replay
```

**Respuesta**:
```json
{
  "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

```http
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

```http
GET /alertas/pendientes
```

### Obtener Estadisticas

```http
GET /alertas/estadisticas
```

### Obtener Configuracion de Alertas

```http
GET /alertas/configuracion
```

**Respuesta**:
```json
{
  "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

```http
PUT /alertas/configuracion
```

### Listar Tipos de Alerta

```http
GET /alertas/tipos
```

### Marcar como Atendida

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

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

---

## Geocercas

### Listar Geocercas (Paginado)

```http
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

```http
GET /geocercas/all
```

Retorna todas las geocercas activas sin paginacion.

### Obtener Geocercas en GeoJSON

```http
GET /geocercas/geojson
```

Retorna todas las geocercas en formato GeoJSON FeatureCollection.

### Crear Geocerca Circular

```http
POST /geocercas/circular
```

### Crear Geocerca Poligonal

```http
POST /geocercas/poligono
```

### Crear Geocerca

```http
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

```http
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

```http
GET /video/camaras
```

### Obtener URL de Stream

```http
GET /video/camaras/{id}/stream
```

**Respuesta**:
```json
{
  "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

```http
GET /video/grabaciones
```

**Parametros query**:
- `camara_id`: integer
- `vehiculo_id`: integer
- `tipo`: string - "continua", "evento", "manual"
- `desde`: datetime
- `hasta`: datetime

### Solicitar Video Historico

```http
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

```http
POST /combustible
Content-Type: application/json

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

### Obtener Consumo

```http
GET /combustible/consumo
```

**Parametros query**:
- `vehiculo_id`: integer
- `desde`: datetime
- `hasta`: datetime

---

## Mantenimiento

### Listar Mantenimientos

```http
GET /mantenimiento
```

### Obtener Proximos Vencimientos

```http
GET /mantenimiento/pendientes
```

### Programar Mantenimiento

```http
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

```http
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

```http
GET /reportes/stats
```

### Plantillas Disponibles

```http
GET /reportes/templates
```

**Respuesta**:
```json
[
  {"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

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

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

### Reportes Programados

```http
GET /reportes/programados
```

### Programar Reporte

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

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

### Obtener Datos de Dashboard

```http
GET /reportes/dashboard
```

**Respuesta**:
```json
{
  "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

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

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

**Respuesta**:
```json
{
  "reporte_id": 1,
  "estado": "procesando",
  "url": null
}
```

### Descargar Reporte

```http
GET /reportes/{id}/descargar
```

---

## POIs (Puntos de Interes)

### Listar POIs

```http
GET /pois
```

**Parametros query**:
- `categoria`: string - Filtrar por categoria
- `activo`: boolean - Filtrar por activos

### Listar Todos los POIs

```http
GET /pois/all
```

### Crear POI

```http
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

```http
GET /configuracion
```

**Respuesta**:
```json
{
  "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

```http
PATCH /configuracion
Content-Type: application/json

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

---

## WebSocket

### Conexion

```javascript
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

```json
{
  "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

```json
{
  "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**:
```json
{
  "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
```