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
Product Owner	Máximo Gómez

---

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

• Carga de archivo de nómina.

• Carga de archivo o archivos bancarios.

• Consulta de BambooHR vía el API.

• 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.
• Envío automático a terceros.
• Aprobaciones de nómina.
• Sustitución oficial del proceso contable sin validación humana.

---

Arquitectura

Arquitectura actual

Usuario
  ↓
App Web Cruce de Cuentas GT
  ↓
Carga de archivos / Datos de entrada
  ↓
Motor de validación
  ↓
Reporte de diferencias

Arquitectura objetivo

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	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. El cruce debe comparar empleados entre BambooHR, nómina y banco.

3. Un empleado activo en BambooHR con monto en nómina debe tener pago bancario correspondiente, salvo excepción documentada.

4. Un pago bancario sin empleado relacionado en nómina debe marcarse como pago no conciliado.

5. Un pago bancario a una cuenta no reconocida debe marcarse como posible irregularidad.

6. Un empleado inactivo en BambooHR con pago en nómina o banco debe marcarse para revisión.

7. Las variaciones de nombres no deben considerarse irregularidad automáticamente.

8. El sistema debe normalizar nombres para reducir falsos positivos.

9. La coincidencia puede realizarse por:

   • Employee Number.
   • Cuenta bancaria.
   • Nombre normalizado.
   • Monto.
   • Combinación de nombre + monto.

10. Las cuentas con moneda especial o excepción deben manejarse en una tabla de excepciones.

11. Si la moneda no se detecta de forma confiable, el sistema debe marcar el caso para revisión.

12. El reporte final debe priorizar hallazgos, diferencias e irregularidades, no llenar al usuario de casos correctos.

13. 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

Employee Number coincide
+
Cuenta bancaria coincide
+
Monto coincide dentro de tolerancia

Coincidencia media

Cuenta bancaria coincide
+
Monto coincide
+
Nombre normalizado compatible

Coincidencia baja

Nombre parecido
+
Monto parecido

Sin coincidencia

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

Resumen Ejecutivo
Irregularidades
Diferencias de Monto
Pagos No Encontrados
Pagos Bancarios No Conciliados
Empleados Inactivos
Posibles Duplicados
Detalle Completo
Excepciones Aplicadas

Columnas sugeridas

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

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.

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

git clone https://gitea.glm.com/glm-it/cruce-cuentas-gt.git
cd cruce-cuentas-gt

Instalar dependencias

pnpm install

Configurar variables

cp .env.example .env.local

Editar .env.local con las credenciales reales del ambiente correspondiente.

Ejecutar en desarrollo

pnpm run dev

La aplicación estará disponible en:

http://localhost:3000

Build de producción

pnpm run build

Ejecutar build

pnpm run start

---

Estructura del Repositorio

/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:

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

id
country
period_month
period_year
run_type
status
created_by
created_at
completed_at
output_file_url

Tabla: payroll_rows

id
payroll_run_id
employee_number
employee_name
bank_account
currency
net_amount
status
raw_payload
created_at

Tabla: bank_transactions

id
payroll_run_id
transaction_date
bank_account
beneficiary_name
currency
amount
reference
description
raw_payload
created_at

Tabla: bamboo_employees

id
employee_number
employee_name
status
termination_date
country
department
position
email
raw_payload
synced_at

Tabla: reconciliation_findings

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

id
bank_account
employee_name
correct_currency
comment
created_at
updated_at

Tabla: audit_logs

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:

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

[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.