Files

T

Isaac_Aracena b283ca3c24 Actualizar README.md

2026-08-07 23:31:44 +00:00

18 KiB

Raw Permalink Blame History

Expedientes de Finiquitos – Guatemala

Sistema interno de GLM para preparar, validar y generar expedientes de finiquitos de Guatemala a partir de prestaciones laborales, datos de BambooHR, documentos de identidad y plantillas corporativas.

INFORMACIÓN GENERAL

Campo	Detalle
Proyecto	Finiquitos – Guatemala
Área	Recursos Humanos / Administración
Estado	Operativo
Developer	Isaac Aracena
IT Manager	Luis Matos

OBJETIVO

Problema que resuelve

La preparación de expedientes de finiquitos en Guatemala requería revisar manualmente las prestaciones laborales, localizar al empleado en BambooHR, buscar y descargar su DPI, validar información legal, crear carpetas individuales, completar documentos corporativos y organizar el expediente final. Este proceso era repetitivo, propenso a errores de digitación y especialmente sensible a diferencias de nombres entre las fuentes.

Solución implementada

El sistema combina Google Sheets, Apps Script y n8n para preparar el lote de prestaciones y procesar cada empleado de manera controlada. El flujo consulta BambooHR, identifica al empleado, localiza su DPI, utiliza Gemini para extraer y validar información, crea el expediente en Google Drive y genera automáticamente el finiquito, voucher y formato de impresión de cheque a partir de plantillas oficiales.

También contempla excepciones reales de operación, como nombres incompletos o distintos en BambooHR, documentos DPI con nombres incorrectos, archivos de identidad en PDF/JPG/PNG y empleados que requieren más de un expediente por prestaciones diferentes.

Usuarios / Beneficiarios

Recursos Humanos de GomezLee Marketing.
Administración.
Personal responsable de revisar y completar finiquitos en Guatemala.
IT, para soporte, auditoría y mantenimiento de la automatización.

ARQUITECTURA

Diagrama de flujo

Archivo de prestaciones
        |
        v
Google Sheets
        |
        +--> Apps Script
        |      |
        |      +--> prepara Consolidado / configuración
        |      +--> genera PDFs de prestaciones
        |      +--> mantiene hojas de control
        |
        v
n8n - Workflow MASIVO
        |
        +--> lee configuración del lote
        +--> lee Consolidado
        +--> prepara empleados autorizados
        +--> procesa 1 empleado a la vez
                 |
                 v
        n8n - Workflow INDIVIDUAL
                 |
                 +--> valida entrada
                 +--> verifica carpeta existente
                 +--> busca empleado en BambooHR
                 +--> obtiene datos completos
                 +--> lista documentos
                 +--> identifica / selecciona DPI
                 +--> descarga DPI
                 +--> Gemini extrae datos
                 +--> valida información
                 +--> crea carpeta en Drive
                 +--> guarda DPI
                 +--> copia plantillas
                 +--> personaliza finiquito
                 +--> personaliza voucher
                 +--> llena formato de cheque
                 +--> actualiza Consolidado
                 |
                 v
        Expediente final en Google Drive

Stack tecnológico

Componente	Tecnología	Propósito
Automatización	n8n	Orquestación del procesamiento masivo e individual
Preparación de datos	Google Apps Script	Preparación del Google Sheet, hojas de control y PDFs de prestaciones
RRHH	BambooHR API	Fuente de datos de empleados y documentos
IA	Google Gemini	Extracción y validación de datos del DPI
Datos operativos	Google Sheets API	Consolidado, configuración y seguimiento
Archivos	Google Drive API	Creación de carpetas, almacenamiento de DPI y documentos
Documentos	Google Docs API	Copia y personalización de plantillas
Correo complementario	Gmail / n8n	Envío de PDFs de prestaciones cuando aplica

Integraciones externas

Sistema	Tipo de integración	Datos que fluyen
Google Sheets	API / OAuth	Prestaciones, configuración, filas de empleados y resultados
Google Drive	API / OAuth	Carpetas, DPI, finiquitos, vouchers, formatos de cheque y PDFs
Google Docs	API / OAuth	Duplicación y personalización de plantillas
BambooHR	API	Perfil del empleado, datos personales y documentos
Gemini	API	Lectura del DPI y extracción de información estructurada
Gmail	OAuth	Envío complementario de PDFs cuando el flujo de correo es utilizado

REGLAS DE NEGOCIO

El workflow masivo procesa únicamente los registros expresamente autorizados para el lote.
Los empleados se procesan uno por uno para evitar conflictos, duplicados y sobrecarga de servicios externos.
Wait For Sub-Workflow Completion debe permanecer activado en el nodo que ejecuta el procesador individual.
El flujo individual conserva como nombre oficial para carpetas y documentos el nombre proveniente del Consolidado.
BambooHR puede contener nombres incompletos o diferentes; se permiten coincidencias exactas, coincidencias flexibles seguras y overrides manuales confirmados.
Los overrides de empleados deben documentarse por nombre normalizado y, cuando sea posible, por employeeId.
El DPI puede estar almacenado como PDF, JPG/JPEG o PNG.
La selección automática del DPI utiliza nombre, metadata y señales como DPI, RENAP, Documento Personal de Identificación o Cédula.
Cuando el archivo correcto está mal nombrado en BambooHR, se permite un override employeeId -> documentId después de validarlo manualmente.
Gemini debe confirmar que el documento corresponde a un DPI guatemalteco y extraer sus datos estructurados.
Las validaciones críticas incluyen documento DPI de Guatemala, frente/reverso visibles y número de DPI de 13 dígitos.
Diferencias de nombre, fecha, sexo, estado civil o campos disponibles en BambooHR pueden registrarse como advertencias sin bloquear automáticamente el expediente cuando el documento fue validado.
El finiquito incorpora municipio y departamento en las menciones del RENAP. Se utiliza lugar de expedición explícito cuando existe y, de acuerdo con el criterio operativo adoptado para este proyecto, se usa el lugar de nacimiento visible como respaldo cuando el DPI no imprime el lugar de expedición.
Antes de crear un expediente se verifica si ya existe una carpeta con ese nombre para evitar duplicados.
Cuando una misma persona requiere un segundo expediente por una prestación distinta, la carpeta anterior debe distinguirse/renombrarse para permitir la creación de un nuevo expediente sin mezclar documentos.
Un error en un empleado no debe detener el lote completo: la rama de error vuelve al loop y continúa con el siguiente empleado.
Los resultados finales deben conservar trazabilidad suficiente para identificar el empleado, DPI seleccionado, carpeta y documentos generados.

CONFIGURACIÓN Y SETUP

Prerrequisitos

Acceso autorizado a BambooHR.
Acceso a Google Drive y Google Sheets del proyecto.
Acceso a las plantillas corporativas de finiquito, voucher y formato de cheque.
Instancia de n8n de GLM.
Credencial de BambooHR configurada en n8n.
Credenciales Google OAuth configuradas en n8n.
Credencial/API de Gemini configurada en n8n.
Apps Script instalado en el Google Sheet utilizado para el lote.

Credenciales y configuración

Las credenciales no deben almacenarse en el repositorio. Deben permanecer configuradas en el credential store de n8n / infraestructura de GLM.

Los IDs de archivos y carpetas que deban ser configurables deben mantenerse en la hoja CONFIG_FINIQUITOS o en los nodos de configuración correspondientes, según la versión del workflow.

Clave	Descripción
`SPREADSHEET_ID`	ID del Google Sheet activo
`CARPETA_RAIZ_N8N_ID`	Carpeta raíz donde se crean los expedientes
`CARPETA_RAIZ_N8N_URL`	URL de la carpeta raíz
`CARPETA_PDF_PRESTACIONES_ID`	Carpeta de PDFs generados por Apps Script
`HOJA_CONSOLIDADO`	Hoja que debe leer el workflow masivo
`SOLO_NO`	Permite reintentar únicamente un registro del lote

NUNCA commitear API keys, tokens OAuth, contraseñas ni secretos en Gitea.

Base de datos

No aplica. El proyecto utiliza Google Sheets como fuente operativa de control y configuración.

Instalación / Deploy

Convertir o abrir el archivo de prestaciones como Google Sheets.
Abrir Extensiones -> Apps Script.
Instalar el archivo .gs del proyecto.
Ejecutar prepararTodoFiniquitosGT.
Confirmar que el Apps Script haya creado/actualizado las hojas requeridas y la configuración.
Importar en n8n el workflow individual.
Configurar sus credenciales de BambooHR, Google y Gemini.
Guardar y publicar el workflow individual.
Importar el workflow masivo.
En Ejecutar procesador individual, seleccionar el workflow individual publicado.
Mantener Wait For Sub-Workflow Completion activado.
Verificar CONFIG_FINIQUITOS y el nombre correcto de la hoja Consolidado.
Ejecutar el MASIVO desde Manual Trigger.

CÓMO FUNCIONA

Flujo paso a paso

Preparación: Apps Script toma el archivo de prestaciones y prepara las hojas necesarias para automatización.
Configuración: el workflow masivo obtiene el Google Sheet, la carpeta raíz, las plantillas y los empleados autorizados.
Lectura: n8n consulta la hoja de Consolidado correspondiente.
Validación: se comprueba NO., nombre y pertenencia al lote autorizado.
Loop: se envía un empleado a la vez al procesador individual.
Carpeta existente: se evita recrear un expediente que ya exista.
BambooHR: se localiza al empleado mediante coincidencia exacta, flexible u override confirmado.
Documentos: se listan los documentos del perfil y se identifica el DPI.
DPI: se descarga el documento; se aceptan PDF, JPG/JPEG y PNG.
Gemini: se extraen número de DPI, nombres, apellidos, sexo, fecha de nacimiento, estado civil, nacionalidad, lugar de nacimiento, vecindad y otros datos visibles.
Validación: se aplican validaciones críticas y advertencias no bloqueantes.
Drive: se crea la carpeta individual y se guarda el DPI.
Documentos: se copian las plantillas oficiales de finiquito, voucher y formato de cheque.
Personalización: se reemplazan los datos y se incorporan municipio/departamento en las menciones del RENAP.
Consolidado: se actualizan los campos operativos requeridos.
Resultado: el procesador individual devuelve estado y enlaces.
Continuación: el MASIVO espera brevemente y procesa el siguiente empleado, incluso si el anterior falló.
Resumen: al finalizar se genera un resumen general de la ejecución.

Schedules / Triggers

Trigger	Frecuencia	Descripción
Manual Trigger — MASIVO	On demand	Inicia el procesamiento del lote autorizado
Execute Sub-workflow	Por empleado	Ejecuta el procesador individual y espera su finalización
Apps Script manual	Por lote / cuando cambian prestaciones	Prepara estructura, configuración y PDFs
Workflow de envío complementario	On demand	Lee `CONTROL_ENVIOS`, descarga el PDF y prepara/envía el correo

TESTING

Casos de prueba mínimos

Caso	Input	Output esperado	Estado
Empleado con nombre exacto	Nombre igual en Consolidado y BambooHR	Perfil identificado y expediente generado	Verificado
Nombre incompleto en BambooHR	Apellidos/nombres diferentes	Match flexible u override confirmado	Verificado
DPI en PDF	Documento PDF válido	DPI analizado, almacenado y expediente generado	Verificado
DPI en JPG/JPEG	Imagen válida	Imagen aceptada y procesada por Gemini	Verificado
DPI en PNG	Imagen válida	Imagen aceptada y procesada por Gemini	Soportado
DPI mal nombrado	Documento válido sin palabra `DPI`	Override por `documentId`	Verificado
Varios documentos	Perfil con múltiples archivos	Se selecciona el DPI por reglas/override	Verificado
Carpeta existente	Expediente ya generado	No se duplica la carpeta	Verificado
Segunda prestación misma persona	Empleado con expediente anterior	Se distingue carpeta anterior y se crea expediente nuevo	Verificado
Error en un empleado	Match/DPI inválido	Se registra error y el MASIVO continúa	Verificado
Municipio/departamento	DPI con datos legibles	Finiquito contiene ambos datos en menciones RENAP	Verificado

ERRORES CONOCIDOS Y TROUBLESHOOTING

Error	Causa probable	Solución
`Unable to parse range: Consolidado!A:Z`	El workflow apunta a una hoja que no existe en el Google Sheet actual	Usar `hojaConsolidado` desde configuración, por ejemplo `Consolidado_Pendientes`
`The resource you are requesting could not be found`	Spreadsheet ID incorrecto o credencial Google sin acceso	Verificar ID y cuenta OAuth
`No fue posible identificar de forma única al empleado en BambooHR`	Nombre diferente o incompleto	Confirmar perfil y agregar override de empleado
`No se encontró ningún documento candidato a DPI`	DPI mal nombrado o reglas automáticas no lo reconocen	Revisar todos los documentos y agregar override `employeeId -> documentId`
MIME / formato DPI no permitido	DPI almacenado como JPG/PNG	Usar la versión que permite PDF/JPG/PNG
Fallo de validación DPI	Gemini no detectó frente/reverso o 13 dígitos	Revisar visualmente el documento y seleccionar el archivo correcto
Carpeta no generada	Carpeta previa detectada o error antes de creación	Revisar ejecución individual y estado de carpeta existente
Expediente duplicado requerido	La persona tiene otra prestación y ya existe carpeta	Renombrar/distinguir el expediente anterior antes de generar el nuevo

MONITOREO

n8n Executions: revisar cada ejecución masiva e individual. Verde = completada; rojo = requiere revisión.
Error Branch: el workflow masivo continúa con el siguiente empleado cuando el procesador individual falla.
Google Drive: confirmar que cada carpeta final contenga DPI, finiquito, voucher y formato de cheque.
Google Sheets: confirmar el registro de datos y estado operativo del lote.
Gemini: ante datos dudosos, revisar el DPI visualmente antes de agregar un override.
Output esperado: expediente completo y separado por empleado, con documentación correcta y trazabilidad.

ESTRUCTURA DEL REPOSITORIO

/expedientes-finiquitos-guatemala
├── README.md
├── /apps-script
│   └── AppsScript_Finiquitos_GT.gs
├── /n8n
│   ├── Finiquitos_GT_MASIVO.json
│   ├── Finiquitos_GT_Procesar_1_empleado.json
│   ├── BambooHR_Ver_Documentos_Empleado.json
│   └── Enviar_PDF_Prestaciones_Laborales.json
├── /docs
│   └── README_assets/
├── CHANGELOG.md
└── DECISIONS.md

CHANGELOG

2026-08 — Ajustes de robustez y nuevo lote

Adaptación para archivos de prestaciones actualizados.
Soporte para Consolidado_Pendientes.
Procesamiento selectivo mediante SOLO_NO.
Manejo de empleados con múltiples prestaciones.
Overrides de nombres entre Consolidado y BambooHR.
Override de DPI por employeeId -> documentId.
Soporte de DPI en PDF, JPG/JPEG y PNG.
Validaciones críticas y advertencias no bloqueantes.
Incorporación de municipio y departamento en menciones del RENAP.
Continuación del lote aun cuando un empleado falla.

2026-07 — Primera versión operativa

Preparación de prestaciones mediante Apps Script.
Workflow MASIVO.
Procesador individual.
Integración BambooHR + Gemini + Google Drive + Google Docs + Google Sheets.
Generación automática de expedientes.

DECISIONS LOG

DEC-001 — Procesamiento secuencial

Contexto: evitar conflictos y sobrecarga.
Decisión: batch de 1 y espera del subworkflow.
Razón: estabilidad y trazabilidad.

DEC-002 — Nombre documental desde Consolidado

Contexto: BambooHR puede tener nombres incompletos.
Decisión: BambooHR resuelve identidad; el Consolidado define el nombre de carpeta/documentos.
Razón: consistencia con prestaciones.

DEC-003 — Overrides controlados

Contexto: nombres y DPI pueden estar mal titulados.
Decisión: permitir overrides manuales confirmados para empleados y documentos.
Razón: resolver excepciones sin debilitar validación general.

DEC-004 — DPI en múltiples formatos

Decisión: aceptar PDF, JPG/JPEG y PNG.
Razón: BambooHR almacena documentos en formatos distintos.

DEC-005 — Validaciones críticas vs. advertencias

Decisión: bloquear solo validaciones críticas y registrar diferencias menores como advertencias.
Razón: reducir falsos negativos.

DEC-006 — Protección contra duplicados

Decisión: verificar carpeta existente antes de procesar.
Razón: evitar expedientes duplicados no intencionales.

DEFINITION OF DONE

Apps Script de preparación operativo.
Workflow MASIVO funcional.
Workflow individual funcional.
Integración con BambooHR.
Extracción de DPI con Gemini.
Soporte de DPI PDF/JPG/PNG.
Creación automática de carpetas.
Generación de finiquito, voucher y formato de cheque.
Inclusión de municipio y departamento.
Manejo de nombres diferentes y overrides.
Protección contra duplicados.
Reintentos individuales mediante SOLO_NO.
Continuación del lote ante errores individuales.
Probado con casos reales.
Agregar enlaces definitivos de Board y PRD si existen.
Mantener CHANGELOG y DECISIONS actualizados con futuros lotes.

Documento mantenido por el equipo GLM IT.

18 KiB Raw Permalink Blame History Unescape Escape