Freight Validator by Invoice

Una herramienta web para validar y calcular el porcentaje de flete respecto al valor de la factura.

Características

✅ Importar archivos - Soporta archivos .xlsx y .csv
✅ Validación automática - Valida número de factura, valor y ciudad de destino
✅ Cálculo de flete - Calcula el porcentaje del flete respecto a la factura
✅ Advertencias - Alerta si el flete supera el 10% del valor de la factura
✅ Interfaz intuitiva - Diseño limpio y responsivo

Requisitos del Archivo

El archivo de entrada debe contener las siguientes columnas:

• numero_factura - Número único de la factura
• valor_factura - Valor monetario de la factura (número positivo)
• ciudad_destino - Ciudad de destino del envío

Ejemplo:

numero_factura	valor_factura	ciudad_destino
FAC-001	150000	Bogotá
FAC-002	200000	Medellín
FAC-003	85000	Cali

Instalación

1. Clonar o descargar el proyecto
2. Instalar dependencias:

npm install

3. Ejecutar el servidor:

npm start

O en modo desarrollo con auto-reload:

npm run dev

4. Abrir en el navegador: http://localhost:3000

Uso

1. Subir archivo: Selecciona un archivo .xlsx o .csv con datos de facturas
2. Seleccionar factura: Elige una factura de la lista
3. Ingresar flete: Introduce el valor del flete/transporte
4. Ver resultado: El sistema calcula el porcentaje y muestra advertencias si es necesario

Estructura del Proyecto

validador-fletes-js/
├── public/
│   ├── index.html       # Página principal
│   ├── app.js          # Lógica del cliente
│   └── style.css       # Estilos
├── src/
│   ├── config/
│   │   └── settings.js # Configuración general
│   ├── controllers/
│   │   └── invoiceController.js # Lógica de rutas
│   ├── routes/
│   │   └── invoiceRoutes.js # Definición de rutas API
│   ├── services/
│   │   ├── fileReaderService.js # Lectura de archivos
│   │   └── freightService.js    # Cálculo de flete
│   ├── utils/
│   │   └── formatters.js    # Funciones de formato
│   └── validators/
│       └── invoiceValidator.js # Validación de datos
├── server.js           # Servidor Express
└── package.json        # Dependencias

API Endpoints

POST /api/invoices/upload

Sube un archivo con datos de facturas.

Request:

Content-Type: multipart/form-data
Body: file (xlsx o csv)

Response:

{
  "message": "File uploaded successfully.",
  "invoices": [
    {
      "id": 0,
      "numero_factura": "FAC-001",
      "valor_factura": 150000,
      "ciudad_destino": "Bogotá"
    }
  ]
}

GET /api/invoices

Obtiene todas las facturas cargadas actualmente.

POST /api/invoices/calculate-freight

Calcula el porcentaje de flete.

Request:

{
  "invoiceId": 0,
  "freightValue": 15000
}

Response:

{
  "invoiceValue": 150000,
  "freightValue": 15000,
  "percentage": 0.1,
  "percentageDisplay": "10.00%",
  "exceedsLimit": false,
  "message": "Freight is within the allowed range.",
  "invoiceValueFormatted": "$150,000",
  "freightValueFormatted": "$15,000"
}

Configuración

Editar src/config/settings.js para cambiar:

• MAX_FREIGHT_PERCENTAGE: Límite de porcentaje (default: 0.10 = 10%)
• PORT: Puerto del servidor (default: 3000)
• WARNING_MESSAGE: Mensaje de advertencia
• SUCCESS_MESSAGE: Mensaje de éxito

Validación de Datos

La aplicación valida:

✓ Archivo no vacío
✓ Presencia de columnas requeridas
✓ Número de factura no vacío
✓ Valor de factura > 0
✓ Ciudad de destino no vacía
✓ Flete debe ser número no negativo

Mejoras Futuras

• Soporte para descarga de resultados
• Histórico de cálculos
• Soporte para múltiples monedas
• Gráficos y estadísticas
• Autenticación de usuarios
• Base de datos persistente
• Importación desde API

Requisitos de Sistema

• Node.js v14+
• npm o yarn
• Navegador moderno (Chrome, Firefox, Safari, Edge)

Licencia

MIT

Autor

Jaltech 2026