372 lines
18 KiB
Markdown
372 lines
18 KiB
Markdown
# 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
|
||
|
||
```text
|
||
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
|
||
|
||
1. El workflow masivo procesa únicamente los registros expresamente autorizados para el lote.
|
||
2. Los empleados se procesan **uno por uno** para evitar conflictos, duplicados y sobrecarga de servicios externos.
|
||
3. `Wait For Sub-Workflow Completion` debe permanecer activado en el nodo que ejecuta el procesador individual.
|
||
4. El flujo individual conserva como nombre oficial para carpetas y documentos el nombre proveniente del Consolidado.
|
||
5. BambooHR puede contener nombres incompletos o diferentes; se permiten coincidencias exactas, coincidencias flexibles seguras y overrides manuales confirmados.
|
||
6. Los overrides de empleados deben documentarse por nombre normalizado y, cuando sea posible, por `employeeId`.
|
||
7. El DPI puede estar almacenado como PDF, JPG/JPEG o PNG.
|
||
8. La selección automática del DPI utiliza nombre, metadata y señales como `DPI`, `RENAP`, `Documento Personal de Identificación` o `Cédula`.
|
||
9. Cuando el archivo correcto está mal nombrado en BambooHR, se permite un override `employeeId -> documentId` después de validarlo manualmente.
|
||
10. Gemini debe confirmar que el documento corresponde a un DPI guatemalteco y extraer sus datos estructurados.
|
||
11. Las validaciones críticas incluyen documento DPI de Guatemala, frente/reverso visibles y número de DPI de 13 dígitos.
|
||
12. 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.
|
||
13. 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.
|
||
14. Antes de crear un expediente se verifica si ya existe una carpeta con ese nombre para evitar duplicados.
|
||
15. 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.
|
||
16. 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.
|
||
17. 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
|
||
|
||
1. Convertir o abrir el archivo de prestaciones como Google Sheets.
|
||
2. Abrir `Extensiones -> Apps Script`.
|
||
3. Instalar el archivo `.gs` del proyecto.
|
||
4. Ejecutar `prepararTodoFiniquitosGT`.
|
||
5. Confirmar que el Apps Script haya creado/actualizado las hojas requeridas y la configuración.
|
||
6. Importar en n8n el workflow individual.
|
||
7. Configurar sus credenciales de BambooHR, Google y Gemini.
|
||
8. Guardar y publicar el workflow individual.
|
||
9. Importar el workflow masivo.
|
||
10. En `Ejecutar procesador individual`, seleccionar el workflow individual publicado.
|
||
11. Mantener `Wait For Sub-Workflow Completion` activado.
|
||
12. Verificar `CONFIG_FINIQUITOS` y el nombre correcto de la hoja Consolidado.
|
||
13. Ejecutar el MASIVO desde `Manual Trigger`.
|
||
|
||
---
|
||
|
||
## CÓMO FUNCIONA
|
||
|
||
### Flujo paso a paso
|
||
|
||
1. **Preparación:** Apps Script toma el archivo de prestaciones y prepara las hojas necesarias para automatización.
|
||
2. **Configuración:** el workflow masivo obtiene el Google Sheet, la carpeta raíz, las plantillas y los empleados autorizados.
|
||
3. **Lectura:** n8n consulta la hoja de Consolidado correspondiente.
|
||
4. **Validación:** se comprueba NO., nombre y pertenencia al lote autorizado.
|
||
5. **Loop:** se envía un empleado a la vez al procesador individual.
|
||
6. **Carpeta existente:** se evita recrear un expediente que ya exista.
|
||
7. **BambooHR:** se localiza al empleado mediante coincidencia exacta, flexible u override confirmado.
|
||
8. **Documentos:** se listan los documentos del perfil y se identifica el DPI.
|
||
9. **DPI:** se descarga el documento; se aceptan PDF, JPG/JPEG y PNG.
|
||
10. **Gemini:** se extraen número de DPI, nombres, apellidos, sexo, fecha de nacimiento, estado civil, nacionalidad, lugar de nacimiento, vecindad y otros datos visibles.
|
||
11. **Validación:** se aplican validaciones críticas y advertencias no bloqueantes.
|
||
12. **Drive:** se crea la carpeta individual y se guarda el DPI.
|
||
13. **Documentos:** se copian las plantillas oficiales de finiquito, voucher y formato de cheque.
|
||
14. **Personalización:** se reemplazan los datos y se incorporan municipio/departamento en las menciones del RENAP.
|
||
15. **Consolidado:** se actualizan los campos operativos requeridos.
|
||
16. **Resultado:** el procesador individual devuelve estado y enlaces.
|
||
17. **Continuación:** el MASIVO espera brevemente y procesa el siguiente empleado, incluso si el anterior falló.
|
||
18. **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
|
||
|
||
```text
|
||
/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
|
||
|
||
- [x] Apps Script de preparación operativo.
|
||
- [x] Workflow MASIVO funcional.
|
||
- [x] Workflow individual funcional.
|
||
- [x] Integración con BambooHR.
|
||
- [x] Extracción de DPI con Gemini.
|
||
- [x] Soporte de DPI PDF/JPG/PNG.
|
||
- [x] Creación automática de carpetas.
|
||
- [x] Generación de finiquito, voucher y formato de cheque.
|
||
- [x] Inclusión de municipio y departamento.
|
||
- [x] Manejo de nombres diferentes y overrides.
|
||
- [x] Protección contra duplicados.
|
||
- [x] Reintentos individuales mediante `SOLO_NO`.
|
||
- [x] Continuación del lote ante errores individuales.
|
||
- [x] Probado con casos reales.
|
||
- [x] Agregar enlaces definitivos de Board y PRD si existen.
|
||
- [x] Mantener CHANGELOG y DECISIONS actualizados con futuros lotes.
|
||
|
||
---
|
||
|
||
Documento mantenido por el equipo **GLM IT**.
|