================================================================================ API DE CREACIÓN DE OT CARTEC - PAQUETE DE DESPLIEGUE ================================================================================ Versión: 1.0.0 Fecha: Diciembre 2025 Estado: Listo para Producción ================================================================================ CONTENIDO DEL PAQUETE ================================================================================ 📁 api_deployment/ ├── 📄 LEEME.md # Descripción general y inicio rápido ├── 📄 IMPLEMENTACION.md # Guía completa de despliegue ├── 📄 package.json # Dependencias de Node.js ├── 📄 env.example # Plantilla de configuración de entorno ├── 📄 .gitignore # Reglas de Git ignore │ ├── 📁 src/ │ └── 📄 index.js # Código fuente de la API (Node.js + Express) │ ├── 📁 sql/ │ ├── 📄 api_procedure.sql # Procedimiento almacenado (REQUERIDO) │ ├── 📄 verify_ot_data.sql # Consultas de verificación │ └── 📄 quick_queries.sql # Consultas de diagnóstico │ ├── 📁 docs/ │ └── 📄 DOCUMENTACION_API.md # Referencia completa de la API │ └── 📁 config/ └── 📄 cartec-api.service # Configuración de servicio systemd ================================================================================ PASOS DE DESPLIEGUE (REFERENCIA RÁPIDA) ================================================================================ 1. Requisitos Previos ✓ Ubuntu 22.04 LTS ✓ Node.js 12+ ✓ MySQL 8.0+ ✓ Acceso root/sudo 2. Desplegar Archivos $ sudo cp -r api_deployment /opt/cartec_api $ cd /opt/cartec_api 3. Configurar $ cp env.example .env $ nano .env # Editar credenciales de BD 4. Instalar Dependencias $ npm install 5. Instalar Procedimiento de Base de Datos $ mysql -u root -p revisa < sql/api_procedure.sql 6. Instalar Servicio $ sudo cp config/cartec-api.service /etc/systemd/system/ $ sudo systemctl daemon-reload $ sudo systemctl enable cartec-api $ sudo systemctl start cartec-api 7. Verificar $ curl http://localhost:3000/api/health ================================================================================ CARACTERÍSTICAS PRINCIPALES ================================================================================ ✅ Creación de OT con Endpoint Único POST /api/ot/create - Crea OT, cliente y vehículos en una sola llamada ✅ Gestión Automática de Clientes - Crea nuevos clientes automáticamente - Actualiza información de contacto de clientes existentes - No requiere registro manual de clientes ✅ Registro de Vehículos - Creación/actualización automática de vehículos - Vincula vehículos a la OT - Soporta múltiples vehículos por OT ✅ Validación de RUT Chileno - Valida formato y dígito verificador - Auto-formatea salida de RUT ✅ Soporte de Proveedores GPS - gpsimple, entel, tattersall, cemin, carflex - Mapeo automático de logos y empresa ✅ Soporte de Tipos de Servicio - instalacion_gps - visita_tecnica - desinstalacion_gps ✅ Soporte de Talleres - cartec (domicilio) - servitattersall ✅ Listo para Producción - Integración con servicio systemd - Manejo de errores y logging - Transacciones de base de datos - Validación de entrada ================================================================================ ENDPOINT DE LA API ================================================================================ URL Base: http://localhost:3000/api Verificación de Salud: GET /api/health Crear OT: POST /api/ot/create Content-Type: application/json Cuerpo de Petición: { "cliente": { "rut": "12345678-5", "nombre": "Nombre Cliente", "direccion": "Dirección", "comuna": "Comuna", "telefono": "+56912345678", "email": "email@example.com" }, "tecnico": { "rut": "11111111-1" }, "servicio": { "presGPS": "gpsimple", "tiposerv": "instalacion_gps", "taller_install": "cartec" }, "vehiculos": [ { "patente": "ABCD12", "marca": "Toyota", "modelo": "Corolla", "color": "Blanco", "anio": 2021 } ] } Respuesta Exitosa (201): { "success": 1, "message": "OT creada correctamente ID: 1656 Vehiculos: 1", "data": { "id_ot": 1656, "rut_cliente": "12345678-5", "rut_tecnico": "11111111-1", "vehiculos_procesados": 1 } } ================================================================================ REQUISITOS DE BASE DE DATOS ================================================================================ Tablas Utilizadas: - OT (Órdenes de Trabajo) - Clientes (Clientes - auto-creados/actualizados) - Tecnicos (Técnicos - deben existir) - Vehiculos (Vehículos - auto-creados/actualizados) - OT_Vehiculos (Enlaces OT-Vehículo) Procedimiento Almacenado: - prc_api_create_OT (DEBE instalarse desde sql/api_procedure.sql) Restricciones de Clave Foránea: - OT.rut_cliente → Clientes.rut_cliente - OT.rut_tecnico → Tecnicos.rut_tecnico - OT_Vehiculos.patente → Vehiculos.patente (El procedimiento las maneja automáticamente) ================================================================================ CONSIDERACIONES DE SEGURIDAD ================================================================================ 1. Configuración de Entorno ✓ Mantener .env seguro (chmod 600) ✓ Nunca hacer commit de .env en git ✓ Usar contraseñas fuertes para base de datos 2. Acceso a Base de Datos ✓ Considerar crear usuario API dedicado ✓ Otorgar solo permisos necesarios (SELECT, INSERT, UPDATE) ✓ Restringir acceso de red a la base de datos 3. Usuario del Servicio ✓ El servicio se ejecuta como www-data (no-root) ✓ Acceso limitado al sistema de archivos ✓ NoNewPrivileges habilitado 4. Seguridad de Red ✓ Configurar firewall si se expone externamente ✓ Considerar usar proxy reverso Nginx con SSL ✓ Implementar limitación de tasa en producción 5. Monitoreo ✓ Revisar logs regularmente: sudo journalctl -u cartec-api ✓ Configurar alertas para fallos del servicio ✓ Monitorear rendimiento de base de datos ================================================================================ PRUEBAS ================================================================================ Verificación de Salud: $ curl http://localhost:3000/api/health Crear OT de Prueba: $ curl -X POST http://localhost:3000/api/ot/create \ -H "Content-Type: application/json" \ -d @peticion_prueba.json Verificar Base de Datos: $ mysql -u root -p revisa < sql/verify_ot_data.sql Verificar Servicio: $ sudo systemctl status cartec-api Ver Logs: $ sudo journalctl -u cartec-api -n 100 ================================================================================ SOLUCIÓN DE PROBLEMAS ================================================================================ El Servicio No Inicia: 1. Verificar logs: sudo journalctl -u cartec-api -n 50 2. Verificar configuración de .env 3. Verificar conectividad de base de datos 4. Asegurar que el puerto 3000 esté disponible Falla la Creación de OT: 1. Verificar procedimiento almacenado: mysql -u root -p revisa -e "SHOW PROCEDURE STATUS WHERE Name = 'prc_api_create_OT';" 2. Verificar que el técnico existe: mysql -u root -p revisa -e "SELECT * FROM Tecnicos WHERE rut_tecnico = '11111111-1';" 3. Revisar logs de la API Errores de Base de Datos: 1. Verificar existencia de tablas 2. Verificar restricciones de clave foránea 3. Probar procedimiento almacenado manualmente 4. Revisar permisos de usuario de base de datos ================================================================================ MANTENIMIENTO ================================================================================ Reiniciar Servicio: $ sudo systemctl restart cartec-api Detener Servicio: $ sudo systemctl stop cartec-api Actualizar Código: $ cd /opt/cartec_api $ # Copiar nuevos archivos $ npm install $ sudo systemctl restart cartec-api Actualizar Procedimiento: $ mysql -u root -p revisa < sql/api_procedure.sql Ver Logs: $ sudo journalctl -u cartec-api -f Limpiar Logs Antiguos: $ sudo journalctl --vacuum-time=7d ================================================================================ ARCHIVOS DE DOCUMENTACIÓN ================================================================================ 📖 LEEME.md Descripción general del paquete, guía de inicio rápido 📖 IMPLEMENTACION.md ⭐ COMENZAR AQUÍ Guía completa de despliegue paso a paso - Requisitos previos - Pasos de instalación - Configuración - Verificación - Solución de problemas 📖 docs/DOCUMENTACION_API.md Referencia completa de la API - Especificaciones de endpoints - Ejemplos de petición/respuesta - Descripción de campos - Códigos de error - Ejemplos de integración (PHP, Python, cURL) 📖 sql/api_procedure.sql ⚠️ REQUERIDO Procedimiento almacenado que maneja la creación de OT DEBE instalarse en la base de datos 📖 sql/verify_ot_data.sql Consultas para verificar la creación de OT 📖 sql/quick_queries.sql Consultas de diagnóstico para solución de problemas ================================================================================ SOPORTE Y RECURSOS ================================================================================ Ubicación de Documentación: /opt/cartec_api/docs/ Ubicación de Logs: journal de systemd (usar journalctl) Archivo de Servicio: /etc/systemd/system/cartec-api.service Configuración: /opt/cartec_api/.env Código Fuente: /opt/cartec_api/src/index.js Procedimiento de Base de Datos: revisa.prc_api_create_OT Puerto: 3000 (configurable en .env) ================================================================================ INFORMACIÓN DE VERSIÓN ================================================================================ Versión de API: 1.0.0 Node.js: >=12.0.0 (16 LTS recomendado) Dependencias: - express: ^4.18.2 - mysql2: ^3.6.5 Base de Datos: - MySQL 8.0+ - Base de datos: revisa Sistema Operativo: - Ubuntu 22.04 LTS (recomendado) - Cualquier Linux con systemd ================================================================================ PRÓXIMOS PASOS ================================================================================ 1. ✅ Leer LEEME.md para descripción general 2. ✅ Seguir IMPLEMENTACION.md paso a paso 3. ✅ Instalar todos los componentes 4. ✅ Probar con verificación de salud y OT de muestra 5. ✅ Revisar DOCUMENTACION_API.md 6. ✅ Configurar monitoreo y alertas 7. ✅ Configurar respaldos (base de datos y .env) 8. ✅ Documentar URL de la API para consumidores ================================================================================ ¡LISTO PARA DESPLIEGUE! 🚀 ================================================================================ Comenzar con: IMPLEMENTACION.md Tiempo estimado de despliegue: 10-15 minutos Para preguntas o problemas, revisar la documentación o verificar logs del servicio. ================================================================================