# Cruce de Cuentas GT > Aplicación interna para cruzar información de BambooHR, nómina y banco en Guatemala, detectando diferencias, pagos no conciliados e irregularidades antes del cierre de nómina. --- ## Información General | Campo | Detalle | | ------------------------ | --------------------------------- | | Proyecto | Cruce de Cuentas GT | | Área | RRHH / Nómina / Administración | | Estado | En Progreso / Prototipo funcional | | Developer Principal | Isaac Aracena | | IT Manager | Luis Matos | | Fecha de Inicio | A completar | | Fecha de Cierre Estimada | A completar | | Ciclo Shape Up | A completar | | Board de Ejecución | A completar | | PRD del Proyecto | A completar | --- ## Objetivo ### Problema que resuelve Actualmente, el cruce entre empleados activos en BambooHR, archivo de nómina y pagos realizados por banco requiere revisión manual en hojas de cálculo. Esto aumenta el riesgo de errores operativos, pagos duplicados, pagos a cuentas incorrectas, pagos a empleados inactivos o pagos a personas que no existen en BambooHR. ### Solución implementada Cruce de Cuentas GT centraliza el análisis de nómina de Guatemala en una aplicación web que permite cargar o consultar las fuentes necesarias, ejecutar validaciones automáticas y generar un reporte de diferencias e irregularidades para revisión del equipo responsable. ### Usuarios / Beneficiarios * Equipo de RRHH Guatemala * Equipo de Nómina * Administración / Finanzas * IT * Gerencia responsable de control interno --- ## Estado Actual del Proyecto Este repositorio contiene la base del portal de Cruce de Cuentas GT. El objetivo del proyecto es convertir el proceso manual de validación de nómina en una herramienta interna más segura, trazable y fácil de usar. En esta etapa, el enfoque principal es Guatemala. Los demás países o portales pueden quedar visibles como módulos futuros, pero deshabilitados hasta que su lógica sea definida y validada. --- ## Características Principales ### Funcionalidades principales * Selección de país, mes, año y tipo de cruce. * Cruce de empleados contra BambooHR. * Cruce de nómina contra archivo bancario. * Validación de montos pagados vs montos esperados. * Detección de empleados no encontrados en BambooHR. * Detección de pagos bancarios no conciliados. * Detección de empleados inactivos con pago. * Validación por cuenta bancaria. * Validación por nombre normalizado. * Validación por monto. * Manejo de monedas y excepciones. * Generación de reporte final de irregularidades. * Descarga de archivo resultado para revisión. * Base preparada para integración con n8n y BambooHR API. ### Funcionalidades objetivo * Portal centralizado por país. * Portal Guatemala activo. * Portales de otros países deshabilitados visualmente. * Consulta directa a BambooHR API. * Carga de archivo de nómina. * Carga de uno o varios CSV del banco. * Cruce mensual o por quincena. * Reporte ejecutivo de diferencias. * Historial de cruces ejecutados. * Control de usuarios y permisos. * Registro de auditoría de ejecuciones. * Alertas automáticas si se detectan irregularidades críticas. --- ## Alcance del MVP El MVP debe enfocarse en el cruce de cuentas de Guatemala. ### Incluido en MVP * Portal de Guatemala activo. * Selección de mes y año. * Selección de tipo de cruce: * Mensual. * Quincena 15. * Quincena 30. * Carga de archivo de nómina. * Carga de archivo o archivos bancarios. * Consulta o carga de datos de BambooHR. * Ejecución del cruce. * Generación de reporte final. * Visualización de diferencias. * Descarga del resultado. ### Fuera de alcance para MVP * Automatización completa para todos los países. * Edición manual de datos desde la app. * Conexión directa con sistemas bancarios. * Envío automático a terceros. * Aprobaciones de nómina. * Sustitución oficial del proceso contable sin validación humana. --- ## Arquitectura ### Arquitectura actual ```txt Usuario ↓ App Web Cruce de Cuentas GT ↓ Carga de archivos / Datos de entrada ↓ Motor de validación ↓ Reporte de diferencias ``` ### Arquitectura objetivo ```txt Usuario autorizado ↓ App Web Centralizada ↓ Portal Guatemala ↓ n8n / Backend ↓ BambooHR API + Nómina + Banco ↓ Motor de conciliación ↓ Reporte final en Excel / Google Sheets ↓ Notificación al responsable ``` --- ## Stack Tecnológico | Componente | Tecnología | Propósito | | ------------------ | --------------------------------- | ----------------------------------------------------------- | | Frontend | React / Vite o Next.js | Interfaz web del portal | | Backend | Node.js / API / n8n | Procesamiento del cruce y orquestación | | Automatización | n8n | Integración con BambooHR, archivos y generación de reportes | | RRHH | BambooHR API | Fuente oficial de empleados | | Archivos de nómina | Excel / CSV | Fuente de pagos esperados | | Banco | CSV / Excel / PDF convertido | Fuente de pagos ejecutados | | Reportes | Excel / Google Sheets | Salida del cruce y hallazgos | | Base de datos | Supabase / PostgreSQL recomendado | Historial de ejecuciones, usuarios y auditoría | | Infraestructura | Servidor GLM / EasyPanel | Hosting de servicios internos | --- ## Integraciones Externas | Sistema | Tipo de integración | Datos que fluyen | | ------------------- | -------------------------- | ------------------------------------------------------------ | | BambooHR | API REST | Empleados, estado, número de empleado, datos laborales | | Archivo de nómina | Carga manual / Excel | Monto neto, cuenta, empleado, moneda, periodo | | Banco | Carga manual / CSV / Excel | Pagos realizados, cuentas, montos, moneda | | n8n | Webhook / Workflow | Orquestación del proceso y generación de salida | | Google Sheets | API / Export | Reporte de resultados y revisión operativa | | Gmail / Google Chat | OAuth / Webhook | Notificaciones futuras de cruce finalizado o irregularidades | --- ## Reglas de Negocio 1. El identificador principal del empleado debe ser `Employee Number` de BambooHR. 2. No se debe usar DPI como identificador principal del reporte. 3. El cruce debe comparar empleados entre BambooHR, nómina y banco. 4. Un empleado activo en BambooHR con monto en nómina debe tener pago bancario correspondiente, salvo excepción documentada. 5. Un pago bancario sin empleado relacionado en nómina debe marcarse como pago no conciliado. 6. Un pago bancario a una cuenta no reconocida debe marcarse como posible irregularidad. 7. Un empleado inactivo en BambooHR con pago en nómina o banco debe marcarse para revisión. 8. Las diferencias pequeñas por redondeo pueden tolerarse según la tolerancia configurada. 9. La tolerancia sugerida para diferencias monetarias es `0.02`. 10. Las variaciones de nombres no deben considerarse irregularidad automáticamente. 11. El sistema debe normalizar nombres para reducir falsos positivos. 12. La coincidencia puede realizarse por: * Employee Number. * Cuenta bancaria. * Nombre normalizado. * Monto. * Combinación de nombre + monto. 13. Las cuentas con moneda especial o excepción deben manejarse en una tabla de excepciones. 14. Si la moneda no se detecta de forma confiable, el sistema debe marcar el caso para revisión. 15. El reporte final debe priorizar hallazgos, diferencias e irregularidades, no llenar al usuario de casos correctos. 16. El resultado debe ser revisado por una persona responsable antes de tomar acciones operativas. --- ## Tipos de Cruce | Tipo de cruce | Descripción | | ------------- | -------------------------------------------------------- | | Mensual | Cruce completo del mes seleccionado | | Quincena 15 | Cruce correspondiente a la primera quincena | | Quincena 30 | Cruce correspondiente a la segunda quincena | | Especial | Cruce puntual para archivos extraordinarios o reprocesos | --- ## Fuentes de Datos ### BambooHR Fuente oficial para validar: * Employee Number. * Nombre del empleado. * Estado del empleado. * Fecha de baja. * Puesto. * País. * Departamento. * Información laboral relevante. ### Nómina Fuente para validar lo que debe pagarse: * Employee Number. * Nombre completo. * Cuenta bancaria. * Periodo. * Moneda. * Salario. * Bonificaciones. * Deducciones. * Neto a pagar. * Estatus. * Comentarios. ### Banco Fuente para validar lo que realmente se pagó: * Fecha de pago. * Cuenta destino. * Nombre asociado. * Monto pagado. * Moneda. * Referencia bancaria. * Descripción o concepto. --- ## Normalización de Datos El sistema debe limpiar y estandarizar los datos antes de cruzarlos. ### Normalización de nombres Debe contemplar: * Mayúsculas y minúsculas. * Tildes. * Espacios dobles. * Orden de nombres y apellidos. * Iniciales. * Primer y segundo nombre. * Palabras comunes como: * DE * DEL * LA * LAS * LOS * Y * DA * DO * DAS * DOS ### Normalización de montos Debe contemplar: * Separadores de miles. * Decimales. * Moneda. * Redondeos. * Diferencias menores dentro de la tolerancia permitida. ### Normalización de cuentas Debe contemplar: * Cuentas como texto. * Ceros a la izquierda. * Espacios. * Guiones. * Formatos distintos entre banco y nómina. --- ## Criterios de Coincidencia El motor de cruce debe evaluar coincidencias con distintos niveles de confianza. ### Coincidencia alta ```txt Employee Number coincide + Cuenta bancaria coincide + Monto coincide dentro de tolerancia ``` ### Coincidencia media ```txt Cuenta bancaria coincide + Monto coincide + Nombre normalizado compatible ``` ### Coincidencia baja ```txt Nombre parecido + Monto parecido ``` ### Sin coincidencia ```txt No existe relación confiable entre BambooHR, nómina y banco ``` Los casos con coincidencia baja o sin coincidencia deben ir al reporte de revisión. --- ## Categorías de Hallazgos El reporte final debe clasificar los casos encontrados. | Categoría | Descripción | | ---------------------------------- | -------------------------------------------------------------------------- | | OK | Caso conciliado correctamente | | Diferencia de monto | El monto de nómina no coincide con el monto pagado | | Pago no encontrado en banco | Está en nómina, pero no aparece pagado | | Pago bancario no conciliado | Está en banco, pero no aparece en nómina | | Empleado no encontrado en BambooHR | Está en nómina o banco, pero no existe en BambooHR | | Empleado inactivo con pago | Tiene fecha de baja o estado inactivo y aparece con pago | | Cuenta bancaria diferente | La cuenta esperada no coincide con la cuenta pagada | | Moneda inconsistente | La moneda no coincide o no pudo validarse | | Posible duplicado | Hay más de un pago o registro asociado al mismo empleado | | Requiere revisión manual | El sistema no tiene suficiente confianza para clasificarlo automáticamente | --- ## Reporte de Salida El sistema debe generar un reporte claro y accionable. ### Hojas sugeridas del Excel final ```txt Resumen Ejecutivo Irregularidades Diferencias de Monto Pagos No Encontrados Pagos Bancarios No Conciliados Empleados Inactivos Posibles Duplicados Detalle Completo Excepciones Aplicadas ``` ### Columnas sugeridas ```txt Periodo Tipo de Cruce Employee Number Empleado Cuenta Nómina Cuenta Banco Moneda Nómina Moneda Banco Monto Nómina Monto Banco Diferencia Estado BambooHR Fecha de Baja Categoría Hallazgo Nivel de Confianza Comentario Acción Recomendada ``` --- ## Flujo Principal ```txt 1. El usuario entra al portal central. 2. Selecciona el módulo Guatemala. 3. Selecciona mes, año y tipo de cruce. 4. Carga el archivo de nómina. 5. Carga uno o varios archivos del banco. 6. El sistema consulta o recibe los datos de BambooHR. 7. El motor normaliza empleados, cuentas, nombres, monedas y montos. 8. El sistema cruza BambooHR vs Nómina. 9. El sistema cruza Nómina vs Banco. 10. El sistema identifica diferencias e irregularidades. 11. El sistema genera un resumen ejecutivo. 12. El sistema genera el Excel final. 13. El usuario descarga el reporte. 14. Opcionalmente, el sistema registra la ejecución en historial. ``` --- ## Schedules / Triggers | Trigger | Frecuencia | Descripción | | ------------------------ | ---------- | --------------------------------------------------- | | Webhook POST `/cruce-gt` | On demand | Ejecuta el cruce cuando el usuario procesa archivos | | Carga manual de archivos | On demand | Usuario sube nómina y banco | | Consulta BambooHR | On demand | Obtiene datos actualizados de empleados | | Notificación final | On demand | Avisa cuando el cruce terminó | | Revisión de historial | Manual | Usuario consulta cruces anteriores | --- ## Configuración y Setup ### Prerrequisitos * Node.js v18 o superior. * pnpm o npm. * Acceso al repositorio. * Acceso a BambooHR API. * Acceso a n8n si el procesamiento se ejecuta vía workflow. * Acceso a carpeta o fuente donde se reciben archivos de nómina y banco. * Variables de entorno configuradas. * Credenciales guardadas en el vault de GLM IT. --- ## Variables de Entorno Crear un archivo `.env` o `.env.local` basado en `.env.example`. ```env APP_ENV=development APP_URL=http://localhost:3000 # BambooHR BAMBOOHR_API_KEY= BAMBOOHR_SUBDOMAIN= BAMBOOHR_BASE_URL= # n8n N8N_WEBHOOK_URL= N8N_API_KEY= # Base de datos DATABASE_URL= SUPABASE_URL= SUPABASE_ANON_KEY= SUPABASE_SERVICE_ROLE_KEY= # Google / Reportes GOOGLE_CLIENT_ID= GOOGLE_CLIENT_SECRET= GOOGLE_DRIVE_FOLDER_ID= GOOGLE_SHEETS_OUTPUT_FOLDER_ID= # Seguridad JWT_SECRET= SESSION_SECRET= ``` > Nunca commitear credenciales reales al repositorio. Todas las llaves, tokens y secretos deben guardarse en el vault o gestor de credenciales definido por GLM IT. --- ## Instalación / Deploy ### Clonar repositorio ```bash git clone https://gitea.glm.com/glm-it/cruce-cuentas-gt.git cd cruce-cuentas-gt ``` ### Instalar dependencias ```bash pnpm install ``` ### Configurar variables ```bash cp .env.example .env.local ``` Editar `.env.local` con las credenciales reales del ambiente correspondiente. ### Ejecutar en desarrollo ```bash pnpm run dev ``` La aplicación estará disponible en: ```txt http://localhost:3000 ``` ### Build de producción ```bash pnpm run build ``` ### Ejecutar build ```bash pnpm run start ``` --- ## Estructura del Repositorio ```txt /cruce-cuentas-gt |-- README.md |-- .env.example |-- package.json |-- pnpm-lock.yaml | |-- /src | |-- /app | |-- /components | |-- /lib | |-- /services | |-- /utils | |-- /db | | |-- schema.sql | | └-- migrations | └-- /types | |-- /n8n | └-- workflow.json | |-- /docs | |-- PRD.md | |-- WORKFLOW.md | |-- DATABASE_SCHEMA.md | |-- FIELD_MAPPING.md | |-- TEST_CASES.md | └-- architecture.png | |-- /scripts | |-- normalize-payroll.ts | |-- normalize-bank.ts | |-- bamboohr-sync.ts | └-- generate-report.ts | |-- /samples | |-- payroll-template.xlsx | |-- bank-template.csv | └-- exceptions-template.xlsx | |-- CHANGELOG.md └-- DECISIONS.md ``` --- ## Esquema de Base de Datos Objetivo Tablas sugeridas: ```txt users countries payroll_runs payroll_rows bank_transactions bamboo_employees reconciliation_results reconciliation_findings currency_exceptions execution_logs audit_logs uploaded_files ``` ### Tabla: payroll_runs ```txt id country period_month period_year run_type status created_by created_at completed_at output_file_url ``` ### Tabla: payroll_rows ```txt id payroll_run_id employee_number employee_name bank_account currency net_amount status raw_payload created_at ``` ### Tabla: bank_transactions ```txt id payroll_run_id transaction_date bank_account beneficiary_name currency amount reference description raw_payload created_at ``` ### Tabla: bamboo_employees ```txt id employee_number employee_name status termination_date country department position email raw_payload synced_at ``` ### Tabla: reconciliation_findings ```txt id payroll_run_id employee_number employee_name finding_category severity confidence_level payroll_amount bank_amount difference_amount comment recommended_action created_at ``` ### Tabla: currency_exceptions ```txt id bank_account employee_name correct_currency comment created_at updated_at ``` ### Tabla: audit_logs ```txt id user_id action entity_type entity_id old_value new_value created_at ``` --- ## Cómo Funciona ### Paso a paso 1. El usuario selecciona Guatemala en el portal. 2. El usuario selecciona el periodo del cruce. 3. El usuario define si el cruce será mensual, quincena 15 o quincena 30. 4. El usuario carga el archivo de nómina. 5. El usuario carga el archivo o archivos del banco. 6. El sistema obtiene la data de BambooHR. 7. El sistema normaliza nombres, cuentas, monedas y montos. 8. El sistema cruza empleados de nómina contra BambooHR. 9. El sistema cruza pagos esperados contra pagos bancarios. 10. El sistema calcula diferencias. 11. El sistema clasifica hallazgos. 12. El sistema genera el reporte. 13. El usuario descarga el Excel final. 14. El sistema guarda historial y logs de ejecución. --- ## Testing Casos de prueba mínimos: | Caso | Input | Output esperado | Estado | | ------------------------------ | --------------------------------------------- | ------------------------------------------------- | ----------- | | Caso feliz | BambooHR, nómina y banco coinciden | Reporte sin irregularidades críticas | A completar | | Diferencia de monto | Monto de nómina distinto al banco | Hallazgo de diferencia de monto | A completar | | Pago faltante | Empleado en nómina no aparece en banco | Hallazgo de pago no encontrado | A completar | | Pago no conciliado | Pago en banco no aparece en nómina | Hallazgo de pago bancario no conciliado | A completar | | Empleado no existe en BambooHR | Registro en nómina sin Employee Number válido | Hallazgo de empleado no encontrado | A completar | | Empleado inactivo | Empleado con baja aparece con pago | Hallazgo de empleado inactivo con pago | A completar | | Cuenta diferente | Cuenta de nómina no coincide con banco | Hallazgo de cuenta bancaria diferente | A completar | | Moneda distinta | Moneda de banco distinta a nómina | Hallazgo de moneda inconsistente | A completar | | Diferencia menor a tolerancia | Diferencia <= 0.02 | Caso marcado como conciliado o diferencia menor | A completar | | Nombre con variación | Nombre parcial o con iniciales | Coincidencia aceptada si cuenta y monto coinciden | A completar | | Archivo inválido | Archivo sin columnas requeridas | Error manejado y mensaje claro | A completar | | API caída | BambooHR no responde | Error manejado, no se genera reporte incompleto | A completar | --- ## Errores Conocidos y Troubleshooting | Error | Causa probable | Solución | | ---------------------------------- | --------------------------------------- | --------------------------------------------------- | | 401 Unauthorized BambooHR | API Key inválida o vencida | Renovar credencial y actualizar `.env` | | Archivo no procesa | Formato incorrecto o columnas faltantes | Validar plantilla esperada | | Montos aparecen como texto | Formato de Excel/CSV incorrecto | Normalizar columna antes del cruce | | Cuentas pierden ceros iniciales | Excel interpreta cuenta como número | Leer cuentas como texto | | Muchos falsos positivos por nombre | Nombres no normalizados | Revisar función de normalización | | Moneda no detectada | Archivo no trae moneda clara | Revisar excepciones de moneda | | Webhook no responde | n8n apagado o URL incorrecta | Revisar n8n Executions y variable `N8N_WEBHOOK_URL` | | Output vacío | No llegaron archivos o el parser falló | Revisar logs de ejecución | | Reporte incompleto | Error en una fuente de datos | Bloquear salida y mostrar error al usuario | | Timeout | Archivo muy grande o servicio lento | Aumentar timeout o procesar en background | --- ## Monitoreo Cuando el sistema esté operativo, revisar: * Ejecuciones de n8n. * Logs de backend. * Errores de BambooHR API. * Archivos subidos. * Cruces fallidos. * Reportes generados. * Hallazgos críticos. * Historial de ejecuciones. * Alertas enviadas. * Tiempo promedio de procesamiento. ### Output esperado Un cruce exitoso debe producir: ```txt 1. Resumen ejecutivo. 2. Archivo Excel con hallazgos. 3. Detalle completo del cruce. 4. Clasificación de irregularidades. 5. Log de ejecución. 6. Enlace de descarga del resultado. ``` --- ## Seguridad 1. No se deben commitear archivos reales de nómina. 2. No se deben commitear archivos reales del banco. 3. No se deben commitear credenciales. 4. Los archivos de prueba deben ser anonimizados. 5. El acceso debe limitarse a usuarios autorizados. 6. Los reportes deben almacenarse en carpetas controladas. 7. Las acciones relevantes deben registrarse en audit log. 8. Los datos sensibles deben eliminarse o archivarse según política interna. --- ## Changelog ```txt [YYYY-MM-DD] v0.1 — Inicio del repositorio y documentación base. [YYYY-MM-DD] v0.2 — Definición de reglas de negocio para cruce Guatemala. [YYYY-MM-DD] v0.3 — Preparación de estructura para BambooHR, nómina y banco. ``` --- ## Decisions Log ### DEC-001 — Guatemala como primer portal activo * Fecha: A completar. * Contexto: El proceso de cruce se está validando inicialmente para Guatemala. * Opciones consideradas: Activar todos los países vs iniciar con Guatemala. * Decisión: Activar solo Guatemala en el MVP. * Razón: Reduce complejidad inicial y permite validar la lógica antes de escalar. ### DEC-002 — Employee Number como identificador principal * Fecha: A completar. * Contexto: El identificador debe ser consistente con BambooHR y evitar dependencias de documentos locales. * Opciones consideradas: DPI vs Employee Number. * Decisión: Usar Employee Number como identificador principal. * Razón: Es el identificador oficial dentro de BambooHR y facilita la integración regional. ### DEC-003 — BambooHR como fuente oficial de empleados * Fecha: A completar. * Contexto: El sistema necesita validar si un empleado existe y si está activo. * Opciones consideradas: Archivo manual de empleados vs BambooHR API. * Decisión: Usar BambooHR como fuente oficial. * Razón: Reduce errores manuales y permite validar empleados activos, inactivos y bajas. ### DEC-004 — Reportar solo hallazgos relevantes * Fecha: A completar. * Contexto: Los reportes con demasiados casos OK dificultan la revisión. * Opciones consideradas: Reporte completo de todos los registros vs reporte enfocado en irregularidades. * Decisión: Priorizar diferencias, irregularidades y casos que requieren revisión. * Razón: Facilita el análisis operativo y acelera la toma de decisiones. ### DEC-005 — Mantener tolerancia monetaria * Fecha: A completar. * Contexto: Pueden existir diferencias pequeñas por redondeo o formato. * Opciones consideradas: Coincidencia exacta vs tolerancia configurable. * Decisión: Usar tolerancia sugerida de `0.02`. * Razón: Reduce falsos positivos sin ocultar diferencias materiales. ### DEC-006 — Manejar excepciones de moneda * Fecha: A completar. * Contexto: Algunos empleados o cuentas pueden tener moneda distinta a la moneda por defecto. * Opciones consideradas: Asumir moneda por defecto vs tabla de excepciones. * Decisión: Mantener una tabla de excepciones de moneda. * Razón: Evita clasificar erróneamente pagos válidos como irregularidades. --- ## Contactos del Proyecto | Rol | Nombre | Contacto | | ----------------------- | ------------- | ----------- | | Product Owner | A completar | A completar | | IT Manager | Luis Matos | A completar | | Developer | Isaac Aracena | A completar | | RRHH Guatemala | A completar | A completar | | Nómina / Administración | A completar | A completar | --- ## Definition of Done * Todos los criterios principales del cruce Guatemala validados. * Código commiteado y pusheado al repositorio. * README completo y actualizado. * Variables de entorno documentadas en `.env.example`. * Tests básicos pasando. * Workflow de n8n exportado en `/n8n/workflow.json`, si aplica. * Schema SQL documentado en `/src/db/schema.sql`, si aplica. * Plantillas de archivos documentadas. * Casos de prueba ejecutados con datos anonimizados. * Reporte final generado correctamente. * Hallazgos clasificados correctamente. * Probado en ambiente real, no solo local. * Luis Matos validó el output. * Product Owner aprobó el resultado final. --- ## Notas Finales Cruce de Cuentas GT busca reducir el riesgo operativo en el proceso de nómina de Guatemala mediante una validación automática entre BambooHR, nómina y banco. El sistema no reemplaza la revisión humana final, pero permite detectar diferencias de forma más rápida, ordenada y trazable.