SYNC_API/sync_api/README.md

API de Monitoreo de Sincronización - Aduanasoft

Sistema de monitoreo de bases de datos SQL Server con API REST desarrollada en FastAPI.

Características

• ✅ API REST completa con FastAPI
• ✅ Conexión robusta a SQL Server con pyodbc
• ✅ Endpoints para monitoreo de nodos individuales y generales
• ✅ Health checks del sistema
• ✅ Información de backups (opcional)
• ✅ Configuración CORS para integración PHP
• ✅ Logging completo
• ✅ Documentación automática con Swagger/OpenAPI
• ✅ Manejo de errores robusto
• ✅ Validación de datos con Pydantic

Estructura del Proyecto

sync_api/
├── main.py                 # Aplicación principal FastAPI
├── requirements.txt        # Dependencias Python
├── .env                   # Variables de entorno
├── models/
│   └── sync_models.py     # Modelos Pydantic para respuestas
├── database/
│   └── connection.py      # Conexión y queries SQL Server
├── routers/
│   ├── nodes.py          # Endpoints de nodos
│   └── health.py         # Endpoints de salud
└── config/
    └── settings.py       # Configuración de la aplicación

Configuración

1. Variables de Entorno

Editar el archivo .env con tus credenciales de SQL Server:

DATABASE_SERVER=tu_servidor
DATABASE_NAME=tu_base_datos
DATABASE_USER=tu_usuario
DATABASE_PASSWORD=tu_password
DATABASE_DRIVER=ODBC Driver 17 for SQL Server

2. Instalación de Dependencias

pip install -r requirements.txt

3. Verificar Driver ODBC

Asegúrate de tener instalado el driver ODBC 17 para SQL Server:

• Microsoft ODBC Driver 17 for SQL Server

Ejecución

Desarrollo

python main.py

Producción con Uvicorn

uvicorn main:app --host 0.0.0.0 --port 8000

Producción con Gunicorn (Linux)

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Endpoints Disponibles

📊 Monitoreo de Nodos

• GET /api/nodes - Lista todos los nodos
• GET /api/nodes/{node_name}/status - Estado específico de un nodo
• GET /api/nodes/{node_name}/backup-info - Información de respaldos

🏥 Health Checks

• GET /api/health - Estado general del sistema
• GET /api/ping - Ping simple

📖 Documentación

• GET /docs - Documentación Swagger UI
• GET /redoc - Documentación ReDoc
• GET / - Información general de la API

Ejemplos de Uso

Estado de un Nodo Específico

curl http://localhost:8000/api/nodes/NODO001/status

Respuesta:

{
  "nodo_sub_nodo": "NODO001",
  "estado_sincronizacion": "Actualizada",
  "ultima_sincronizacion": "2025-11-03T10:30:00",
  "total_clientes": 45,
  "clientes_activos": 42,
  "clientes_inactivos": 3,
  "tiempo_desde_ultima_sync": "2 horas"
}

Lista de Todos los Nodos

curl http://localhost:8000/api/nodes

Health Check del Sistema

curl http://localhost:8000/api/health

Respuesta:

{
  "status": "healthy",
  "database_status": "healthy",
  "total_nodes": 15,
  "nodes_healthy": 12,
  "nodes_attention": 2,
  "nodes_error": 1,
  "last_check": "2025-11-03T12:00:00",
  "uptime": "2h 15m",
  "version": "1.0.0"
}

Integración con PHP

Ejemplo AJAX básico:

// Obtener estado de un nodo
fetch('http://localhost:8000/api/nodes/NODO001/status')
  .then(response => response.json())
  .then(data => {
    console.log('Estado del nodo:', data);
    // Actualizar dashboard
  })
  .catch(error => console.error('Error:', error));

// Health check periódico
setInterval(() => {
  fetch('http://localhost:8000/api/health')
    .then(response => response.json())
    .then(data => {
      updateHealthIndicator(data.status);
    });
}, 30000); // Cada 30 segundos

Ejemplo PHP con cURL:

function getNodeStatus($nodeName) {
    $url = "http://localhost:8000/api/nodes/{$nodeName}/status";
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    }
    
    return null;
}

// Uso
$nodeStatus = getNodeStatus('NODO001');
if ($nodeStatus) {
    echo "Estado: " . $nodeStatus['estado_sincronizacion'];
}

Estados de Sincronización

Estado	Descripción	Acción Recomendada
Actualizada	Funcionando correctamente	Monitoreo normal
Atención	Requiere revisión	Investigar causa
Error	Problema crítico	Acción inmediata

Logging

Los logs se muestran en consola y incluyen:

• Peticiones HTTP entrantes y salientes
• Tiempos de procesamiento
• Errores de conexión a BD
• Estadísticas de consultas

Nivel de logging configurable via LOG_LEVEL en .env:

• DEBUG: Información detallada
• INFO: Información general (por defecto)
• WARNING: Solo advertencias y errores
• ERROR: Solo errores

Monitoreo y Alertas

Métricas Clave a Monitorear:

• Estado de conectividad de la API (/api/ping)
• Estado general del sistema (/api/health)
• Tiempo de respuesta de endpoints
• Errores de conexión a base de datos
• Distribución de estados de nodos

Alertas Sugeridas:

• API no responde en /api/ping
• Base de datos desconectada
• Más del 20% de nodos en estado "Error"
• Tiempo de respuesta > 5 segundos
• Nodo sin sincronizar > 24 horas

Solución de Problemas

Error de Conexión a SQL Server

1. Verificar credenciales en .env
2. Confirmar que SQL Server acepta conexiones
3. Verificar firewall y puertos
4. Comprobar driver ODBC instalado

API no responde

1. Verificar que el puerto 8000 esté disponible
2. Revisar logs de la aplicación
3. Confirmar dependencias instaladas

Errores de CORS

1. Agregar el dominio PHP a allow_origins en main.py
2. Verificar headers permitidos
3. Comprobar métodos HTTP utilizados

Desarrollo y Extensiones

Agregar Nuevos Endpoints:

1. Crear función en router apropiado (routers/nodes.py o routers/health.py)
2. Definir modelo de respuesta en models/sync_models.py
3. Documentar endpoint con docstrings

Optimizaciones Futuras:

• Cache con Redis para consultas frecuentes
• Paginación avanzada para listas grandes
• Filtros adicionales por fecha/cliente
• Websockets para actualizaciones en tiempo real
• Autenticación y autorización

Soporte

Para soporte técnico o mejoras, contactar al equipo de desarrollo de Aduanasoft.

---

Versión: 1.0.0
Desarrollado con: FastAPI + Python 3.12
Base de Datos: SQL Server
Licencia: Propietaria - Aduanasoft