================================================================================ CARTEC OT CREATION API - DEPLOYMENT PACKAGE ================================================================================ Version: 1.0.0 Date: December 2025 Status: Production Ready ================================================================================ PACKAGE CONTENTS ================================================================================ πŸ“ api_deployment/ β”œβ”€β”€ πŸ“„ README.md # Package overview and quick start β”œβ”€β”€ πŸ“„ IMPLEMENTATION.md # Complete deployment guide β”œβ”€β”€ πŸ“„ package.json # Node.js dependencies β”œβ”€β”€ πŸ“„ env.example # Environment configuration template β”œβ”€β”€ πŸ“„ .gitignore # Git ignore rules β”‚ β”œβ”€β”€ πŸ“ src/ β”‚ └── πŸ“„ index.js # API source code (Node.js + Express) β”‚ β”œβ”€β”€ πŸ“ sql/ β”‚ β”œβ”€β”€ πŸ“„ api_procedure.sql # Stored procedure (REQUIRED) β”‚ β”œβ”€β”€ πŸ“„ verify_ot_data.sql # Verification queries β”‚ └── πŸ“„ quick_queries.sql # Diagnostic queries β”‚ β”œβ”€β”€ πŸ“ docs/ β”‚ └── πŸ“„ API_DOCUMENTATION.md # Complete API reference β”‚ └── πŸ“ config/ └── πŸ“„ cartec-api.service # Systemd service configuration ================================================================================ DEPLOYMENT STEPS (QUICK REFERENCE) ================================================================================ 1. Prerequisites βœ“ Ubuntu 22.04 LTS βœ“ Node.js 12+ βœ“ MySQL 8.0+ βœ“ Root/sudo access 2. Deploy Files $ sudo cp -r api_deployment /opt/cartec_api $ cd /opt/cartec_api 3. Configure $ cp env.example .env $ nano .env # Edit DB credentials 4. Install Dependencies $ npm install 5. Install Database Procedure $ mysql -u root -p revisa < sql/api_procedure.sql 6. Install Service $ sudo cp config/cartec-api.service /etc/systemd/system/ $ sudo systemctl daemon-reload $ sudo systemctl enable cartec-api $ sudo systemctl start cartec-api 7. Verify $ curl http://localhost:3000/api/health ================================================================================ KEY FEATURES ================================================================================ βœ… Single Endpoint OT Creation POST /api/ot/create - Creates OT, client, and vehicles in one call βœ… Automatic Client Management - Creates new clients automatically - Updates existing client contact information - No manual client registration required βœ… Vehicle Registration - Automatic vehicle creation/update - Links vehicles to OT - Supports multiple vehicles per OT βœ… Chilean RUT Validation - Validates format and verification digit - Auto-formats RUT output βœ… GPS Provider Support - gpsimple, entel, tattersall, cemin, carflex - Automatic logo and empresa mapping βœ… Service Type Support - instalacion_gps - visita_tecnica - desinstalacion_gps βœ… Taller Support - cartec (domicilio) - servitattersall βœ… Production Ready - Systemd service integration - Error handling and logging - Database transactions - Input validation ================================================================================ API ENDPOINT ================================================================================ Base URL: http://localhost:3000/api Health Check: GET /api/health Create OT: POST /api/ot/create Content-Type: application/json Request Body: { "cliente": { "rut": "12345678-5", "nombre": "Cliente Name", "direccion": "Address", "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 } ] } Success Response (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 } } ================================================================================ DATABASE REQUIREMENTS ================================================================================ Tables Used: - OT (Γ“rdenes de Trabajo) - Clientes (Clients - auto-created/updated) - Tecnicos (Technicians - must exist) - Vehiculos (Vehicles - auto-created/updated) - OT_Vehiculos (OT-Vehicle links) Stored Procedure: - prc_api_create_OT (MUST be installed from sql/api_procedure.sql) Foreign Key Constraints: - OT.rut_cliente β†’ Clientes.rut_cliente - OT.rut_tecnico β†’ Tecnicos.rut_tecnico - OT_Vehiculos.patente β†’ Vehiculos.patente (Procedure handles these automatically) ================================================================================ SECURITY CONSIDERATIONS ================================================================================ 1. Environment Configuration βœ“ Keep .env secure (chmod 600) βœ“ Never commit .env to git βœ“ Use strong database passwords 2. Database Access βœ“ Consider creating dedicated API user βœ“ Grant only necessary permissions (SELECT, INSERT, UPDATE) βœ“ Restrict network access to database 3. Service User βœ“ Service runs as www-data (non-root) βœ“ Limited file system access βœ“ NoNewPrivileges enabled 4. Network Security βœ“ Configure firewall if exposing externally βœ“ Consider using Nginx reverse proxy with SSL βœ“ Implement rate limiting in production 5. Monitoring βœ“ Check logs regularly: sudo journalctl -u cartec-api βœ“ Set up alerts for service failures βœ“ Monitor database performance ================================================================================ TESTING ================================================================================ Health Check: $ curl http://localhost:3000/api/health Create Test OT: $ curl -X POST http://localhost:3000/api/ot/create \ -H "Content-Type: application/json" \ -d @test_request.json Verify Database: $ mysql -u root -p revisa < sql/verify_ot_data.sql Check Service: $ sudo systemctl status cartec-api View Logs: $ sudo journalctl -u cartec-api -n 100 ================================================================================ TROUBLESHOOTING ================================================================================ Service Won't Start: 1. Check logs: sudo journalctl -u cartec-api -n 50 2. Verify .env configuration 3. Check database connectivity 4. Ensure port 3000 is available OT Creation Fails: 1. Verify stored procedure: mysql -u root -p revisa -e "SHOW PROCEDURE STATUS WHERE Name = 'prc_api_create_OT';" 2. Check technician exists: mysql -u root -p revisa -e "SELECT * FROM Tecnicos WHERE rut_tecnico = '11111111-1';" 3. Review API logs Database Errors: 1. Check table existence 2. Verify foreign key constraints 3. Test stored procedure manually 4. Review database user permissions ================================================================================ MAINTENANCE ================================================================================ Restart Service: $ sudo systemctl restart cartec-api Stop Service: $ sudo systemctl stop cartec-api Update Code: $ cd /opt/cartec_api $ # Copy new files $ npm install $ sudo systemctl restart cartec-api Update Procedure: $ mysql -u root -p revisa < sql/api_procedure.sql View Logs: $ sudo journalctl -u cartec-api -f Clean Old Logs: $ sudo journalctl --vacuum-time=7d ================================================================================ DOCUMENTATION FILES ================================================================================ πŸ“– README.md Package overview, quick start guide πŸ“– IMPLEMENTATION.md ⭐ START HERE Complete step-by-step deployment guide - Prerequisites - Installation steps - Configuration - Verification - Troubleshooting πŸ“– docs/API_DOCUMENTATION.md Complete API reference - Endpoint specifications - Request/response examples - Field descriptions - Error codes - Integration examples (PHP, Python, cURL) πŸ“– sql/api_procedure.sql ⚠️ REQUIRED Stored procedure that handles OT creation MUST be installed in database πŸ“– sql/verify_ot_data.sql Queries to verify OT creation πŸ“– sql/quick_queries.sql Diagnostic queries for troubleshooting ================================================================================ SUPPORT & RESOURCES ================================================================================ Documentation Location: /opt/cartec_api/docs/ Logs Location: systemd journal (use journalctl) Service File: /etc/systemd/system/cartec-api.service Configuration: /opt/cartec_api/.env Source Code: /opt/cartec_api/src/index.js Database Procedure: revisa.prc_api_create_OT Port: 3000 (configurable in .env) ================================================================================ VERSION INFORMATION ================================================================================ API Version: 1.0.0 Node.js: >=12.0.0 (16 LTS recommended) Dependencies: - express: ^4.18.2 - mysql2: ^3.6.5 Database: - MySQL 8.0+ - Database: revisa OS: - Ubuntu 22.04 LTS (recommended) - Any Linux with systemd ================================================================================ NEXT STEPS ================================================================================ 1. βœ… Read README.md for overview 2. βœ… Follow IMPLEMENTATION.md step-by-step 3. βœ… Install all components 4. βœ… Test with health check and sample OT 5. βœ… Review API_DOCUMENTATION.md 6. βœ… Configure monitoring and alerts 7. βœ… Set up backups (database and .env) 8. βœ… Document API URL for consumers ================================================================================ DEPLOYMENT READY! πŸš€ ================================================================================ Start with: IMPLEMENTATION.md Estimated deployment time: 10-15 minutes For questions or issues, review the documentation or check service logs. ================================================================================