# 🚀 API GPS - GPSPHONNEX

API REST para el sistema de monitoreo GPS en tiempo real, basada en la lógica del sistema original GPSPHONNEX.

## 📋 Endpoints Disponibles

### 1. **Empresas y Flotas**
- **URL:** `/api/companies-flotas.php`
- **Método:** GET
- **Parámetros:**
  - `tipo` (opcional): `empresas`, `flotas`, `all` (default: `all`)
  - `id_empresa` (opcional): Filtrar flotas por empresa

**Ejemplo:**
```
GET /api/companies-flotas.php?tipo=all
GET /api/companies-flotas.php?tipo=flotas&id_empresa=5465
```

### 2. **Lista de Vehículos**
- **URL:** `/api/vehicles.php`
- **Método:** GET
- **Parámetros:**
  - `id_empresa` (opcional): Filtrar por empresa
  - `id_flota` (opcional): Filtrar por flota
  - `limit` (opcional): Límite de resultados (default: 100)
  - `offset` (opcional): Offset para paginación (default: 0)

**Ejemplo:**
```
GET /api/vehicles.php?id_empresa=5465&id_flota=1579
```

### 3. **Ubicaciones en Tiempo Real**
- **URL:** `/api/vehicle-locations.php`
- **Método:** GET
- **Parámetros:**
  - `id_empresa` (opcional): Filtrar por empresa
  - `id_flota` (opcional): Filtrar por flota
  - `id_vehiculos` (opcional): Lista de IDs separados por comas
  - `include_inactive` (opcional): `true`/`false` (default: `false`)

**Ejemplo:**
```
GET /api/vehicle-locations.php?id_empresa=5465
GET /api/vehicle-locations.php?id_vehiculos=123,456,789
```

### 4. **Búsqueda por Placa**
- **URL:** `/api/vehicle-search.php`
- **Método:** GET
- **Parámetros:**
  - `placa` (requerido): Placa del vehículo

**Ejemplo:**
```
GET /api/vehicle-search.php?placa=A1F-833
```

### 5. **Información Completa del Vehículo**
- **URL:** `/api/vehicle-info.php`
- **Método:** GET
- **Parámetros:**
  - `placa` (opcional): Placa del vehículo
  - `id_vehiculo` (opcional): ID del vehículo

**Ejemplo:**
```
GET /api/vehicle-info.php?placa=A1F-833
GET /api/vehicle-info.php?id_vehiculo=123
```

## 🗄️ Estructura de Base de Datos

### Tablas Principales:
- **`vehiculo`**: Información básica de vehículos
- **`recorrido`**: Datos GPS en tiempo real
- **`empresa`**: Información de empresas
- **`flota`**: Información de flotas
- **`chofer`**: Información de conductores
- **`modelo_gps`**: Modelos de dispositivos GPS

### Campos Clave:
- **Ubicación:** `co_coordx` (latitud), `co_coordy` (longitud)
- **Velocidad:** `re_velocidad`
- **Tiempo GPS:** `f_gps_actual`
- **Estado:** `state` ('0' = activo)

## 🚦 Estados de Vehículos

| Estado | Descripción | Condición |
|--------|-------------|-----------|
| `parado` | Vehículo detenido | Velocidad = 0 |
| `sinCobertura` | Sin datos recientes | > 30 min sin datos |
| `excesoVelocidad` | Excede límite | Velocidad ≥ 90 km/h |
| `transmisionNormal` | Funcionamiento normal | Datos recientes, velocidad normal |
| `mantenimiento` | En mantenimiento | Estado especial |

## ⚙️ Configuración

### Parámetros de Configuración:
- **Intervalo de actualización:** 5 segundos
- **Límite de velocidad:** 90 km/h
- **Timeout de cobertura:** 30 minutos
- **Máximo vehículos por consulta:** 100

### Zona Horaria:
- Ajuste automático: +5 horas (Lima, Perú)

## 📊 Formato de Respuesta

Todas las respuestas siguen el formato JSON estándar:

```json
{
  "status": "success|error",
  "message": "Mensaje descriptivo",
  "data": { ... },
  "timestamp": "2025-01-13 16:45:00",
  "api_version": "1.0"
}
```

## 🧪 Pruebas

### Archivo de Prueba:
- **URL:** `/api/test-api.php`
- **Parámetros:** `test` (opcional): `vehicles`, `locations`, `info`, `search`, `companies`, `all`

**Ejemplo:**
```
GET /api/test-api.php?test=all
```

## 🔒 Seguridad

- Sanitización de entrada automática
- Validación de parámetros requeridos
- Logs de errores detallados
- Conexiones seguras a base de datos

## 📝 Logs

Los errores se registran automáticamente en el log del servidor con:
- Timestamp
- Mensaje de error
- Contexto adicional
- Stack trace (si aplica)

## 🚀 Uso en Frontend

### Ejemplo de integración con JavaScript:

```javascript
// Obtener ubicaciones en tiempo real
async function getVehicleLocations(empresaId, flotaId) {
    try {
        const response = await fetch(`/api/vehicle-locations.php?id_empresa=${empresaId}&id_flota=${flotaId}`);
        const data = await response.json();
        
        if (data.status === 'success') {
            return data.data.vehicles;
        } else {
            console.error('Error:', data.message);
            return [];
        }
    } catch (error) {
        console.error('Error de conexión:', error);
        return [];
    }
}

// Buscar vehículo por placa
async function searchVehicle(placa) {
    try {
        const response = await fetch(`/api/vehicle-search.php?placa=${placa}`);
        const data = await response.json();
        
        if (data.status === 'success') {
            return data.data;
        } else {
            console.error('Error:', data.message);
            return null;
        }
    } catch (error) {
        console.error('Error de conexión:', error);
        return null;
    }
}
```

## 🔄 Actualización en Tiempo Real

Para implementar actualizaciones en tiempo real:

1. **Polling cada 5 segundos:**
```javascript
setInterval(async () => {
    const vehicles = await getVehicleLocations();
    updateMap(vehicles);
}, 5000);
```

2. **WebSocket (futuro):**
- Implementación de WebSocket para actualizaciones instantáneas
- Notificaciones push para alertas críticas

## 📈 Rendimiento

- **Consultas optimizadas** con índices apropiados
- **Paginación** para grandes volúmenes de datos
- **Cache** de consultas frecuentes (futuro)
- **Compresión** de respuestas JSON (futuro)

## 🛠️ Mantenimiento

### Monitoreo:
- Verificar logs de errores regularmente
- Monitorear tiempo de respuesta de consultas
- Validar integridad de datos GPS

### Actualizaciones:
- Backup de base de datos antes de cambios
- Pruebas en entorno de desarrollo
- Documentación de cambios en API

---

**Desarrollado para GPSPHONNEX** 🚀
**Versión:** 1.0
**Última actualización:** 2025-01-13