# DOC. SERVICIOS APP - SHALOM FAMILIA # Modulo Inicial # Login de usuario - [validate_user_active] ## 🧾 **Descripción** **Valida si un usuario:** 1. *Existe y su contraseña es correcta* 2. *Está habilitado (**enabled = 1**) en el Doctype `User`* Es un servicio simple de autenticación básica, expuesto como endpoint público vía `frappe.whitelist(allow_guest=True)`. --- # 🚀 **Endpoint**

**`POST /api/method/validate_user_active`**

> Nota: El nombre final depende del módulo donde esté definida la función. > Ejemplo típico Frappe: > `/api/method/app.module.doctype.file.validate_user_active` --- # 🔐 **Seguridad** - **allow\_guest=True** → cualquiera puede llamarlo sin token - Solo valida credenciales usando **`check_password()`** ⚠️ Esto implica que el endpoint debe usarse únicamente desde un frontend controlado o un gateway seguro. --- # 📥 **Request Body** **Formato JSON:**

`{ "usr": "correo@dominio.com", "pwd": "contraseña"}`

--- # 📤 **Responses** ### ✅ **200 – Usuario válido**

`{ "success": true, "message": "Usuario válido y activo (check_password)."}`

--- ### ❌ **401 – Credenciales incorrectas** (Realmente devuelve 200 con success=false, pero semánticamente es un error)

`{ "success": false, "message": "Usuario o contraseña incorrectos."}`

--- ### ❌ **403 – Usuario deshabilitado**

`{ "success": false, "message": "El usuario está deshabilitado."}`

--- # 🧩 **Lógica Interna (resumen)** 1. Ejecuta **`check_password(usr, pwd)`** - Si falla → usuario o contraseña incorrectos 2. Consulta el campo `enabled`: 3. Devuelve éxito solo si: - Contraseña correcta - Usuario habilitado --- # 📚 **Schemas** ### **Entrada**

`{ "usr": "string", "pwd": "string"}`

### **Salida**

`{ "success": "bool", "message": "string"}`

--- # 🧪 **Ejemplo de uso (curl)**

`curl -X POST https://midominio.com/api/method/app.validate_user_active \-H "Content-Type: application/json" \-d '{"usr":"admin@example.com", "pwd":"123"}'`

# Guardar usuario - [saveUsersLogeds] ## 🧾 **Descripción** *Registra y actualiza información de usuarios que inician sesión desde la aplicación móvil.* *Además, valida si la versión de la app instalada es compatible con la versión mínima definida en el servidor.* **Funcionalidad:** 1. **Verifica la versión de la app** contra `versiones.json`. 2. **Crea o actualiza** el registro de un usuario en la base de datos `mysql2.users`. 3. Devuelve mensaje de éxito o error según el proceso. --- # 🚀 **Endpoint**

**`POST /save-users-logeds`**

> El nombre real depende del archivo de rutas de Laravel (web.php / api.php). --- # 🔐 **Seguridad** - Requiere enviar parámetros en el body (no hay autenticación nativa). - Se recomienda usarlo en rutas **API protegidas**. --- # 📥 **Request Body**

`{ "user": "string", "version": "string"}`

### Campos

Campo	Tipo	Requerido	Descripción
user	string	Sí	Username que se registra o actualiza.
version	string	Sí	Versión de la app instalada en el dispositivo.

--- # 📤 **Responses** ### ❗ Importante En tu código actual, la primera línea retorna **inmediatamente**:

`return [ "valor"=>true, "msn"=> "Registro actualizado",];`

Por lo tanto **todo el servicio está anulado**. Si esto es accidental, debes eliminar ese `return`. Aun así, la documentación refleja lo que *debería hacer* según el resto del código. --- ## ✔️ **Versión actualizada (200 OK)** Si la versión enviada es igual o mayor que la versión mínima del archivo `versiones.json`:

`{ "valor": true, "msn": "Registro Exitoso"}`

`{ "valor": true, "msn": "Registro actualizado"}`

--- ## ❌ **Versión desactualizada**

`{ "valor": false, "msn": "Actualize su aplicacion en Play Store", "version_app": "1.0.1", "version_service": "1.0.5"}`

--- ## ❌ **Error al registrar o actualizar usuario**

`{ "valor": false, "msn": "Registre un usuario"}`

`{ "valor": false, "msn": "Registro Actualizado"}`

--- # 🧩 **Lógica Interna (detallada)** ### 1. Leer versión mínima del archivo: **Campo utilizado:** `familia` ### 2. Convertir versiones a enteros **Ejemplo:** “1.2.3” → 123 Esto permite compararlas. ### 3. Validación: ### 4. Registrar usuario: - Si no existe → insertar username + primera sesión + última sesión - Si existe → actualizar última sesión - Base de datos usada: **mysql2** Tablas y campos usados: --- # 📚 **Esquema del JSON de version-app/versiones.json** **Se utiliza solo el campo:**

`{ "familia": "1.0.5"}`

--- # 🗃 **Schemas** ### Request

`{ "user": "string", "version": "string"}`

### Response

`{ "valor": "boolean", "msn": "string", "version_app": "string(optional)", "version_service": "string(optional)"}`

--- # 🧪 **Ejemplo de uso (curl)**

`curl -X POST https://midominio.com/api/save-users-logeds \-H "Content-Type: application/json" \-d '{"user":"jhon.doe","version":"1.0.2"}'`

--- # ⚠️ Notas importantes para documentación ### 🔴 Problema detectado **La primera línea del método cancela toda la lógica:**

`return [ "valor"=>true, "msn"=> "Registro actualizado",];`

Si quieres que el servicio funcione como en la documentación, debes eliminar ese `return`. # Términos y Condiciones - [setTermsAndConditions] ## 🧾 **Descripción** *Registra la aceptación de los Términos y Condiciones por parte del usuario logueado en la aplicación.* *El proceso localiza al empleado asociado al `user_id` (email del usuario) y actualiza los campos:* - `terminos_y_condiciones_app = 1` - **`fecha_terminos_y_condiciones = fecha/hora actual`** --- # 🚀 **Endpoint**

**`POST /set-terms-and-conditions`**

> La ruta exacta depende de cómo esté configurado en tus **`routes/api.php`**. --- # 🔐 **Seguridad** - No requiere token explícito aquí, pero el backend usa **`apiService`**, que probablemente **sí exige autenticación** hacia ERPNext. - Se recomienda proteger este endpoint detrás de autenticación de la app. --- # 📥 **Request Body**

`{ "email_logued": "string"}`

### Campos requeridos:

Campo	Tipo	Requerido	Descripción
email\_logued	string	Sí	Email del usuario con el que inició sesión en la app. Este email debe coincidir con el `user_id` del Employee.

--- # 📤 **Responses** ## ✔️ 200 – Términos aceptados correctamente

`{ "valor": true, "msn": "Terminos y Condiciones Aceptadas Correctamente"}`

--- ## ❌ 400 – Falta el email

`{ "valor": false, "msn": "Es necesario el email con el que ha entrado a la app"}`

--- ## ❌ 404 – No existe Employee asociado al usuario **Incluye ambos casos del código:**

`{ "valor": false, "msn": "Error al traer el empleado asociado"}`

--- ## ❌ 500 – Error al actualizar Employee

`{ "valor": false, "msn": "Error al aceptar terminos y condiciones", "error": { ...respuesta ERP... }}`

--- ## ❌ 500 – Error inesperado

`{ "valor": false, "msn": "Error en el servicio"}`

--- # 🧩 **Lógica Interna** 1. **Validación inicial** Si **`email_logued`** viene vacío → error 2. **Buscar Employee asociado al usuario** **Consulta en ERP:** 3. **Manejo de errores:** - Respuesta sin `data` - Array vacío 4. **Actualizar Employee** 5. **Si el response incluye** `"data"` → éxito Si no → error --- # 📚 **Schemas** ### Request Schema

`{ "email_logued": "string"}`

### Response Schema

`{ "valor": "boolean", "msn": "string", "error": "object (opcional)"}`

--- # 🧪 **Ejemplo de Uso (curl)**

`curl -X POST https://midominio.com/api/set-terms-and-conditions \-H "Content-Type: application/json" \-d '{"email_logued":"user@example.com"}'`

# Obtener Usuario (1,2,3,4) - [getUser3] ## 🧾 **Descripción** *Retorna la información del usuario ingresado en la app (empleado o estudiante).* *El servicio consulta primero la tabla **Employee** del ERP.* *Si no existe o no está activo, consulta la tabla **Student**.* *Finalmente, devuelve la información personal, laboral/educativa, permisos y datos complementarios.* *Funciona como un **servicio maestro de login/datos del usuario** para la aplicación móvil.* --- # 🚀 **Endpoint**

**`POST /get-user3`**

> El nombre real depende del archivo **`routes/api.php`**. --- # 🔐 **Seguridad** - No se ve autenticación explícita, pero las consultas al ERP (**`dbErp`**, **`ServiceErp`**) requieren token/credenciales internas. - Se recomienda protegerlo con autenticación JWT o middleware. --- # 📥 **Request Body**

`{ "username": "string"}`

### Campos

Campo	Tipo	Requerido	Descripción
username	string	Sí	Email o DNI/pasaporte. Si contiene “@” se asume email, de lo contrario documento.

--- # 🧩 **Lógica Interna Detallada** ## 1️⃣ Determinar si buscar por email o documento - Si el parámetro incluye “@” → buscar por **`emp.user_id`** - Sino → buscar por **`emp.passport_number`** ## 2️⃣ Consultar información del empleado en ERP Consulta SQL con múltiples JOIN: **Tablas involucradas:** - `tabEmployee` (principal) - `tabUser` - `tabBranch` - `tabContrato de Trabajo` - `tabDepartment` Si no encuentra empleado → pasa a modo estudiante. --- ### ❌ Errores de empleado antes de consultar estudiante: - No `valor` en la respuesta - `response` vacío → continuar con búsqueda en Student --- ## 3️⃣ Consultar información del estudiante (fallback) **Si el usuario no es empleado, consulta en:** - `tabStudent` - `tabUser` - `tabBranch` - `tabJob Applicant` - `tabRequerimiento de Personal` - `tabDesignation` - `tabDepartment` ### Validaciones de estudiante: - Si no existe →

`{ "valor": false, "msn": "Sin Estudiante: ...", "data": [] }`

- Si el usuario está deshabilitado (**`us.enabled = 0`**) →

`{ "valor": false, "msn": "Usuario Deshabilitado...", "data": [...] }`

Si todo está correcto → retorna data del estudiante. --- ## 4️⃣ Procesamiento final de empleado ### Validaciones - Si **`status = Inactive`** → usuario no puede usar la app ### Ajustes en la data: - Formato de fecha de nacimiento → **`mm-dd`** - Si contrato indeterminado → reemplazar texto - Detectar si es renovación o primer contrato (ServiceErp) - Normalizar campos: - `bank_ac_no` - `pets` - `tipo_usuario = "Empleado"` --- ## 5️⃣ Respuesta final (Empleado o Estudiante) Retorna la data enriquecida del usuario. --- # 📤 **Responses** ## ✔️ 200 – Usuario encontrado

`{ "valor": true, "msn": "Si hay data", "data": [ ... ]}`

--- ## ❌ Usuario no es empleado ni estudiante

`{ "valor": false, "msn": "Este usuario no es empleado", "data": []}`

--- ## ❌ Usuario estudiante sin permisos

`{ "valor": false, "msn": "Sin Estudiante: Su usuario no tiene permisos para acceder al aplicativo. Contactar con soporte.", "data": []}`

--- ## ❌ Usuario deshabilitado

`{ "valor": false, "msn": "Usuario Deshabilitado: Comuníquese con su administrador", "data": [ ... ]}`

--- ## ❌ Empleado inactivo

`{ "valor": false, "msn": "Empleado Inactivo: Comuníquese con su administrador", "data": [ ... ]}`

--- # 📚 **Schemas** ### Request

`{ "username": "string"}`

### Response (general)

`{ "valor": "boolean", "msn": "string", "data": "array"}`

--- # 🧪 **Ejemplo de uso (curl)**

`curl -X POST https://midominio.com/api/get-user3 \-H "Content-Type: application/json" \-d '{"username":"empleado@empresa.com"}'`

--- # ✔️ Servicios ERP usados internamente ### 1. **`send-query-database`** Método POST que ejecuta consultas SQL personalizadas en ERPNext. ### 2. `resource/Contrato de Trabajo` Consulta REST para obtener contratos de trabajo. --- # 📝 Observaciones técnicas (reales) - Código mezcla SQL dinámico en body con filtros JSON → validar inyección. - Se usa **`LIMIT 1`** en employee, pero la consulta de contratos tiene **`limit=None`**. - Campos duplicados en **`sql_query`** (ej. **`emp.bank_ac_no`** aparece 2 veces). - Es un servicio **muy grande**, podría dividirse por responsabilidad. # Obtener Version - [version] ## 🧾 **Descripción** *Obtiene la versión actual de una aplicación móvil específica.* *El servicio valida si el identificador de la app existe y, de ser así, devuelve la versión correspondiente.* **Este endpoint se usa para:** - Mostrar la versión actual al usuario - Verificar actualizaciones desde la app móvil - Controlar múltiples aplicaciones dentro del mismo backend --- # 🚀 **Endpoint**

**`POST /version`**

> La ruta final dependerá del archivo de rutas (**`routes/api.php`**). --- # 🔐 **Seguridad** - Sin autenticación explícita - Normalmente accesible para todas las apps móviles --- # 📥 **Request Body**

`{ "app": "string"}`

### Campos

Campo	Tipo	Requerido	Descripción
app	string	Sí	Identificador de la aplicación cuya versión se desea consultar.

--- # 📤 **Responses** ## ✔️ 200 – App encontrada (Versión obtenida)

`{ "valor": true, "msn": "Versión del app MiApp: 1.0.5", "version": "1.0.5"}`

*El nombre mostrado proviene de:* **`$name_app = $this->apps[$app];`** *La versión proviene de:* **`$versiones = $this->data();$version = $versiones[$app];`** --- ## ❌ 404 / 200 – App no existente > Nota: El método devuelve **200 OK** incluso cuando la app no existe. > (Esto es comportamiento actual del código.) --- # 🧩 **Lógica Interna** 1. Recibe el parámetro **`app`**. 2. Obtiene todas las versiones desde **`$this->data()`** *(método interno que no está mostrado pero retorna un array asociativo)*. 3. Valida si la clave **`app`** existe en el array versiones: - **No existe** → error - **Existe** → procede 4. Obtiene el nombre de la app desde: **`$this->apps[$app]`** 5. Obtiene la versión asociada: `$versiones[$app]` 6. Devuelve la versión actual en el message. --- # 📚 **Schema** ### Request

`{ "app": "string"}`

### Response

`{ "valor": "boolean", "msn": "string", "version": "string (opcional)"}`

--- # 🧪 **Ejemplo de Uso (curl)**

`curl -X POST https://midominio.com/api/version \-H "Content-Type: application/json" \-d '{"app":"shalom_app"}'`

**Respuesta esperada:** # Rol de usuario - [rolUsuario] ## 🧾 **Descripción** *Valida si un usuario tiene el rol **"Supervisor Nacional"** dentro del ERP.* *Busca en la tabla **`tabHas Role`** un registro cuya columna **`role = 'Supervisor Nacional'`** y **`parent = {name_usuario}`**.* --- # 🚀 **Endpoint**

`POST /rol-usuario`

> La ruta exacta depende de tu archivo `routes/api.php`. --- # 🔐 **Seguridad** - Recibe el nombre del usuario sin autenticación adicional. - Se recomienda incluir autenticación JWT o token de aplicación para mayor seguridad. --- # 📥 **Request Body** ### JSON

`{ "name": "string"}`

### Campos

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre interno del usuario en ERPNext (us.name).

--- # 🧩 **Lógica Interna del Servicio (resumen)** 1. Toma **`name`** desde el request. 2. Construye una consulta SQL hacia ERP que busca: - El usuario (**`rol.parent`**) - El rol **`"Supervisor Nacional"`** **(`rol.role`)** 3. Ejecuta: - `dbErp("POST", body, method/send-query-database)` 4. Si encuentra el rol → retorna verdadero 5. Si no lo encuentra → indica que no es supervisor 6. Maneja errores con **`try/catch`**. --- # 📤 **Responses** ## ✔️ 200 – Usuario es Supervisor Nacional

`{ "value": true, "msn": "Listado exitoso", "data": true}`

--- ## ❌ 200 – Usuario NO es supervisor

`{ "value": false, "msn": "Usuario no es supervisor", "data": false}`

--- ## ❌ 500 – Error interno al procesar

`{ "value": false, "msn": "Mensaje de excepción"}`

--- # 📚 **Schemas** ### Request

`{ "name": "string"}`

### Response

`{ "value": "boolean", "msn": "string", "data": "boolean (solo en éxito o denegado)"}`

--- # 🧪 Ejemplo de uso (curl)

`curl -X POST https://midominio.com/api/rol-usuario \-H "Content-Type: application/json" \-d '{"name":"jhon.doe@empresa.com"}'`

# Permisos del modulo - [permissions-module] ## 🧾 **Descripción** *Devuelve un listado de permisos de módulos habilitados para el usuario autenticado en la app.* *Además, determina si el usuario tiene acceso al módulo **“solicitudes\_de\_pagos”**, validándolo contra listas internas y datos del ERP (tabla **`Validacion de Pagos Gerencia`**).* --- # 🚀 **Endpoint**

**`POST /permissions-modules`**

--- # 🔐 **Seguridad** - Requiere usuario enviado en el body. - No usa autenticación adicional dentro del servicio, pero sí consulta el ERP vía **`dbErp()`**. --- # 📥 **Request Body**

`{ "usuario": "string"}`

### Campos

Campo	Tipo	Requerido	Descripción
usuario	string	Sí	Email del usuario de la app.

--- # 📤 **Responses** ## ✔️ 200 – Respuesta exitosa

`{ "valor": true, "msn": "lista de dni validacion módulos", "data": { "informacion_personal": true, "marcaciones": true, "otros_descuentos": true, "capacitacion": true, "contrato_de_trabajo": true, "boletas_de_pago": true, "solicitudes": true, "reconocimiento_de_deuda": true, "centro_de_ayuda": true, "supervision": true, "asistencia": true, "contratacion": true, "convocatoria": true, "documentos_internos": true, "solicitudes_de_pagos": true }}`

> **Nota:** El valor de **`solicitudes_de_pagos`** depende del usuario. --- ## ❌ 400 – Falta el usuario en la solicitud

`{ "valor": false, "msn": "Debe enviar el usuario"}`

--- # 🧩 **Lógica Interna** ### 1. Validar que se envíe el parámetro **`usuario`** Si no existe → retorna error. ### 2. Lista inicial de usuarios con permiso en **`solicitudes_de_pagos`** **Hardcoded en el código:**

`[ "45738484@shalomcontrol.com", "40650120@shalomcontrol.com", "40377937@shalomcontrol.com"]`

### 3. Consulta al ERP **Consulta la tabla:** **`tabValidacion de Pagos Gerencia`** **Utiliza:** **`SELECT usuario FROM `tabValidacion de Pagos Gerencia``** Si la respuesta contiene valores, se agregan a la lista general. ### 4. Mezcla de listas **Se combinan:** - Lista hardcodeada - Lista proveniente del ERP ### 5. Validación final **`solicitudes_de_pagos = in_array(usuario, lista_combinada)`** ### 6. Todos los demás permisos se marcan como `true` --- # 📚 **Schema de Respuesta** ### **`data`** (permisos)

`{ "informacion_personal": true, "marcaciones": true, "otros_descuentos": true, "capacitacion": true, "contrato_de_trabajo": true, "boletas_de_pago": true, "solicitudes": true, "reconocimiento_de_deuda": true, "centro_de_ayuda": true, "supervision": true, "asistencia": true, "contratacion": true, "convocatoria": true, "documentos_internos": true, "solicitudes_de_pagos": "boolean dinámico"}`

--- # 🧪 **Ejemplo de uso (curl)**

`curl -X POST https://midominio.com/api/permissions-modules \-H "Content-Type: application/json" \-d '{"usuario":"user@example.com"}'`

# Verificar *** - [verifyDownloadSalary] ## 🧾 **Descripción** *Valida si un trabajador ha descargado su boleta de pago correspondiente al mes anterior.* *La validación solo aplica del **día 1 al 7 de cada mes**; fuera de ese rango, se asume automáticamente como validación positiva.* *El servicio consulta el registro de descargas en la tabla **`historial_procesos_app`**.* --- # 🚀 Endpoint

**`POST /verify-download-salary`**

> La ruta final depende de cómo esté configurada en **`routes/api.php`**. --- # 🔐 Seguridad No se valida token en el controlador, pero se recomienda proteger el endpoint detrás de autenticación de la app. --- # 📥 Request Body

`{ "employee": "string", "fechaIngreso": "string (YYYY-MM-DD)"}`

### Campos requeridos

Campo	Tipo	Obligatorio	Descripción
employee	string	Sí	Código del empleado (ID del trabajador).
fechaIngreso	string	Sí	Fecha de ingreso del trabajador en formato `YYYY-MM-DD`.

--- # 🧠 Reglas de negocio 1. **Validación por fecha** Si la fecha actual es mayor al día 7 del mes → **no corresponde validación**. 2. Obtiene el **mes anterior** y convierte el número en texto (ej. 01 → Enero). 3. Si **`fechaIngreso >= primer día del mes actual`**, entonces el trabajador ingresó recientemente → **no se valida descarga**. 4. Consulta en la BD (**`mysql2.historial_procesos_app`**) si existe un registro: - `proceso = 'NOMINA'` - `empleado = ` - `month` y `year` del mes anterior - Registros con fecha ascendente 5. Si existe registro → sí descargó Si no → debe descargar su boleta pendiente. --- # 📤 Responses ### 🟦 Caso 1: Fuera del rango de fechas (después del día 7)

`{ "valor": true, "msg": "No corresponde validación, fuera de fecha."}`

--- ### 🟥 Error: falta fecha de ingreso

`{ "valor": false, "msg": "Debe enviar la fecha de ingreso del trabajador"}`

--- ### 🟥 Error: falta empleado

`{ "valor": false, "msg": "Debe enviar el código de empleado del trabajador"}`

--- ### 🟦 Caso 2: Ingreso reciente (no se valida)

`{ "valor": true, "msg": "No corresponde validación"}`

--- ### 🟩 Caso 3: El trabajador SÍ descargó su boleta

`{ "valor": true, "msg": "Si descargó boleta."}`

--- ### 🟥 Caso 4: El trabajador NO descargó su boleta

`{ "valor": false, "msg": "Tiene pendiente descargar su boleta de pago del mes de , descárguelo desde el módulo Boletas de Pago."}`

**Ejemplo:**

`{ "valor": false, "msg": "Tiene pendiente descargar su boleta de pago del mes de Enero 2025, descárguelo desde el módulo Boletas de Pago."}`

--- # 🔎 Ejemplo de consumo (curl)

`curl -X POST https://midominio.com/api/verify-download-salary \-H "Content-Type: application/json" \-d '{"employee":"EMP-001","fechaIngreso":"2023-02-15"}'`

# Obtener publicaciones - [obtainPosts2] ## 🧾 **Descripción** *Obtiene publicaciones (posts) asociadas a un usuario y una categoría determinada.* *La lógica de filtrado, cacheo o búsqueda se realiza internamente mediante el método:*

*`$this->postsCache($user, $category)`*

*Este servicio únicamente recibe los parámetros, solicita la data a **`postsCache()`** y devuelve la respuesta.* --- # 🚀 **Endpoint**

**`POST /obtain-posts`**

> El nombre final dependerá de tu archivo `routes/api.php`. --- # 🔐 **Seguridad** No realiza autenticación explícita. Si requieres seguridad, debe implementarse a nivel de ruta (middleware). --- # 📥 **Request Body**

`{ "cookie": "string (opcional)", "user": "string", "category": "string"}`

### Campos

Campo	Tipo	Requerido	Descripción
cookie	string	No	Cookie del usuario. En este servicio no se usa, pero está recibido.
user	string	Sí	ID o email del usuario para obtener las publicaciones.
category	string	Sí	Categoría de las publicaciones a listar.

--- # 📤 **Respuesta (200 OK)** ### Ejemplo de respuesta:

`{ "data": [ // contenido devuelto por postsCache() ]}`

La estructura interna depende íntegramente de lo que retorne **`postsCache()`**. --- # 🧩 **Lógica Interna (resumen)** 1. Recibe **`cookie`**, **`user`**, y **`category`**. 2. Llama a: `postsCache($user, $category)` 3. Devuelve un JSON simple: --- # 📚 **Schema de Respuesta**

`{ "data": "array | object según postsCache()"}`

--- # 🧪 **Ejemplo en curl**

`curl -X POST https://midominio.com/api/obtain-posts \-H "Content-Type: application/json" \-d '{"user":"user@example.com","category":"capacitacion"}'`

# Página nueva - [registerLikeForPosts] ## 🧾 **Descripción** *Permite registrar un **Like** o **Dislike** sobre una publicación del módulo Publicaciones en ERPNext.* *La acción se ejecuta usando el endpoint interno **`frappe.desk.like.toggle_like`**, el cual requiere un **cookie de sesión válido**.* --- # 🚀 **Endpoint**

**`POST /register-like-for-posts`**

> La ruta exacta depende de tu archivo **`routes/api.php`**. --- # 🔐 **Seguridad** Este endpoint **requiere el cookie de sesión Frappe**, el cual se envía desde la aplicación móvil. Sin el cookie, el servicio **rechaza la operación**. --- # 📥 **Request Body**

`{ "cookie": "string", "name": "string", "marked": true}`

### Campos requeridos:

Campo	Tipo	Requerido	Descripción
cookie	string	Sí	Cookie de sesión válido en ERPNext.
name	string	Sí	Nombre del documento `Publicaciones` al que se aplicará Like/Dislike.
marked	boolean	Sí	`true` = Like, `false` = Dislike.

--- # 📤 **Responses** ## ✔️ **200 – Like o Dislike registrado correctamente**

`{ "valor": true, "msn": "Like para publicación correcto", "data": []}`

(El mensaje cambia dependiendo de `marked`) --- ## ❌ **400 – Falta de parámetros** ### Falta nombre

`{ "valor": false, "msn": "Es necesario el nombre de la publicación para dar like", "data": []}`

### Falta marked

`{ "valor": false, "msn": "Es necesario el estado del like", "data": []}`

### Falta cookie

`{ "valor": false, "msn": "Es necesario el cookie para dar like", "data": "cookie_recibida"}`

--- ## ❌ **500 – Error desde ERPNext**

`{ "valor": false, "msn": "Error al generar Servicio", "data": ""}`

--- # 🧩 **Lógica Interna** 1. Valida parámetros obligatorios: **`name`**, **`marked`**, **`cookie`**. 2. Construye la propiedad **`add`**: - **`marked = true`** → `"Yes"` - **`marked = false`** → `"No"` 3. Construye la llamada a ERPNext: 4. ERPNext registra o quita el Like. 5. Devuelve mensaje según operación: "Like" o "Dislike". --- # 📚 **Schemas** ### Request Schema

`{ "cookie": "string", "name": "string", "marked": "boolean"}`

### Response Schema

`{ "valor": "boolean", "msn": "string", "data": "array | object"}`

--- # 🧪 Ejemplo de uso (curl)

`curl -X POST https://midominio.com/api/register-like-for-posts \-H "Content-Type: application/json" \-d '{ "cookie": "sid=12345abcde", "name": "PUB-00012", "marked": true}'`

# Obtener Comentarios Post (1) - [obtain-comments2] ## 🧾 Descripción *Obtiene los comentarios de una publicación específica del módulo **Publicaciones (Frappe/ERPNext)** junto con información adicional del empleado que realizó cada comentario.* *El servicio:* 1. *Consulta los comentarios del documento **`Publicaciones/{post_name}`**.* 2. *Obtiene la lista de empleados activos desde ERP para enlazar **`owner → nombre_completo`**.* 3. *Ordena todos los comentarios por fecha de creación en orden ascendente.* 4. *Devuelve la lista final enriquecida con el nombre completo del usuario comentador.* --- # 🚀 Endpoint

**`POST /obtain-comments-by-post`**

*(La ruta final depende de la configuración en routes/api.php)* --- # 🔐 Seguridad - Requiere **cookie de sesión Frappe** válida (el usuario debe estar logueado). - Sin cookie → fallo en la consulta al endpoint de ERP. --- # 📥 Request Body

`{ "cookie": "string", "post_name": "string", "start": 0, "limit": 10}`

### Campos

Campo	Tipo	Requerido	Descripción
cookie	string	Sí	Cookie de sesión enviada por ERP para realizar consultas autenticadas.
post\_name	string	Sí	Nombre (ID) de la publicación en ERP, ejemplo: `"PUB-0001"`.
start	number	No	Índice inicial para paginación de comentarios.
limit	number	No	Cantidad máxima de comentarios a obtener.

--- # 📤 Responses ## ✔️ 200 – Comentarios obtenidos correctamente

`{ "data": [ { "owner": "user@example.com", "name": "COM-0001", "content": "Buen trabajo equipo!", "creation": "2025-01-01 10:30:00", "nombre_completo": "Juan Pérez" } ]}`

--- ## ❌ 400/500 – Error en la solicitud a ERPNext Si ocurre una excepción desde Guzzle (cookie inválida, publicación inexistente, etc.): **Respuesta directa del error de ERPNext**, ejemplo:

`{"exc": ["Traceback...", "..."]}`

--- # 🧩 Lógica Interna (Resumen Técnico) 1. **Validación de entradas** - Se extraen: **`cookie`**, **`post_name`**, **`start`**, **`limit`**. 2. **Consulta de comentarios** - **Endpoint Frappe llamado:** **`GET APICAPACITACION/resource/Publicaciones/{post_name}`** - **Envia parámetros:** 3. **Consulta de empleados activos** - **Solicita:** **`Employee?fields=["name","nombre_completo","user_id"]&filters=[["status","=","Active"]]`** - **Construye un mapa:** **`user_id → nombre_completo`** 4. **Enriquecimiento de comentarios** - **A cada comentario se le agrega:** **`nombre_completo = jsonEmployee[owner] ?? owner`** 5. **Ordenamiento** - Orden ascendente por la fecha **`creation`**. 6. **Resultado final**

`{ "data": [ ...comentarios_ordenados... ] }`

--- # 📚 Schema de respuesta final ### Comentario:

`{ "owner": "string", "name": "string", "content": "string", "creation": "datetime", "nombre_completo": "string"}`

--- # 🧪 Ejemplo de uso (curl)

`curl -X POST https://midominio.com/api/obtain-comments-by-post \-H "Content-Type: application/json" \-d '{ "cookie":"sid=abc123", "post_name":"PUB-0005", "start":0, "limit":20}'`

# Enviar Comentarios Post (1) - [sendComment] ## 🧾 **Descripción** *Registra un nuevo comentario dentro de una publicación del módulo de “Publicaciones” en ERP/Capacitación.* *El servicio envía la información del comentario a un endpoint del ERP mediante autenticación por cookie.* --- # 🚀 **Endpoint**

**`POST /send-comment`**

> La ruta real depende del archivo de rutas Laravel (**`api.php`**). --- # 🔐 **Seguridad** - Requiere **cookie de sesión ERP** enviada por el cliente. - La cookie se usa directamente en la cabecera: --- # 📥 **Request Body**

`{ "content": "string", "parent": "string", "cookie": "string"}`

### **Descripción de campos**

Campo	Tipo	Requerido	Descripción
content	string	Sí	Texto del comentario.
parent	string	Sí	ID del documento `Publicaciones` al que pertenece el comentario.
cookie	string	Sí	Cookie de sesión válida del ERP.

**Otros campos se envían de forma fija al backend:**

`{ "parenttype": "Publicaciones", "parentfield": "comments"}`

--- # 📤 **Responses** ## ✔️ **200 – Comentario creado correctamente**

`{ "valor": true, "msn": "Creado correctamente", "data": { ... }}`

--- ## ❌ **400 – Error en datos del cliente** El servicio no valida explícitamente los campos, pero si backend rechaza:

`{ "valor": "false", "msn": "Error de servidor", "data": "Detalle del error del ERP"}`

--- ## ❌ **500 – Error al procesar la solicitud** Cuando la API del ERP responde con error:

`{ "valor": "false", "msn": "Error de servidor", "data": ""}`

--- # 🧩 **Lógica interna del servicio** 1. Crea un cliente **`ApiRest`** con manejo de cookies. 2. Construye los datos del comentario: - `content` - `parent` (publicación) - `parenttype = Publicaciones` - `parentfield = comments` 3. Envía un **`POST`** al endpoint del ERP: 4. Maneja error HTTP (BadResponseException). 5. Si la respuesta contiene `data`, devuelve éxito. 6. Si no, marca error de creación. --- # 🗃 **Schemas** ### Request Schema

`{ "content": "string", "parent": "string", "cookie": "string"}`

### Response Schema

`{ "valor": "boolean|string", "msn": "string", "data": "object"}`

--- # 🧪 **Ejemplo de uso (curl)**

`curl -X POST https://midominio.com/api/send-comment \-H "Content-Type: application/json" \-d '{ "content":"Excelente publicación", "parent":"PUB-00045", "cookie":"sid=cd2312fa..."}'`

# Modulo Información Personal # Obtener Usuario (2) - [get-user3] ## 🧾 Descripción *Obtiene la información completa de un usuario del sistema, ya sea **Empleado** o **Estudiante**, de acuerdo al identificador enviado (email o DNI/pasaporte).* *Retorna datos personales, laborales, de contrato y estado del usuario.* *Si es empleado, consulta tablas de Employee —si no existe— consulta Student.* --- # 🚀 Endpoint

**`POST /get-user3`**

> La ruta final depende de tus archivos **`api.php`**. --- # 🔐 Seguridad - No valida token aquí, pero depende del mecanismo usado dentro de **`general->dbErp`** y **`general->ServiceErp`**. - Debe ser usado desde una app autenticada. --- # 📥 Request Body

`{ "username": "string"}`

### Parámetros

Campo	Tipo	Requerido	Descripción
username	string	Sí	Email del usuario o número de documento/pasaporte.

--- # 📤 Respuestas ## ✔️ 200 – Usuario encontrado (Empleado) --- ## ✔️ 200 – Usuario encontrado (Estudiante) --- ## ❌ Usuario no encontrado en Employee ni Student

`{ "valor": false, "msn": "Sin Estudiante: Su usuario no tiene permisos para acceder al aplicativo. Contactar con soporte.", "data": []}`

--- ## ❌ Empleado inactivo

`{ "valor": false, "msn": "Empleado Inactivo: Comuníquese con su administrador para que pueda verificar el estado de su empleado.", "data": [ ... ]}`

--- ## ❌ Usuario estudiante deshabilitado

`{ "valor": false, "msn": "Usuario Deshabilitado: Comuníquese con su administrador para que pueda verificar el estado de su empleado.", "data": [ ... ]}`

--- # 🧩 Lógica del Servicio ### 1️⃣ Determinar tipo de búsqueda Si el username contiene **@**, se busca por: **`Employee.user_id = username`** Si no: **`Employee.passport_number = username`** --- ### 2️⃣ Consulta principal (Employee) Usa **`dbErp`** con una consulta SQL dinámica unida a: - tabEmployee - tabUser - tabBranch - tabContrato de Trabajo - tabDepartment Si **no hay resultados** → se intenta en Student. --- ### 3️⃣ Consulta secundaria (Student) **Busca en:** - tabStudent - tabUser - tabBranch - tabJob Applicant - tabRequerimiento de Personal - tabDesignation - tabDepartment Si no existe → usuario sin permisos. --- ### 4️⃣ Validaciones adicionales - Employee con status **`"Inactive"`** → error. - Student con **`enabled = 0`** → error. - Formatear **`fecha_de_nacimiento`** → **`"m-d"`**. --- ### 5️⃣ Validación de contratos **Se consulta:** `resource/Contrato de Trabajo` **Se determina:** - `"primer_contrato"` o - `"renovacion"` --- ### 6️⃣ Ajuste final de campos - pets → transformado a “0” si viene null. - Se asignan alias y campos calculados. --- # 📚 Response Schema ### Para Empleado **Incluye (parcial):**

Campo	Descripción
name	ID del Employee
employee\_name	Nombre completo
tipo\_usuario	"Empleado"
status	Active, PreActivo, Inactive
vigencia\_contrato	Rango de fechas
contratacion	primer\_contrato / renovacion
pets	Valor convertido a string
fecha\_de\_nacimiento	mm-dd

Más de 40 campos adicionales según tu SQL. --- ### Para Estudiante **Incluye:**

Campo	Descripción
name	ID del Student
employee\_name	Nombre completo
tipo\_usuario	Estudiante
statusUser	1 ó 0
user\_image	Foto
gender	Género
dni	Documento

--- # 🧪 Ejemplo curl

`curl -X POST https://midominio.com/api/get-user3 \-H "Content-Type: application/json" \-d '{"username": "juan.perez@empresa.com"}'`

# Actualizar Datos del Usuario (1) - [update-perfil-info] ## 🧾 **Descripción** *Actualiza la información de perfil del empleado dentro del ERP (doctype **Employee**) mediante una petición **PUT**, modificando uno o varios de los siguientes datos:* - Número de celular (**`cell_number`**) - Correo personal (**`personal_email`**) - Dirección permanente (**`permanent_address`**) *Solo actualiza los campos enviados; los no enviados no se modifican.* --- # 🚀 **Endpoint** > La ruta real depende del archivo **`routes/api.php`**. --- # 🔐 **Seguridad** - Requiere que la app ya tenga autenticación o sesión aplicada. - Internamente el servicio usa **`ServiceErp`** (ERPNext API con permiso necesario). --- # 📥 **Request Body**

`{ "employe": "HR-EMP-001", "celular": "987654321", "correo": "example@correo.com", "direccion": "Av. Los Olivos 123"}`

### Campos

Campo	Tipo	Requerido	Descripción
employe	string	✔️ Sí	ID del empleado en ERPNext (`Employee.name`).
celular	string	No	Nuevo número de celular.
correo	string	No	Nuevo correo personal. (Actualiza `personal_email`).
direccion	string	No	Nueva dirección permanente del empleado.

--- # 🧩 **Validaciones** 1. **employe vacío** → se devuelve error mediante `responseValidate()`. 2. Los demás campos son opcionales. 3. Solo se actualizan los campos enviados. --- # 📤 **Responses** ## ✔️ 200 – Actualización exitosa > Nota: El valor **`"value": false`** parece un bug en tu código, ya que indica éxito pero devuelve **`false`**. > Te lo dejo documentado según tu implementación real. --- ## ❌ 400 – Faltan parámetros requeridos Ejemplo cuando no se envía **`employe`**:

`{ "valor": false, "msn": "Debe enviar el empleado", "data": []}`

*(Respuesta generada por **`responseValidate()`**)* --- # 🧠 **Lógica Interna (Resumen)** 1. Recibe parámetros del request. 2. Si **`employe`** está vacío → error. 3. Crea un arreglo `updateKeys` solo con los campos enviados. 4. Llama a: Con el body: 5. Devuelve la respuesta del ERP. --- # 📚 **Schemas** ### Request

`{ "employe": "string", "celular": "string (opcional)", "correo": "string (opcional)", "direccion": "string (opcional)"}`

### Response --- # 🧪 **Ejemplo de Uso (curl)** # Actualizar Imagen de Perfil del Usuario (1) - [update-img-user] ## 🧾 Descripción *Actualiza la imagen de perfil de un usuario en ERPNext.* *El proceso incluye:* 1. Recepción de un archivo enviado desde la app. 2. Subida del archivo al endpoint de ERPNext: **`method/upload_file`**. 3. Obtención de la URL generada del archivo. 4. Actualización del campo **`user_image`** del **User**. 5. Actualización del campo **`image`** en el **Employee** asociado (si existe). --- # 🚀 Endpoint

**`POST /update-img-user`**

> La ruta exacta dependerá del archivo de rutas Laravel (**`api.php`**). --- # 🔐 Seguridad - La función no valida sesión o token, pero el endpoint llamado en ERPNext usa **cookies de sesión Guest**, lo que indica que debe usarse desde un backend confiable. - Se recomienda protegerla en la API propia. --- # 📥 Request (Multipart / Form-Data) ### Campos requeridos

Campo	Tipo	Requerido	Descripción
file	file	Sí	Imagen a subir (jpg, png, etc.)
user	string	Sí	Nombre del usuario en ERPNext para actualizar (`User.name`).

### Ejemplo (form-data)

`file: avatar.pnguser: user@example.com`

--- # 📤 Responses ## ✔️ 200 – Imagen actualizada correctamente

`{ "valor": true, "msn": "Imagen de usuario actualizado correctamente", "data": { ... }}`

--- ## ❌ 400 – Faltan datos o error al subir archivo Ejemplo de error al no recibir archivo:

`{ "msn": "File could not be processed"}`

--- ## ❌ 500 – Error de carga o actualización

`{ "valor": false, "msn": "Error al actualizar la imagen de usuario", "data": { ... }}`

--- # 🧩 Lógica Interna ### 1. **Lectura del archivo** ### 2. **Subida a ERPNext** - Endpoint usado: `POST /method/upload_file` - Cabecera usada: `Cookie: full_name=Guest; sid=Guest; system_user=no; user_id=Guest; user_image=` > ⚠️ Se sube el archivo como usuario Guest. ### 3. **Validación de respuesta** Debe existir: `message.file_url` Si no existe → error. ### 4. **Actualizar información del User**

`PUT resource/User/{user}{ "user_image": ""}`

### 5. **Actualizar Employee si corresponde** - Busca Employee cuyo **`user_id`** coincida: Si existe: --- # 📚 Request/Response Schemas ### Request (multipart/form-data)

`file: Fileuser: string`

### Response (success)

`{ "valor": true, "msn": "Imagen de usuario actualizado correctamente", "data": { "user_image": "url_file" }}`

--- # 🧪 Ejemplo de uso (curl)

`curl -X POST https://midominio.com/api/update-img-user \ -F "file=@/home/user/avatar.png" \ -F "user=user@example.com"`

# Modulo de Asistencia y Marcaciones (Marcaciones) # Obtiene descarga boleta de pago (1,2,3,4,5,6,7,8) - [getDownloadBoletaPago] ## 🧾 **Descripción General** *Este servicio valida si un empleado debe descargar su boleta de pago (Salary Slip) correspondiente al mes anterior.* *La validación depende:* - Del **día del mes actual** - Del **estado del empleado** - De si existe o no una boleta generada - De si dicha boleta está habilitada - De si ya registró una descarga previa *La lógica se usa para **bloquear marcaciones o solicitudes** cuando un trabajador tiene una boleta pendiente por descargar.* --- # 🚀 **Endpoint** **Parámetro Path:**

Parámetro	Tipo	Requerido	Descripción
empleado	string	Sí	Código del empleado (Employee.name en ERPNext).

--- # 🔐 **Seguridad** No usa autenticación dentro de esta función, pero depende de endpoints internos ERPNext vía **`dbErp`**. Se recomienda incluirlo dentro de rutas protegidas. --- # 🧠 **Flujo Lógico (Resumen Ejecutivo)** 1. **Validación de fechas** - Si el día actual es mayor a **3**, no se hace validación → se retorna éxito. 2. **Consultar datos del empleado** - Obtiene desde ERP: - **`fecha_de_ingreso_real`** - **`status`** 3. **Casos especiales por estado** - Si el empleado está en **PreActivo**, no se valida. 4. **Determinar si corresponde validar** - Calcula el **último día del mes anterior**. - Si el ingreso del trabajador es posterior a ese mes → no se valida. 5. **Validar si existe boleta generada** - Consulta Salary Slip del mes anterior. - Si no existe boleta → no corresponde validar. 6. **Validar si la boleta mensual está habilitada (Estado Boleta Mensual)** - Revisa si está habilitada para ese mes. 7. **Verificar si ya descargó boleta** - Revisa tabla **`historial_procesos_app`** en MySQL. - Si no descargó → retorna mensaje de pendiente. 8. **Caso final** - Si todo está correcto → retorna éxito. --- # 📥 **Request** Sin body. Solo recibe el parámetro **`{empleado}`** en la URL. --- # 📤 **Responses** ### ✔️ 200 – No corresponde validación (día mayor a 3)

`{ "status": true, "msn": "No está dentro del rango de fecha de validación"}`

--- ### ✔️ 200 – Empleado en PreActivo

`{ "status": true, "msn": "No validar descarga de boleta en PreActivo"}`

--- ### ✔️ 200 – No corresponde validación (ingresó después)

`{ "status": true, "msn": "No tiene boleta de pago por lo tanto no se valida"}`

--- ### ❌ 200 – Boleta pendiente por descargar (validación negativa)

`{ "status": false, "msn": "Para poder registrar su marcación o realizar alguna solicitud, descargar su boleta pendiente del mes"}`

--- ### ✔️ 200 – Boleta descargada previamente

`{ "status": true, "msn": "Se ha descargado la boleta de pago"}`

--- ### ✔️ 200 – Error capturado (retorna como éxito) > *Este mensaje parece incorrecto para el contexto (habla de contrato en vez de boleta), pero se documenta tal como el código lo retorna.* --- # 📚 **Lógica de Consultas Usadas** ## 1. Obtener datos del empleado Consulta a ERP: ## 2. Validar Salary Slip del mes anterior

`SELECT posting_dateFROM `tabSalary Slip`WHERE employee = %(employee)s AND posting_date BETWEEN %(fecha_inicio)s AND %(fecha_fin)s`

## 3. Validar estado de boleta (habilitado) ## 4. Validar si el empleado ya descargó su boleta Tabla: **historial\_procesos\_app (mysql2)** Filtro: - proceso = NOMINA - employee - month - year --- # 🧩 **Posibles Errores de Diseño (para tu control interno)** - El `catch` retorna mensaje incorrecto: *“Se ha descargado el contrato de trabajo”*. - En validación final siempre retorna “status: true” aunque haya fallas. - Se usa `POST` en algunas consultas SQL cuando debería ser `GET`. (Solo informativo; no se incluye en documentación oficial si no lo deseas.) # Obtiene descarga Renovación de contrato (1,2,3,4,5,6,7,8) - [getRenovacionContrato] ## 🧾 **Descripción** *Valida si un trabajador tiene pendiente la descarga de su **renovación de contrato**, lo cual puede bloquear el registro de marcaciones o solicitudes dentro del aplicativo.* *El servicio evalúa fechas, estado del trabajador y el registro interno en base MySQL donde se guarda el historial de descargas realizadas.* --- # 🚀 **Endpoint** > **`{empleado}`** corresponde al código del empleado (Employee.name en ERPNext). --- # 🔐 **Seguridad** - Requiere que el cliente esté autenticado (según arquitectura de la app). - Accede a ERP (Frappe) mediante un servicio interno (**`dbErp`**). --- # 📥 **Parámetros**

Parámetro	Tipo	Requerido	Descripción
empleado	string	Sí	Código único del empleado en ERPNext.

--- # 📤 **Responses** ### ✔️ 200 – No corresponde validar renovación (fuera de fecha) El proceso solo se ejecuta si **día >= 26**. Si es antes, devuelve:

`{ "status": true, "msn": "No es el día correcto para la renovación de contrato"}`

--- ### ✔️ 200 – Validación NO necesaria (no aplica por antigüedad) Si el empleado ingresó después del mes previo:

`{ "status": true, "msn": "Se ha descargado el contrato de trabajo"}`

--- ### ❌ 200 – Debe descargar el contrato de renovación (pendiente) El empleado tiene renovación generada y habilitada, pero **no tiene registro de descarga**:

`{ "status": false, "msn": "Para poder registrar su marcación o realizar alguna solicitud, descargar su renovación de contrato"}`

--- ### ✔️ 200 – Renovación ya descargada La base MySQL registra descarga previa:

`{ "status": true, "msn": "Se ha descargado el contrato de trabajo"}`

--- ### ✔️ 200 – Error controlado Ante cualquier excepción:

`{ "status": true, "msn": "Se ha descargado el contrato de trabajo"}`

--- # 🧩 **Flujo del Servicio** 1. Verifica el **día actual** - Si día < 26 → no corresponde validar 2. Obtiene datos del empleado desde ERP (`fecha_de_ingreso_real`) 3. Calcula: - Último día del mes anterior - Mes actual (texto) 4. Si el ingreso del empleado es **anterior al último día del mes previo**, aplica validación. 5. Consulta en ERP: - Solicitudes de renovación para este empleado - Con criterios: - Mes - Año - Código del empleado - `renueva = "Si"` - documento validado 6. Si tiene renovación pendiente: - Consulta base MySQL2 → tabla `historial_procesos_app` - Busca registro del proceso `descargaContratoRenovacion` - Si no existe → debe descargar renovación 7. Si ya está registrado → permitir normal funcionamiento. --- # 📚 **Consultas utilizadas** ### A. Obtener datos del empleado

`SELECT fecha_de_ingreso_realFROM `tabEmployee`WHERE name = {empleado}`

### B. Consulta de renovaciones ### C. Validación de descarga --- # 🧪 **Ejemplo de consumo (HTTP)** ### Request: ### Response (pendiente): # Consulta si existe documento del puesto (1, 2,3) - [getDocumentPuesto] ## 🧾 **Descripción** *Permite obtener el documento **MOF (Manual de Organización y Funciones)** asociado a un puesto específico registrado en el ERP, consultando el Doctype **Designation**.* *Este servicio se utiliza para mostrar o validar documentación laboral relacionada al cargo del trabajador.* --- # 🚀 **Endpoint** > También puede enviarse como parámetro directo según cómo se defina en routes: --- # 🔐 **Seguridad** - El endpoint no exige autenticación explícita en el código. - Se recomienda protegerlo mediante API Token o Middleware según la arquitectura. --- # 📥 **Parámetros de Entrada** ### **Query / Path Parameter**

Parámetro	Tipo	Requerido	Descripción
puesto	string	Sí	Nombre del Designation cuyo MOF se desea obtener.

--- # 📤 **Responses** ## ✔️ **200 – Documento encontrado** - **`data`** contiene el valor del campo **`mof`** del Doctype **Designation**. --- ## ❌ **404 – Documento no encontrado** Se devuelve cuando el puesto no existe o no tiene MOF asociado. --- # 🧠 **Lógica Interna (Resumen)** 1. Verifica que se haya enviado un nombre de puesto. 2. Construye una consulta GET hacia: **`resource/Designation`** Con: - `filters`: `[["name","=", puesto]]` - `fields`: `["mof"]` 3. Envía la solicitud mediante: `ServiceErp("GET", null, body, APICAPACITACION."resource/Designation")` 4. Evalúa la respuesta: - Si encuentra registros → devuelve el `mof`. - Si no encuentra → error. --- # 📚 **Schema** ### **Response** --- # 🧪 **Ejemplo de Uso (curl)** **Respuesta esperada:** # Verifica los documentos descargados (1, 2) - [verifyDownloadedDocuments] ## **Descripción** *Este servicio valida si un empleado ha completado la **descarga obligatoria de documentos institucionales** dentro del aplicativo.* *Además, verifica si el empleado ha registrado previamente sus documentos de ingreso (elección de banco, declaración de AFP/ONP, etc.).* *El proceso consulta tanto **ERPNext** como **la base de datos MySQL2** para construir un resumen de los documentos descargados y determinar si el empleado tiene **todos los documentos obligatorios** descargados.* --- ## **Parámetros**

Parámetro	Tipo	Descripción
`$employee`	string	Código del empleado (Employee.name) que se va a validar.

--- ## **Proceso general** 1. **Validación inicial de datos del empleado** - Realiza una consulta a ERPNext para obtener los campos: - `eleccion_banco` - `afiliado_fondo_pensiones` - `elección_fondo_pensiones` - Si el empleado no existe, devuelve un error. 2. **Validación de documentos de ingreso** - Antes de validar documentos descargados, se comprueba que el empleado ya **subió sus documentos de ingreso**. - Si falta alguno de estos: - Elección de banco - Si está afiliado o no al fondo de pensiones - Selección AFP u ONP → Se retorna: **"Primero suba los documentos de ingreso"** 3. **Obtención del historial de descargas** - Consulta la tabla **`historial_procesos_app`** en MySQL2. - Se recuperan registros para los procesos: - descargaContratoTrabajo - descargaReglamentoInternoTrabajo - descargaRecomentacionesSST - descargaConvenioDescuento - descargaDeclaracionJuradaDomicilio - descargadeclaracionJuradaSNPSPP - descargaPoliticasSalariales - registroEPP - descargaPETSAlmacenamiento - descargaPETSManipulacion - descargaMOF - descargaPoliticasDescuentosPorDanios 4. **Construcción del resumen por empleado** - Cada documento es asignado como: - `1` → descargado - `0` → pendiente 5. **Validación del 100% de documentos** - Si todos los procesos están registrados → **`total_documentos = true`** - Si falta alguno → **`total_documentos = false`** 6. **Validación adicional: Cambio de modalidad** - Si el empleado tiene alguna "Solicitud de Cambio de Modalidad" aprobada (`docstatus != 2`), se considera **descargado automáticamente el contrato de trabajo**. 7. **Retorno final del estado del empleado** --- ## **Respuesta exitosa**

`{ "valor": true, "data": { "empleado": "EMP-001", "descargaContratoTrabajo": 1, "descargaReglamentoInternoTrabajo": 1, "descargaRecomendacionesSST": 0, "descargaConvenioDescuento": 1, "descargaDeclaracionJuradaDomicilio": 1, "descargaDeclaracionJuradaSNPSPP": 0, "descargaPoliticasSalariales": 1, "registroEPP": 1, "descargaPETSAlmacenamiento": 1, "descargaPETSManipulacion": 1, "descargaMOF": 1, "descargaPoliticasDescuentosPorDanios": 1, "total_documentos": false }}`

--- ## **Posibles respuestas con error** ### ● Empleado no encontrado ### ● Documentos de ingreso no completados # Lista de marcaciones generada (1) - [listMarkingsApp45] ### 🧾 Descripción *Este servicio obtiene y consolida **todas las marcaciones de asistencia de un empleado en una fecha específica**, combinando información de:* - **Employee Checkin** (Entradas, salidas, refrigerios) - **Attendance** (Estado del día) - **Cortes** (Fechas especiales donde cambia el criterio de consulta) - **Turnos del empleado (Shift Type)** *Entrega una estructura lista para mostrar en una app móvil o web con:* - Entrada - Salida a refrigerio - Retorno de refrigerio - Salida - Estado del día (Presente, Ausente, Teletrabajo, etc.) - Información del día: nombre, mes, fecha formateada. *El servicio también calcula dinámicamente si debe tomar **estado\_reporte** o **status**, según si la fecha consultada pertenece al rango generado desde el último corte del mes.* --- # 🚀 Endpoint **POST** **`/list-markings-app45`** --- # 📥 Parámetros de Entrada (Request Body)

Campo	Tipo	Descripción
usuario	string	Usuario que solicita información (no se usa en lógica interna).
empleado	string	ID del empleado a consultar.
cookie	string	Cookie de sesión para consultas al ERP.
date	string	Fecha de la marcación.

--- # 🔐 Seguridad Requiere cookie de sesión válida para ERPNext, ya que usa servicios internos vía: - `dbErp()` - `ServiceErp()` --- # 🧠 Flujo del Servicio (Resumen Real) ### 1️⃣ Obtiene filtros según fecha - Si la fecha es **>= 2022-11-10**, consulta por **`fecha_consolidado`**. - Si es menor, consulta por *rango horario* (00:00:00 – 23:59:59). ### 2️⃣ Trae las marcaciones del empleado Consulta **`tabEmployee Checkin`** (Entrada, Refrigerio, Salida). ### 3️⃣ Consulta estado de asistencia Desde `tabAttendance`, validando solo documentos aprobados (`docstatus = 1`). ### 4️⃣ Obtiene configuración de cortes del mes Sirve para determinar si el estado válido es: - `estado_reporte` (cuando está dentro del rango posterior al corte), ó - `status` (estado normal de Attendance) ### 5️⃣ Genera un rango de fechas desde el corte hasta fin de mes Se usa para validar cambios de lógica. ### 6️⃣ Procesa marcaciones y las estructura así: ### ### 7️⃣ Traduce estados a texto legible Ejemplo:

ERP	Texto entregado
Present	Presente
Absent	Ausente
Work From Home	Trabajar desde casa
Half Day	Medio día

--- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Error al obtener marcaciones ### 2. Error al consultar Attendance o Cortes ### 3. Error interno del servidor

`{ "valor": false, "msn": "Error en listMarkingsApp45: ", "error": ""}`

--- # 📚 Tablas / Recursos Usados ### 🔹 `tabEmployee Checkin` Campos: - name - employee - employee\_name - log\_type - time - tardanza - salida\_temprana ### 🔹 `tabAttendance` - status - estado\_reporte - attendance\_date - employee ### 🔹 `tabCortes` - dia\_inicio - dia\_final ### 🔹 `tabShift Type` - start\_time - end\_time --- # 🧩 Lógica en Pseudocódigo

`input: usuario, empleado, cookie, datecalcular inicio y fin del díasi date >= 2022-11-10: buscar checkin por fecha_consolidadoelse: buscar checkin por rango de horasconsultar Attendanceconsultar Cortes del messi cortes vacío → errorgenerar fechas posteriores al cortedeterminar estado (status o estado_reporte)crear estructura de salidaiterar marcaciones: si log_type == Entrada → entrada si log_type == Salida Refrigerio → salida_refrigerio etc.retornar JSON con todas las marcaciones y estado`

# Obtener Usuario (3) - [getUser3] ### 🧾 Descripción *Este servicio permite **obtener la información completa de un usuario**, ya sea **Empleado** o **Estudiante**, usando cualquiera de los siguientes identificadores:* - **Correo** (user\_id) - **DNI / Pasaporte** (passport\_number) *La función consulta múltiples tablas del ERP y retorna la información enriquecida del usuario, incluyendo:* - Datos personales - Datos laborales - Contratos - Imagen de usuario - Estado actual - Sucursal, puesto, departamento - Datos adicionales (PETS, tipo de jornada, fondo de pensiones, etc.) *Si el usuario no es empleado, se intenta validar como estudiante.* *El servicio aplica múltiples reglas de negocio internas sobre estado, tipo de usuario y permisos.* --- # 🚀 Endpoint **POST /get-user-3** 📥 *Body esperado* O también: --- # 🔐 Seguridad Este servicio requiere autenticación interna contra el ERP mediante **`dbErp()`** y **`ServiceErp()`** con token válido del sistema. --- # 🧠 Flujo del Servicio (Resumen Real) ### **1. Determinar tipo de búsqueda** Si **`username`** contiene **@**, se asume que es *user\_id*. Si no contiene, se usa como **passport\_number** (DNI). Se arma el filtro dinámicamente:

Caso	Campo filtrado
Correo	emp.user\_id
DNI / Pasaporte	emp.passport\_number

--- ### **2. Buscar al usuario como *Empleado*** Consulta principal: `POST method/send-query-database` Incluye joins a: - tabUser - tabBranch - tabContrato de Trabajo - tabDepartment Si existe un registro válido: - Se valida que NO esté inactivo. - Se formatea fecha de nacimiento. - Se determina si el contrato es renovación o primer contrato. - Se normalizan campos (pets, cuenta haberes, vigencia del contrato, tipo\_usuario = "Empleado"). 📌 **Si todo está correcto, el servicio termina aquí** retornando la data del empleado. --- ### **3. Si NO existe empleado → Buscar como *Estudiante*** Filtros dependen de correo o DNI. Validaciones aplicadas: - Debe estar habilitado (`enabled = 1`). - Si no existe → acceso denegado. - Si está deshabilitado → retorno con error. Datos retornados incluyen: - Nombre completo - Sucursal, departamento - Tipo de puesto (convertido desde convocatoria si aplica) - Imagen de usuario - Tipo\_usuario = “Estudiante” --- ### **4. Retornar la data final** Si es empleado → retorna información laboral con contratos. Si es estudiante → retorna información básica educativa. --- # 📤 Response 200 – Ejemplo (Empleado) --- # ❗ Posibles Errores ### **1. No existe como empleado ni estudiante** ### **2. Empleado Inactivo** ### **3. Usuario deshabilitado (estudiante)** ### ### **4. Error al consultar ERP** --- # 📚 Tablas consultadas ### **Empleado** - `tabEmployee` - `tabUser` - `tabBranch` - `tabContrato de Trabajo` - `tabDepartment` ### **Estudiante** - `tabStudent` - `tabUser` - `tabBranch` - `tabJob Applicant` - `tabRequerimiento de Personal` - `tabDesignation` - `tabDepartment` --- # 🗃 Resultado Final (Estructura General) ### Para empleados: ### Para estudiantes: --- # 🧩 Pseudocódigo del servicio # Lista de Sucursales - [listOfErpBranchs] ## 🧾 Descripción *Obtiene la lista completa de **sucursales registradas en el ERP**, filtrando únicamente aquellas que:* - No sean concesionarios (`concesionario = 0`) - Tengan un identificador válido (`ideentificador != "0"`) *El servicio consulta directamente el ERP a través del método `apiService()` y devuelve las sucursales ordenadas alfabéticamente por su nombre.* *También realiza un post-proceso convirtiendo el campo `ideentificador` en **string**, garantizando consistencia en el frontend (evita problemas cuando el ERP envía valores numéricos).* --- ## 🚀 Endpoint **GET** **`/list-of-erp-branchs`** No recibe parámetros. Toda la data proviene del ERP mediante: --- ## 🔐 Seguridad Requiere autenticación del ERP mediante **`apiService()`**. El token se gestiona internamente (servicio backend–backend). --- ## 🧠 Flujo del Servicio 1. Llama al ERP solicitando todas las sucursales: - Sin límite (`limit=None`) - Ordenadas (`order_by=name asc`) - Filtradas por: - concesionario = 0 - ideentificador ≠ "0" - Campos solicitados: - `name` - `ideentificador` 2. Decodifica la respuesta. 3. Valida que exista el campo `"data"` en la respuesta del ERP. - Si no existe, retorna error. 4. Recorre cada registro y convierte `ideentificador` a string. 5. Retorna la lista final de sucursales. --- ## 📥 Request Body No tiene body. --- ## 📤 Response 200 – Ejemplo --- ## ❗ Posibles Errores ### 1. Error al obtener data del ERP ### 2. Excepción interna del servidor --- ## 📚 Esquema de datos (Branch) ### **Branch (GET)** Campos utilizados: --- ## 🗃 Pseudocódigo del servicio # Intento de Marcación (1) - [intentMarca] ### 🧾 Descripción *Registra y actualiza los intentos de marcación que realiza un empleado en una agencia durante el día.* *Este servicio controla cuántas veces un colaborador intenta marcar asistencia, creando o actualizando un registro diario en el ERP.* Se basa en el Doctype: - **Intento de marcacion** Y utiliza los campos: - empleado - agencia - intento - creacion (fecha del intento) --- # 🚀 Endpoint **POST /intent-marca** El servicio recibe datos desde el body mediante **`Request`**. --- # 📥 Request Body ### Campos requeridos:

Campo	Tipo	Obligatorio	Descripción
empleado	string	✔	Código del empleado
agencia	string	✔	Agencia en la que intenta marcar
intento	int	✔	Intento actual enviado desde la app

--- # 🔐 Seguridad Utiliza autenticación interna del ERP a través de: - **dbErp()** para consultas SQL - **ServiceErp()** para creación y actualización de documentos en el ERP Requiere credenciales internas del sistema. --- # 🧠 Flujo del Servicio (resumen real) 1. **Valida que existan los parámetros obligatorios**: empleado, agencia e intento. Si falta alguno → retorna error. 2. **Determina la fecha actual (`Y-m-d`)**. Este valor se usa para registrar un intento por día. 3. **Consulta si el empleado ya tiene un registro de Intento de marcacion para el día actual**: 4. Si **existe un registro previo**: - Se suma el intento nuevo al intento existente: - Se actualiza el Doctype: 5. Si **NO existe un registro previo**: - Se crea un nuevo documento Intento de marcacion: 6. Devuelve la respuesta directa del ERP. --- # 📤 Response 200 – Ejemplo (actualizado) ### ✔ Caso actualización ### ✔ Caso creación --- # ❗ Posibles Errores ### 1. Falta de parámetros requeridos ### 2. Error en la consulta DB → dbErp ### 3. Error en creación o actualización en ERP --- # 📚 Doctype utilizado ## Intento de marcacion Campos usados: --- # 🗃 Lógica en pseudo-código # Validar Marcación (1) - [validar] ### 🧾 Descripción *Este servicio ejecuta **toda la lógica de validación previa** para permitir que un empleado realice una marcación (asistencia).* *El servicio centraliza más de **10 validaciones críticas**, verificando:* - Campos obligatorios - Licencias activas - Restricciones por puesto - Validación de firma de documentos obligatorios - Descarga de contratos y documentos requeridos - Datos incompletos del empleado - Tipo de marcación permitido - Esquema de fiscalización - Reglas por empresa (Shalom Express vs Shalom Empresarial) *Es un servicio de control que determina si el empleado puede realizar una marcación y qué mensaje debe mostrarse al usuario.* --- # 🚀 Endpoint **POST /validar** --- # 📥 Request Body (resumen) --- # 🔐 Seguridad - Requiere usuario autenticado. - Usa datos precargados del empleado (`$this->employee_detail`). - Internamente utiliza múltiples servicios ERP y validadores internos. --- # 🧠 Flujo del Servicio (Resumen Real) 1️⃣ **Validar campos obligatorios** Llama a `verifyFields()`. Si falta algún parámetro → retorna error inmediato. 2️⃣ **Cargar datos principales** - empleado - tipo de marcación - fecha de asistencia - datos del empleado desde sesión previa 3️⃣ **Validar restricciones por puesto** Si el empleado NO es "PreActivo", llama a: `validateRestrictedDesignation(designation)` 4️⃣ **Validar licencia activa** `verifyLicencia(empleado, fechaIngreso)` 5️⃣ **Validar nuevos ingresos** Solo para empleados activos, ingreso reciente, y NO Express: `verifySignedNewAdmissionRegistrations()` 6️⃣ **Validar descarga de documentos obligatorios** Obtiene documentos descargados: `verifyDownloadedDocumentsBd()` Y valida contrato pendiente: `verifyContractDownload()` 7️⃣ **Validar documentos de cambio de modalidad** `verifyModalityChangeDocument()` 8️⃣ **Validar información del empleado (horarios, jornada, etc.)** `verifyEmployeeData()` 9️⃣ **Obtener últimas marcaciones** `getMarkingsByEmployee()` 🔟 **Validación de “No sujeto a fiscalización”** `verifyEmployeeNotSubjectToInspection()` 1️⃣1️⃣ **Validación de refrigerio** Si type == *llegada\_refrigerio*: `verifyStartOfLunch()` 1️⃣2️⃣ **Validar coherencia del tipo de marcación** Ejemplo: que no marque salida sin marcar ingreso. `verifyTypeOfMarking()` 📌 Si todas las validaciones son correctas → retorna éxito. --- # 📤 Response 200 – Ejemplo (OK) --- # ❗ Posibles Errores devueltos por este servicio ### 1. Campos obligatorios faltantes ### 2. Puesto restringido ### 3. Empleado con licencia activa ### 4. Documentos de ingreso no firmados ### 5. Contrato pendiente por descargar ### 6. Error en la lógica de marcación (orden incorrecta) ### 7. No sujeto a fiscalización --- # 🗃 Funciones internas utilizadas

Nombre	Descripción
verifyFields	Valida campos requeridos del request
validateRestrictedDesignation	Controla puestos con restricciones
verifyLicencia	Evalúa si el empleado tiene licencia activa
verifySignedNewAdmissionRegistrations	Valida firmas de ingreso
verifyDownloadedDocumentsBd	Valida documentos descargados
verifyContractDownload	Revisa si falta descargar contrato
verifyModalityChangeDocument	Valida documentos de cambios de modalidad
verifyEmployeeData	Verifica datos del empleado necesarios para marcar
getMarkingsByEmployee	Obtiene último registro de marcación
verifyEmployeeNotSubjectToInspection	Revisa si está sujeto a fiscalización
verifyStartOfLunch	Valida inicio del refrigerio
verifyTypeOfMarking	Controla coherencia de marcaciones

--- # 🗃 Pseudo-código real del servicio # Crear Marcación (1) - [crear] ## 🧾 Descripción *Registra una **marcación de entrada o salida** para un empleado, validando previamente:* - Datos obligatorios del request. - Duplicidad de marcaciones. - Estado del empleado (Activo / PreActivo). - Horario asignado (tardanza y horas extra). - Reglas especiales según modalidad (offline / online). - Registro simultáneo en: - **ERP (Employee Checkin)** - **Base de datos interna (tabla marcaciones)** *Es uno de los servicios centrales del módulo de asistencia.* --- # 🚀 Endpoint **`POST /marcaciones/store`** Este servicio **sí recibe parámetros en el request**. --- # 📥 Request Body (Campos usados) ### Campos relevantes

Campo	Tipo	Descripción
empleado	string	ID del empleado
image	string	URL base64 o imagen enviada
fecha\_asistencia	date	Fecha de la marcación
type	string	“entrada” o “salida”
passport\_number	string	Documento del empleado
coordinates	string	Lat/Lon opcional
isOfline	int	`1` si se marcó offline

--- # 🔐 Seguridad El servicio requiere: - Token válido via middleware Laravel. - Acceso interno al ERP mediante **`general->insertERPNew()`** y **`general->dbErp()`**. --- # 🧠 Flujo del Servicio (resumen real) ### **1. Validación de campos** Se ejecuta `verifyFields($request)` y si falla, retorna de inmediato. ### **2. Prevención de fechas inválidas** Si la marcación es online y la fecha es mayor al día actual → rechaza. ### **3. Validación de duplicidad** Se construye: Luego: `validateDuplicateDialing()` Si ya existe marcación → error. --- ### **4. Obtención del turno del empleado** Consulta ERP: - Hora de inicio (`start_time`) - Hora de salida (`end_time`) - Datos básicos del empleado Si es “entrada” → valida que pase de PreActivo → Activo. --- ### **5. Cálculo de tardanza u horas extra** - Si el empleado marca **entrada** más de 5 min tarde → genera tardanza `"HH:MM"`. - Si marca **salida** con +60 minutos → horas extra. --- ### **6. Registro en ERP** Crea documento: **Employee Checkin** --- ### **7. Registro en base de datos interna** Inserta en tabla `marcaciones`: --- ### **8. Generación de asistencia** Si la marcación es **salida**, ejecuta: `storeAttendance($request)` y devuelve datos adicionales. --- # 📤 Response 200 – Ejemplo ### ✔ Entrada o salida registrada correctamente ### ✔ Al registrar salida (incluye asistencia generada) --- # ❗ Posibles Errores ### 1. Campos inválidos ### 2. Marcación duplicada ### 3. Fecha mayor al día actual ### 4. Error creando Employee Checkin ### 5. Error servidor --- # 📚 Schemas utilizados ### **Employee** ### **Shift Type** ### **Employee Checkin (ERP)** --- # 🗃 Lógica en Pseudo-código # Modulo de Asistencia y Marcaciones (Asistencia) # Obtiene descarga boleta de pago (2) - [getDownloadBoletaPago] ### 🧾 Descripción *Este servicio valida si un empleado **debe descargar obligatoriamente su boleta de pago del último mes** antes de poder realizar acciones como:* - Registrar marcación - Registrar solicitudes en la app - Acceder a otros módulos operativos *El servicio evalúa:* 1. Si está dentro del rango de validación (solo **del día 1 al 3** de cada mes). 2. La **fecha de ingreso del trabajador**. 3. Si tiene boleta generada el mes anterior. 4. Si el mes correspondiente está **habilitado para descarga**. 5. Si el empleado **ya descargó** la boleta (se revisa historial en MySQL). 6. Si el empleado está **PreActivo**, no se valida la descarga. --- # 🚀 Endpoint ### GET /get-download-boleta-pago/{empleado} 📌 **Parámetro obligatorio:** - **empleado** → ID del Employee (name) --- # 🔐 Seguridad - Requiere autenticación interna por el ERP mediante `dbErp()` y conexión MySQL interna. - El servicio está pensado solo para uso interno de la aplicación móvil corporativa. --- # 🧠 Flujo del Servicio (resumen) ### 1️⃣ Validación de fecha Solo se ejecuta validación si el día actual está entre **1 y 3**. Si el día > 3 → se omite toda validación: --- ### 2️⃣ Obtener información del empleado Consulta ERP: Si el empleado está **PreActivo**, no se valida boleta: --- ### 3️⃣ Comparar fecha de ingreso vs fecha límite Se calcula: - Mes anterior - Último día del mes anterior Solo se valida si el empleado ingresó **antes del cierre del mes previo**. --- ### 4️⃣ Verificar en MySQL si ya descargó la boleta Consulta tabla `historial_procesos_app`: Si no existe registro se sigue validación. --- ### 5️⃣ Validar si EXISTE boleta en ERP Consulta Salary Slip del último mes:

`SELECT posting_dateFROM `tabSalary Slip`WHERE employee = ?AND posting_date between <primer_día_mes_anterior> AND <último_día_mes_anterior>`

Si no tiene boleta: --- ### 6️⃣ Validar si el mes está habilitado para descarga Consulta: Si está habilitado pero **el trabajador NO la descargó**, se bloquea: --- ### 7️⃣ Si pasa todas las validaciones → OK --- # 📥 Request **No usa body**, solo el parámetro de ruta: `empleado: string` --- # 📤 Response – Ejemplos ### ✔ Caso permitido (día fuera de rango) ### ✔ Empleado en PreActivo ### ✔ No tiene boleta generada ### ❌ No ha descargado la boleta y es obligatoria ### ✔ Todo correcto --- # ❗ Posibles errores

Error	Descripción
Empleado no existe	No se encuentra en ERP
No tiene boleta generada	Salary Slip del mes anterior vacío
Boleta habilitada pero no descargada	Bloquea marcación y solicitudes
Error en ERP o MySQL	Respuesta capturada por el catch

--- # 🧩 Tablas consultadas ### ERP (Frappe/ERPNext) - `tabEmployee` - `tabSalary Slip` - `tabEstado Boleta Mensual` ### MySQL externo - `historial_procesos_app` --- # 🗃 Pseudocódigo del servicio # Obtiene descarga Renovación de contrato (2) - [getRenovacionContrato] ## 🧾 Descripción *Valida si un empleado **debe descargar su renovación de contrato**, según reglas internas de fecha y estado en el ERP.* Este servicio determina: - Si hoy es la fecha válida para revisar renovaciones (solo a partir del día 26 de cada mes). - Si el empleado ingresó antes del cierre del mes anterior (lo que lo vuelve candidato a renovación). - Si el empleado tiene una solicitud de renovación aprobada y marcada como “Validado”. - Si el empleado **ya descargó** su documento de renovación. - Caso contrario, se bloquean ciertas funcionalidades hasta que la descargue. *Se combina información del **ERP** y del registro histórico en **MySQL2**.* --- # 🚀 Endpoint GET /get-renovacion-contrato/{empleado} 📌 *El parámetro **`empleado`** es obligatorio (ID del Employee en ERP).* --- # 🔐 Seguridad ✔ Requiere autenticación interna vía **`dbErp()`** y tokens del ERP. ✔ Acceso restringido a servicios del backend. --- # 🧠 Flujo del Servicio (Resumen) 1. **Verifica la fecha actual.** - Si el día del mes es menor a 26 → No corresponde validar renovaciones. 2. **Obtiene datos del empleado.** 3. **Determina si el empleado aplica para renovación:** - Debe haber ingresado **antes del último día del mes anterior**. 4. **Busca renovaciones validadas del empleado:** 5. **Si existe una renovación validada:** - Consulta MySQL2 → tabla `historial_procesos_app` - Revisa si el usuario **ya descargó su renovación**: 6. **Si no la descargó → bloquea ciertas funciones.** 7. **Si todo está conforme → indica que la renovación fue descargada.** --- # 📥 Request ### Parámetro de ruta

Campo	Tipo	Obligatorio	Descripción
empleado	string	✔	ID del Employee dentro del ERP

No tiene body. --- # 📤 Response 200 – Ejemplos ### ✔ Caso 1 — No es día de validación ### ✔ Caso 2 — Debe descargar renovación (bloqueo) ### ✔ Caso 3 — Renovación descargada correctamente ### ✔ Caso 4 — Error controlado --- # ❗ Posibles errores

Código	Significado
status:false	El empleado tiene renovación pendiente y no la descargó
status:true	No aplica validación o ya cumplió con la descarga
Excepción	Se devuelve un mensaje genérico indicando que el contrato fue descargado

--- # 📚 Tablas / Datos utilizados ### ERP - `tabEmployee` Campos usados: - `fecha_de_ingreso_real` ### ERP - `tabSolicitud de Renovaciones` Campos usados: - `data_12` - `año` - `estado_de_documento` ### ERP - `tabTrabajadores pendiete de renovar` Campos usados: - `codigo` - `renueva` ### MySQL2 - tabla `historial_procesos_app` Procesos revisados: - `descargaContratoRenovacion` --- # 🗃 Lógica en Pseudo-Código

`if day(today) < 26: return OK("No es el día correcto")empleado = queryERP(Employee where name=empleado)if empleado.ingreso < ultimo_dia_mes_anterior: renov = queryERP(Solicitud de Renovaciones where codigo=empleado AND renueva="Si" AND estado="Validado" ) if renov exists: registro = queryMySQL(historial_procesos where proceso="descargaContratoRenovacion") if registro vacío: return ERROR("Debe descargar la renovación")return OK("Se ha descargado el contrato de trabajo")`

# Lista de Asistencias (1) - [getMarkingsApp] ## 🧾 Descripción *Este servicio obtiene y consolida **todas las asistencias** de un empleado en un mes específico, calculando:* - Porcentaje de asistencia del mes. - Total de días asistidos. - Permisos. - Faltas. - Feriados. - Días de descanso. - Marcaciones incompletas. - Fechas únicas de asistencia. Además, toma en cuenta: - Fecha de ingreso del trabajador (para no contar días previos como faltas). - Domingos y feriados declarados en *holidays.json*. - Validación de límites según el mes actual. *Es un endpoint fundamental para el módulo de **Control de Asistencias** dentro del aplicativo.* --- # 🚀 Endpoint ### **POST /get-markings-app** 📥 Requiere parámetros obligatorios en el body: --- # 🔐 Seguridad Requiere autenticación interna del sistema ERP mediante: - `dbErp()` para consultas SQL internas. - Acceso a archivo local `/public/recursos_humanos/holidays.json`. --- # 🧠 Flujo del Servicio (resumen real) 1. **Recibe parámetros del empleado y mes a consultar.** employee, month, anio, fechaIngreso 2. **Calcula rango real del mes a evaluar**, tomando en cuenta: - Si es el mes actual. - Si el empleado ingresó después del día 1. - Días previos al ingreso del trabajador. 3. **Carga feriados y domingos del archivo JSON:** `/public/recursos_humanos/holidays.json` 4. **Determina cuántos días del mes son feriados o domingos dentro del rango permitido.** 5. **Valida campos obligatorios.** 6. **Consulta en el ERP todas las asistencias del empleado en el mes:** 7. **Recorre todas las asistencias y clasifica:** - Present → Suma asistencia - On Leave → Permisos - Absent → Faltas - Feriado → Feriados - Día de Descanso → Descansos - Marcacion Incompleta → Marcaciones incompletas 8. **Calcula porcentaje de asistencia**, considerando: - Días previos al ingreso. - Si el mes es el actual → hasta el día de hoy. - Casos especiales de permisos dominicales. 9. **Construye respuesta final con totales y fechas.** --- # 📥 Request Body 📌 **Todos son obligatorios.** --- # 📤 Response 200 – Ejemplo

`{ "valor": true, "msn": "LISTA DE ASISTENCIAS", "data": { "porcentage": "92.55", "dias_aistidos": "25", "dias_totales": "27", "permisos": "1", "faltas": "0", "marcacion_incompleta": "1", "fechas_asistidas": [ "2025-03-01", "2025-03-02", "2025-03-03" ], "feriados": "1", "descansos": "4", "dias_permisos": [ "2025-03-08" ], "dias_tardanzas": [ "2025-03-15" ], "dias_faltas": [], "dias_feriados": [ "2025-03-29" ], "dias_descansos": [ "2025-03-02", "2025-03-09" ] }}`

--- # ❗ Posibles Errores ### 1. Faltan parámetros obligatorios ### 2. No existe asistencia registrada ### 3. Error interno inesperado --- # 📚 Estructuras usadas ### **Attendance (tabAttendance)** Campos consultados: - `attendance_date` - `status` - `horas_trabajadas` - `horas_extras` - `name` ### **Archivo holidays.json** Estructura: --- # 🧩 Lógica en pseudo-código

`input: employee, month, anio, fechaIngresovalidar campos requeridoscalcular fecha_inicio y fecha_fin según: - mes actual - fecha de ingreso del empleadocargar feriados y domingos (holidays.json)contar días dentro del rangoconsultar asistencias en ERP: SELECT attendance_date, status FROM tabAttendance WHERE employee = employee AND status IN (...)inicializar contadoresforeach asistencia in resultado: clasificar según status acumular días, permisos, faltas, descansos, feriadoscalcular porcentaje de asistenciareturn { valor: true, data: {...}}`

# Modulo de Asistencia y Marcaciones (Horas Extras) # Obtiene descarga boleta de pago (3) - [getDownloadBoletaPago] 🧾 **Descripción** *Valida si un empleado **debe descargar su boleta de pago del mes anterior** antes de poder registrar marcaciones o realizar solicitudes en el sistema.* *La validación se aplica únicamente dentro de un periodo permitido (del día 1 al 3 del mes).* Este servicio combina datos entre: - `Employee` (ERP) - `Salary Slip` (Boleta de pago, ERP) - `Estado Boleta Mensual` (ERP) - `historial_procesos_app` (Base MySQL interna) Permite determinar si el usuario: - No debe validar nada. - No tiene boleta para ese mes. - Tiene boleta habilitada y aún **no la descargó** → Debe descargarla. - Ya descargó → Se libera el acceso. --- # 🚀 Endpoint **POST /get-download-boleta-pago** ### 📥 Parámetros

Campo	Tipo	Requerido	Descripción
empleado	string	Sí	ID del empleado (Employee.name)

--- # 🔐 Seguridad **El servicio requiere:** - Acceso API válido al ERP (vía `dbErp()`). - Acceso a la base interna MySQL (`mysql2`). --- # 🧠 Flujo del Servicio (resumen real) ### 1️⃣ Verifica si está dentro del rango permitido - Solo valida del **día 1 al 3**. - Si el día es mayor a 3 → no valida nada. ### 2️⃣ Obtiene datos del empleado Consulta:

`GET tabEmployeefields = ["fecha_de_ingreso_real", "status"]`

Si el empleado está **PreActivo**, no se valida boleta. ### 3️⃣ Determina el mes anterior **Se calcula:** - Primer día del mes anterior - Último día del mes anterior Se verifica que el empleado haya ingresado antes del fin del mes anterior. ### 4️⃣ Verifica si existe boleta del mes anterior Consulta a ERP:

`tabSalary SlipWHERE employee = empleadoAND posting_date BETWEEN primer_día_mes_pasado AND último_día_mes_pasado`

Si **no tiene boleta**, no se valida nada. ### 5️⃣ Valida si el mes está habilitado para descarga Consulta:

`tabEstado Boleta MensualWHERE mes = AND año = AND habilitado = 1`

### 6️⃣ Consulta si el usuario ya descargó la boleta Busca en MySQL:

`historial_procesos_appWHERE empleado = empleadoAND proceso = 'NOMINA'AND month = mesAND year = año`

Si **no existe descarga previa** y el mes está habilitado → debe descargar. --- # 📤 Respuestas Posibles ### ✔️ 1. No está en rango de validación ### ✔️ 2. Empleado PreActivo ### ✔️ 3. No tiene boleta del mes ### ❌ 4. Debe descargar la boleta (regla principal) ### ✔️ 5. Ya descargó la boleta ### ✔️ 6. Error controlado --- # 📚 Tablas y esquemas usados ### 🔹 Employee (ERP) Campos utilizados: ### 🔹 Salary Slip (ERP) Campo utilizado: `posting_date` ### 🔹 Estado Boleta Mensual (ERP) Campos utilizados: ### 🔹 historial\_procesos\_app (MySQL) Campos usados: --- # 🗃 Lógica en pseudocódigo # Obtiene descarga Renovación de contrato (3) - [getRenovacionContrato] 🧾 **Descripción** *Valida si un empleado debe **descargar la renovación de contrato** antes de poder registrar marcaciones o realizar solicitudes dentro del aplicativo.* El servicio evalúa: - La fecha actual (solo aplica desde el día **26 de cada mes**). - La fecha de ingreso del empleado. - Si el empleado tiene un proceso de renovación registrado y validado en ERP. - Si ya existe un registro de descarga previo en `historial_procesos_app`. *Este servicio actúa como una **regla de negocio obligatoria** para habilitar o bloquear el uso del aplicativo.* --- # 🚀 Endpoint **POST /get-renovacion-contrato** 📌 Recibe un único parámetro: --- # 🔐 Seguridad - Requiere credenciales autorizadas para consumir la API del ERP. - Utiliza internamente `dbErp()` para ejecutar consultas SQL seguras contra ERPNext. - Accede a `mysql2` para verificar registros de descargas. --- # 🧠 Flujo del Servicio (Resumen Real) ### 1️⃣ Validación inicial por fecha - Solo permite validar renovación desde el **día 26** del mes. Si es antes: --- ### 2️⃣ Obtener fecha real de ingreso del empleado Consulta al ERP: Si no existe → el servicio simplemente finaliza sin error. --- ### 3️⃣ Determinar si el empleado ya debería tener renovación - Calcula el último día del **mes anterior**. - Si el ingreso es anterior a ese período, el empleado califica para renovación. --- ### 4️⃣ Consultar renovación en ERP (contratos validados) Busca registros de: - Mes actual (en texto: Enero, Febrero…) - Año del mes previo - Código del empleado - `renueva = Si` - `estado_de_documento = Validado` Consulta ejecutada: --- ### 5️⃣ Validar si el empleado YA descargó la renovación Consulta en base de datos interna: - Si **NO la descargó** → Bloquea acciones del app: --- ### 6️⃣ Si todo está correcto Retorna éxito: --- # 📥 Request Body --- # 📤 Response 200 – Ejemplos ### ✔ Caso correcto (ya descargó renovación) ### ❌ Debe descargar renovación antes de usar el app ### ✔ Aún no es día válido --- # ❗ Posibles Errores

Error	Respuesta
Día inválido para la operación	`"No es el día correcto para la renovación de contrato"`
Empleado sin renovación validada	`"Para poder registrar su marcación..."`
Error inesperado en ejecución	Se devuelve mensaje genérico, pero siempre con status: true
No existe el empleado	El flujo simplemente finaliza sin error explícito

--- # 📚 Consultas y estructuras usadas ### ✔ ERP — Employee Campos consultados: ### ✔ ERP — Solicitud de Renovaciones Consulta combinada mediante JOIN: - `data_12` (mes) - `año` - `codigo` - `renueva` - `estado_de_documento` ### ✔ Base interna MySQL (mysql2) Tabla: `historial_procesos_app` Campo crítico: `proceso = 'descargaContratoRenovacion'` --- # 🗃 Lógica en Pseudo-código # Horas Extras del Mes (1) - [getMarkingsForEmployeePerMonth2] 🧾 **Descripción** Obtiene y calcula todas las **horas extras registradas** para un empleado en un mes específico, detallando: - Horas al **25%** - Horas al **35%** - Horas al **100%** (domingos y feriados) - Listado detallado por día - Total acumulado del periodo de corte mensual El servicio consulta información desde varios recursos del ERP: - **Cortes (tabCortes)** → para determinar el rango mensual válido - **Horas Extras (tabHoras Extras)** → totales por mes - **Marcaciones (tabMarcaciones)** → registros por día - Archivo local de feriados: `holidays.json` --- # 🚀 Endpoint **POST** **`/get-markings-employee-month`** 📥 **Parámetros en el body** --- # 🔐 Seguridad - Requiere token interno del ERP (autenticación manejada por **`ServiceErp()`**). - Validación del request vía Laravel. --- # 🧠 Flujo del Servicio (resumen real) ### 1️⃣ Obtiene el corte mensual Consulta el recurso: Si no existe corte → retorna error `"No hay corte mensual para este mes"`. --- ### 2️⃣ Obtiene las horas extras acumuladas del mes --- ### 3️⃣ Obtiene las marcaciones dentro del periodo del corte Si no hay marcaciones → retorna mensaje informativo. --- ### 4️⃣ Carga feriados desde archivo local `public/recursos_humanos/holidays.json` Feriados + domingos se consideran jornada **al 100%**. --- ### 5️⃣ Procesa cada marcación Por cada registro: - Si es feriado/domingo → 100% - Si horas ≤ 2 → 25% - Si horas > 2 - primeras 2h → 25% - resto → 35% Cada día se estructura como: --- ### 6️⃣ Arma la respuesta final: Incluye: - `marcaciones`: detalle por día - `horas25`, `horas35`, `horas100`: de la tabla Horas Extras - `horas_acumuladas`: sumatoria real de horas del mes --- # 📤 **Response 200 – Ejemplo** --- # ❗ Posibles Errores ### 1. Corte mensual no configurado ### 2. Error al traer horas extras ### 3. Marcaciones vacías ### 4. Error en servicio del ERP --- # 📚 **Schemas utilizados** ### **Cortes** ### **Horas Extras** ### **Marcaciones** --- # 🗃 Lógica en pseudo-código # Modulo Otros Descuentos # Otros descuentos de Nomina (1, 2) - [listar] 🧾 **Descripción** *Obtiene y lista los otros descuentos de nómina registrados para un empleado en un año y mes específicos.* *El servicio consulta la información en el ERP (Doctype: **Otros Descuentos Nomina**) y devuelve únicamente los registros que coinciden con el mes y año enviados.* *Permite también filtrar por **todos los meses del año** enviando `"TODOS"` en el parámetro `month`.* --- # 🚀 Endpoint **POST** **`/listar-descuentos`** --- # 📥 Parámetros (Request Body) ### Campos requeridos:

Campo	Tipo	Obligatorio	Descripción
employee	string	✔️ Sí	Código del empleado
year	string	✔️ Sí	Año a filtrar
month	string	✔️ Sí	Mes a filtrar. Si se envía `"TODOS"` devuelve todos los meses del año.

--- # 🔐 Seguridad Requiere token válido del ERP. La comunicación se realiza mediante **ServiceErp()**, usando cabeceras internas de autenticación. --- # 🧠 Flujo del Servicio (Resumen real) 1. **Valida que el parámetro employee exista.** 2. **Valida que el parámetro year exista.** 3. Consulta al ERP: 4. Verifica que exista información. 5. Recorre la tabla interna `table_22` (donde vienen los descuentos mensuales): - Compara: - `item.mes` == mes enviado - `item.ano` == año enviado - Si `month == "TODOS"`, ignora el filtro del mes. 6. Para cada coincidencia arma un objeto con: - motivo - monto - año - mes - creation (en formato `"d de Mes"`) 7. Si no hay coincidencias, retorna "Sin Descuentos". 8. Si hay registros, los devuelve ordenados por creación. --- # 📤 Response 200 – Ejemplo exitoso --- # ⚠️ Respuestas de Error ### 1. Falta employee ### 2. Falta año ### 3. El ERP no devuelve información ### 4. No existen descuentos para el filtro solicitado --- # 🗃 Estructuras usadas (Schemas) ### **Otros Descuentos Nomina** Campos usados: --- # 🧩 Pseudocódigo # Módulo Capacitación(Cursos) # Matricula Estudiante (1) - [enrollStudent] ## 🧾 Descripción *Este servicio **matricula automáticamente a un estudiante** en todos los programas de capacitación correspondientes a su **puesto actual (designation)**.* El flujo toma como origen: - **Student** (por DNI) - **Program** - **Course** - **Program Enrollment** *El servicio determina **qué cursos pertenecen al puesto del estudiante**, identifica **qué programas contienen esos cursos** y finalmente crea **matrículas individuales** para cada programa en el ERP.* --- # 🚀 Endpoint **POST** **`/enroll-student`** --- # 📥 Parámetros (Request Body)

Campo	Tipo	Obligatorio	Descripción
dni	string	Sí	DNI del estudiante para buscarlo en el ERP

--- # 🔐 Seguridad Requiere autenticación interna mediante: - `dbErp()` para consultas SQL - `ServiceErp()` para consumo REST de recursos del ERP --- # 🧠 Flujo del Servicio (resumen) ### 1. Validar parámetro `dni` Si no se envía DNI: → retorna error inmediato. --- ### 2. Buscar al estudiante en `tabStudent` Si no existe: → retorna *"no se encontró al estudiante"*. --- ### 3. Obtener todos los Programas del ERP GET `/resource/Program?fields=["name"]&limit=None` Por cada programa: - Se consulta `/resource/Program/` - Se leen los cursos incluidos en ese programa - Se construye el mapa: --- ### 4. Obtener todos los Cursos del ERP GET `/resource/Course?fields=["name"]` Por cada curso: - Se consulta `/resource/Course/` - Se revisan los `designation` asociados al curso - Se construye el mapa: --- ### 5. Validar si el puesto del estudiante tiene cursos asignados Si no tiene cursos asociados: → retorna *"No se encontró programas para este puesto"*. --- ### 6. Determinar los programas finales Para cada curso del puesto, buscar en qué programas aparece y construir la lista final: Si la lista queda vacía: → no existen programas asignados a este puesto. --- ### 7. Registrar las matrículas (Program Enrollment) Para cada programa identificado: 1. Validar si ya existe matrícula: 2. Si **existe**, se almacena como encontrado. 3. Si **no existe**, se crea:

`POST Program Enrollment{ "student": "", "program": "", "enrollment_date": "", "academic_year": "", "docstatus": 1}`

El servicio separa: - Matrículas creadas - Matrículas ya existentes - Errores durante el registro --- # 📤 Respuesta 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Falta DNI ### 2. Estudiante no encontrado ### 3. Puesto sin cursos asociados ### 4. Error al registrar un enrollment Se devuelve en `errors`: --- # 🗃 Esquemas usados en el ERP ### **Student** ### **Program** ### **Course** ### **Program Enrollment** --- # 🧩 Lógica en Pseudocódigo

`dni = request.dniif empty(dni): return errorstudent = query Student where dni=dni order by joining_date desc limit 1if not found: return errordesignation = student.puestoprogramas = GET all programsmapProgramas = generar mapa curso → programascursos = GET all coursesmapCursos = generar mapa puesto → cursosif designation not in mapCursos: return errorprogramas_final = programas donde cursos del puesto están incluidosforeach programa in programas_final: if enrollment existe: agregar a enrollments encontrados else: crear enrollment agregar respuesta a enrollments`

# Listar Cursos (1) - [listar] ### 🧾 Descripción *Este servicio obtiene **todos los cursos asignados** a un empleado o estudiante, basándose en su **puesto** (designation / puesto académico).* *El flujo evalúa primero si el DNI pertenece a un **Empleado**, y si no, valida si pertenece a un **Estudiante**.* *Con el puesto encontrado, se consultan los cursos vinculados y finalmente se retornan los detalles del curso desde `tabCourse`.* El servicio interactúa con: - `tabEmployee` - `tabStudent` - `tabPuesto Curso` - `tabCourse` --- # 🚀 Endpoint **POST** `/listar` --- # 📥 Request Body

Campo	Tipo	Obligatorio	Descripción
dni	string	✔	DNI del empleado o estudiante para identificar su puesto.

--- # 🔐 Seguridad - Requiere autenticación interna del ERP vía `dbErp()`. - No requiere token externo del cliente. --- # 🧠 Flujo del Servicio (Resumen real) ### 1. Buscar si el DNI pertenece a un **Empleado** activo Consulta a: `tabEmployee` con filtros: - passport\_number = DNI - status = Active - designation IS NOT NULL Si se encuentra → extrae el `designation`. --- ### 2. Si no es empleado, verificar si es **Estudiante activo** Consulta a: `tabStudent` con filtros: - dni = DNI - enabled = 1 Si se encuentra → extrae el campo `puesto`. --- ### 3. Si no existe puesto asignado Retorna mensaje: --- ### 4. Buscar cursos asignados al puesto Consulta a: `tabPuesto Curso` filtrando por: - designation = puestoEmpleado Obtiene los `parent` → IDs de los cursos asignados. --- ### 5. Obtener información de los cursos Consulta a: `tabCourse` Retorna campos: - name - hero\_image --- ### 6. Respuesta final Se devuelve el listado de cursos con sus imágenes. --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. No existe empleado NI estudiante con ese DNI --- ### 2. Puesto sin cursos configurados --- ### 3. Error al obtener datos del ERP --- # 📚 Tablas y Campos utilizados ### 🔸 **tabEmployee** Campos: - passport\_number - designation - status ### 🔸 **tabStudent** Campos: - dni - enabled - puesto ### 🔸 **tabPuesto Curso** Campos: - designation - parent (ID del curso) ### 🔸 **tabCourse** Campos: - name - hero\_image --- # 🗃 Lógica en pseudo-código

`dni = request.dniemployee = GET tabEmployee WHERE passport_number = dni AND status = 'Active'if employee exists: puesto = employee.designationelse: student = GET tabStudent WHERE dni = dni AND enabled = 1 if student exists: puesto = student.puesto else: return error("No se encontro el puesto de empleado")cursosAsignados = GET tabPuesto Curso WHERE designation = puestoif cursosAsignados empty: return error("Su usuario no tiene cursos asignados")idsCursos = cursosAsignados.parentsinfoCursos = GET tabCourse WHERE name IN idsCursosreturn infoCursos`

# Cursos Temas (1, 2, 3, 4, 5, 6, 7) - CAPACITACIÓN ATC (II FASE) - [temas] ## 🧾 Descripción *Obtiene los **temas (topics)** de un curso específico y calcula cuántos **videos** y **artículos** contiene cada tema.* *Este servicio consulta:* - La información completa del **Course** - El detalle de cada **Topic** - Cuenta los contenidos según su tipo: *Video* o *Article* *Está diseñado para mostrar al usuario un resumen claro del material disponible por tema.* --- ## 🚀 Endpoint **GET /temas** ### 📥 Parámetros (Request) Se recibe un único valor desde el request: --- ## 🔐 Seguridad Este servicio requiere autenticación válida hacia el ERP mediante: El token o cookies activos son manejados internamente por la clase `general`. --- # 🧠 Flujo del Servicio (resumen real) 1. **Recibe el curso** por parámetro. 2. Consulta al ERP el recurso: 3. Verifica que el curso exista; si no, devuelve error: 4. Extrae la lista de **topics** del curso. 5. Para cada topic: - Inicializa sus contadores: - Consulta el contenido del tópico: - Recorre el contenido (`topic_content`): - Si `content_type == Video` → incrementa contador de videos - Si `content_type == Article` → incrementa contador de artículos 6. Retorna la lista de temas con sus conteos. --- ## 📤 Response 200 – Ejemplo --- ## ❗ Posibles Errores ### 1. Curso no existe o no tiene permisos ### 2. El tópico no contiene información (se ignora sin romper el flujo) No retorna error, simplemente no se contabiliza. ### 3. Fallo de conexión con ERP --- ## 📚 Schemas Consultados ### **Course** Campos usados: ### **Topic** Campos usados:

`{ "topic_content": [ { "content_type": "Video | Article", "content": "string" } ]}`

--- ## 🗃 Lógica en pseudo-código # Cursos Temas Contenido (1, 2, 3, 4, 5, 6, 7) - [temas_contenido] ## 🧾 Descripción *Obtiene **todo el contenido asociado a un Tema de Capacitación**, enriqueciendo la información con:* - URL del **video** (si el contenido es Video) - Texto o enlace procesado del **artículo** (si el contenido es Article) - Cantidad de intentos realizados en un **quiz** por un estudiante (si corresponde) *El servicio puede opcionalmente recibir el **DNI del estudiante**, para verificar su progreso (intentos de quiz).* *Este servicio integra información desde varios recursos del ERP:* - **Topic** - **Video** - **Article** - **Student** - **Quiz Activity** --- # 🚀 Endpoint ### **GET /temas-contenido** 📌 **Parámetros vía request:**

Parámetro	Tipo	Obligatorio	Descripción
tema	string	✔️	Nombre del Topic a consultar
dni	string	❌	DNI del estudiante para obtener intentos de quiz

--- # 🔐 Seguridad Requiere autenticación interna vía: No necesita token del cliente, se usa credencial del backend. --- # 🧠 Flujo del Servicio (Resumen real) ### 1️⃣ Si viene DNI → Obtener datos del estudiante Consulta: Guarda `name` del estudiante si existe. --- ### 2️⃣ Obtener el tema solicitado Debe existir; si no, devuelve: `{ "valor": false, "msn": "No se encontró el tema del curso" }` --- ### 3️⃣ Recorrer cada elemento de “topic\_content” Para cada ítem: #### **📽 Si es Video:**

`GET Video/{content_id}`

Agrega: `"url": ""` --- #### **📄 Si es Article:**

`GET Article/{content_id}`

- Se extrae contenido sin HTML (`strip_tags`) - Si dentro del texto hay un link, se devuelve solo ese link - Se agrega:

`"url": ""`

--- #### **❓ Si es Quiz y hay estudiante:** Agrega: `"quiz_attempts": ` Si no hay estudiante o no es quiz: `"quiz_attempts": 0` --- ### 4️⃣ Retornar todos los contenidos enriquecidos --- # 📥 Request Body (ejemplo) --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Tema no encontrado ### 2. Estudiante no existe (cuando se envía DNI) No genera error, simplemente no agrega intentos de quiz. ### 3. Contenido sin URL o datos incompletos El servicio ignora valores faltantes y continúa procesando. ### 4. Error del servidor --- # 📚 Recursos / Esquemas usados ### **Topic**

`{ "topic_content": [ { "content_type": "Video | Article | Quiz", "content": "string" } ]}`

### **Video** ### **Article**

`{ "content": "html|string" }`

### **Student** ### **Quiz Activity** --- # 🗃 Pseudocódigo del servicio # Examen del Curso (1, 2, 3) - EXAMEN ATC - Agregar contacto - [preguntas] ### 🧾 Descripción *Obtiene todas las preguntas de un examen (Quiz) registrado en el ERP, junto con sus opciones, respuestas correctas y metadatos.* El servicio se encarga de: - Consultar el examen (*Quiz*) en la base ERP. - Traer todas las preguntas asociadas. - Traer todas las opciones de cada pregunta. - Reorganizar los resultados del SQL (que vienen aplanados) en una estructura jerárquica: - **Pregunta** - **Opciones** - Convertir el contenido HTML de la pregunta a texto plano. - Detectar si la pregunta incluye una **imagen** embebida. - Preparar la respuesta final en un formato limpio y listo para usar en la app. --- # 🚀 Endpoint **POST** `/preguntas` --- # 📥 Request Body **Parámetros**

Campo	Tipo	Obligatorio	Descripción
examen	string	✔️	ID del cuestionario (Quiz.name)

--- # 🔐 Seguridad Este servicio requiere acceso a la API interna del ERP a través de: - `dbErp()` → Consulta SQL interna No usa token del usuario final. La autenticación es interna del servidor. --- # 🧠 Flujo del Servicio (Explicación Real) ### 1. Construye consulta SQL El servicio arma un query que une: - `tabQuiz` - `tabQuiz Question` - `tabQuestion` - `tabOptions` De esta manera obtiene: - Datos de la **pregunta** - Datos de **cada opción** - Datos del examen ### 2. Envía la consulta Se ejecuta: `POST method/send-query-database` ### 3. Reorganiza la data El ERP devuelve una fila por cada opción. El servicio agrupa todo por: `question.name` Generando esta estructura:

`[ { question: "...", question_link: "...", options: [ { option: "...", is_correct: 0/1 } ] }]`

### 4. Convierte HTML → texto Las preguntas vienen como HTML. El servicio: - Analiza el HTML con `html_to_obj()` - Extrae texto plano (`strip_tags`) - Busca imágenes incrustadas y genera la URL completa. ### 5. Construye la respuesta final Para cada pregunta: - `name` - `question` (texto plano) - `imagen` (si existe) - `options` (lista de alternativas) --- # 📤 Response 200 – Ejemplo

`{ "valor": true, "data": [ { "name": "PREG-001", "owner": "admin@example", "creation": "2025-01-01", "modified": "2025-01-01", "modified_by": "admin@example", "idx": 1, "docstatus": 0, "question": "¿Cuál es la capital de Francia?", "question_type": "Opciones", "question_link": "PREG-001", "options": [ { "name": "OPT-001", "option": "Madrid", "is_correct": 0, "doctype": "Options" }, { "name": "OPT-002", "option": "París", "is_correct": 1, "doctype": "Options" } ], "imagen": "" } ]}`

--- # ❗ Posibles Errores ### 1. Examen no encontrado ### 2. Error en consulta SQL ### 3. Examen sin preguntas --- # 📚 Schemas Usados ### 🔸 Quiz

Campo	Tipo
name	string

--- ### 🔸 Question

Campo	Tipo
name	string
question	HTML
question\_type	string

--- ### 🔸 Options

Campo	Tipo
name	string
option	string
is\_correct	int (0 o 1)
parent	question.name

--- # 🗃 Lógica en pseudo-código # Evaluar Examen del Curso (1, 2, 3) - EXAMEN ATC - Agregar contacto - [guardar_examen_old] ## 🧾 Descripción *Este servicio registra las respuestas de un examen enviado por un estudiante.* La función: 1. **Recibe** el DNI del estudiante, el identificador del examen y las respuestas. 2. **Valida** que el estudiante exista en el ERP. 3. **Obtiene** la definición completa del examen (Quiz) desde el ERP. 4. **Obtiene** la información detallada de cada pregunta usando los `question_link`. 5. **Devuelve** el listado de preguntas del examen, incluyendo su estructura completa. ⚠ **Importante:** Este servicio *no guarda las respuestas* del examen. Solo valida al estudiante y retorna las preguntas del examen consultado. --- # 🚀 Endpoint **POST /guardar-examen-old** --- # 📥 Request Body (JSON) Ejemplo:

`{ "dni": "12345678", "examen": "QUIZ-0001", "respuestas": "{\"P1\":\"A\",\"P2\":\"C\"}"}`

--- # 🔐 Seguridad - Requiere autenticación ERP (a través de `ServiceErp()` ). - No utiliza tokens externos. --- # 🧠 Flujo del Servicio (Explicación detallada) 1. **Recibe datos del request:** - `$dni` - `$examen` - `$respuestas` (JSON string → array) 2. **Decodifica las respuestas del examen:** 3. **Busca al estudiante por DNI (solo estudiantes habilitados):** GET Student `filters=[["Student","enabled","=",1],["Student","dni","like","%%"]]` - Si no encuentra coincidencias → ❌ devuelve error: 4. **Obtiene la definición del examen (Quiz) desde el ERP:** GET Quiz/<examen> - Trae todas las preguntas vinculadas. 5. **Por cada pregunta del examen:** - Consulta la API: GET Question/{question\_link} - Agrega la información completa al arreglo final. 6. **Devuelve todas las preguntas consultadas.** --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Estudiante no existe o no está habilitado ### 2. Error consultando Quiz o Preguntas (NOT IMPLEMENTED, pero puede ocurrir internamente) ### 3. Respuestas mal formateadas Si el JSON no es válido: (Nota: El código actual **no valida** esto, pero debería.) --- # 📚 Schemas usados ### Student (GET) ### Quiz (GET) ### Question (GET) --- # 🗃 Lógica en pseudocódigo # Módulo Capacitación (Evaluaciones) # Evaluaciones (1) - [serviceForNotesPerEmployee_old] ### 🧾 Descripción *Servicio que consulta y consolida los **resultados de evaluaciones (exámenes)** rendidos por un empleado durante un mes específico.* El servicio obtiene: - Datos del empleado por su **email corporativo**. - Los **exámenes asignados** según su puesto (`Designation`). - Los **resultados obtenidos** en el mes solicitado (`Quiz Activity`). - Devuelve un resumen con: - Lista de todos los exámenes esperados - Puntajes obtenidos - Estado (Pass / No Pass / No rindió) > Esta es una versión antigua del servicio, mantenida por compatibilidad. --- # 🚀 Endpoint **POST** **`/service-for-notes-employee-old`** --- # 📥 Request Body ### Parámetros

Campo	Tipo	Obligatorio	Descripción
email	string	✔️	Email corporativo del empleado (user\_id).
date	string (YYYY-MM-DD)	✔️	Fecha usada para identificar el mes a consultar.

--- # 🔐 Seguridad Utiliza autenticación interna mediante **apiService()** (token ERP interno). No requiere autenticación del cliente (uso interno backend → ERP). --- # 🧠 Flujo del Servicio (Explicación Real) ### **1) Validación inicial** - El email es obligatorio. Si falta, responde: --- ### **2) Obtener empleado por email** Consulta al ERP: Validaciones: - Si no devuelve datos → error. - Si el empleado no tiene **designation** → error. --- ### **3) Obtener información del puesto (Designation)** - Trae la lista de exámenes asignados al puesto. - Transformación especial si el puesto contiene espacios (caso HR). --- ### **4) Rango de fechas del mes** A partir del parámetro `date`: - Primer día del mes - Último día del mes Ejemplo: `2024-05-01 to 2024-05-31` --- ### **5) Obtener evaluaciones del mes** Consulta al ERP: --- ### **6) Construcción del resultado** - Se genera una lista con **todos los exámenes del puesto**, con estado inicial: - Se recorren las evaluaciones rendidas: - Se conserva la **mejor nota** por examen. - Se asigna estado: - Pass → "Pass" - Fail → "No Pass" --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Email vacío ### 2. Error buscando empleado ### 3. Sin puesto asignado ### 4. Error obteniendo exámenes ### 5. Error obteniendo resultados ### 6. Error interno del servidor --- # 📚 Schemas ### **Employee** ### **Designation** ### **Quiz Activity** --- # 🗃 Lógica en pseudo-código

`email = request.emaildate = request.dateif email is empty: return erroremployee = GET Employee by user_id=emailif empty: return errordesignation = employee.designationif empty: return errorexams = GET Designation/examsrange = firstDayOfMonth(date), lastDayOfMonth(date)quizResults = GET QuizActivity where dni = employee.passport_number and creation between rangeprepare response: for each exam: set puntaje = "-" set estado = "No rindió" for each quizResult: keep best score set estado based on Pass/Failreturn json`

# Módulo Contratación # Documento de Ingresos (Subir Documentos de ingresos (1)) - [documentosIngreso] ## 🧾 Descripción *Registra y actualiza los **documentos obligatorios de ingreso** de un empleado dentro del ERP, así como su información bancaria y de fondo de pensiones.* *Este servicio valida la información mínima necesaria antes de actualizar el documento Employee en el ERP.* 👉 Es un servicio crítico para el proceso de onboarding, ya que sin este registro el empleado no continúa con otros procesos internos. --- # 🚀 Endpoint **POST** **`/documentos-ingreso`** --- # 📥 Parámetros de entrada (Request Body) --- # 🔐 Seguridad Requiere token válido del ERP (la autenticación se maneja internamente mediante `ServiceErp()`). --- # 🧠 Flujo del Servicio (Resumen Real) 1. **Valida que existan campos obligatorios**: - employee - banco - fondo\_pensiones - afiliado\_fondo\_pensiones (“SI” o “NO”) 2. Construye un arreglo con los datos a actualizar: 3. Si el fondo de pensiones es **ONP**, también actualiza: 4. Si se envían documentos opcionales (DNI, copia de DNI de hijos, CV, certificado de trabajo, etc.), también se agregan al payload. 5. Realiza la actualización del empleado: 6. Devuelve la respuesta del ERP junto con los datos enviados. --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Falta el employee ### 2. Falta banco ### 3. Falta fondo de pensiones ### 4. Afiliado fondo pensiones inválido ### 5. Error del ERP al actualizar --- # 📚 Data Model Usado ### Employee (PUT) Campos actualizables: --- # 🗃 Pseudocódigo de la lógica # Documento de Ingresos (Formulario Ficha de Personal (1)) - [formFichaPersonal] ### 🧾 Descripción *Registra la **Ficha Personal** del trabajador, permitiendo actualizar:* - Datos de contacto de emergencia - Información del cónyuge/conviviente según estado civil - Registro del proceso en el módulo *historial\_procesos\_app* *Es un servicio utilizado por la aplicación para completar los datos obligatorios que el trabajador debe registrar para continuar con otros procesos internos.* *Este servicio actualiza directamente el documento **Employee** en el ERP.* --- # 🚀 Endpoint

**`POST /form-ficha-personal`**

--- # 📥 Request Body (JSON) Los campos **contactoEmergencia** y **estadoCivil** vienen como JSON string y se decodifican dentro del servicio. --- # 🔐 Seguridad - Requiere autenticación interna ERP vía `ServiceErp()`. - Solo accesible para usuarios autenticados en la app. - Valida que el Employee exista antes de actualizar. --- # 🧠 Flujo del Servicio (Paso a Paso) ### 1️⃣ Validaciones iniciales - Verifica que **estadoCivil** exista. - Verifica que **contactoEmergencia** exista. - Si faltan datos, devuelve error. ### 2️⃣ Obtiene información del empleado Valida que el empleado exista y revisa si tiene estado civil registrado en el ERP: - Si es **Casado/a** o **Conviviente**, revisa que toda la información del cónyuge esté completa. ### 3️⃣ Determina nuevo estado civil Si el ERP no tiene estado civil registrado: - Si `estadoCivil["nombreCompleto"]` existe → **Casado/a** - Si no existe → **Soltero/a** ### 4️⃣ Construye el body para actualizar Employee Campos incluidos: Todos los textos se envían en mayúsculas. ### 5️⃣ Actualiza Employee ### 6️⃣ Registra proceso de Ficha Personal Inserta un registro en MySQL (`historial_procesos_app`) con: - proceso = "registerFichaPersonal" - fecha actual - empleado Sirve para el tracking de documentos obligatorios. ### 7️⃣ Respuesta exitosa Devuelve: --- # 📤 Response 200 – Ejemplo ### ✔️ Caso exitoso ### ❌ Error: falta información del estado civil ### ❌ Error: datos incompletos del cónyuge ### ❌ Error al actualizar en el ERP --- # ❗ Posibles Errores Detallados

Error	Descripción
Missing estadoCivil	No se envió estado civil o JSON inválido
Missing contactoEmergencia	Falta información mínima para completar la ficha
Employee no encontrado	GET Employee/{empleado} no encontró registro
Información incompleta del cónyuge	Falta un campo requerido cuando el estado civil es casado/conviviente
Error de actualización	PUT Employee falló
Error registrando proceso	Inserción en historial\_procesos\_app falló

--- # 📚 Schemas (Estructuras Utilizadas) ### Employee (GET y PUT) Campos usados:

`person_to_be_contactedrelationemergency_phone_numbernombre_completo_conyuguefecha_de_nacimiento_conyugueocupación_conyuguecentro_de_trabajo_conyuguedirección_actual_conyugueestado_civil_personal`

### historial\_procesos\_app (INSERT) --- # 🗃 Lógica en pseudo-código

`empleado = request.empleadocontacto = json_decode(request.contactoEmergencia)civil = json_decode(request.estadoCivil)if civil is null or empty: return error("No tiene información de estado civil")if contacto is null: return error("Falta información de contacto de emergencia")employee = GET Employee/{empleado}if civil.previous == Casado or Conviviente: validar campos completos de cónyugenewCivil = employee.estadoCivil != "" ? employee.estadoCivil : (civil.nombreCompleto ? "Casado/a" : "Soltero/a")bodyPUT = construir campos del contacto + cónyugeupdate = PUT Employee/{empleado}if update.ok: insertar registro en historial_procesos_app return successelse: return error("Ocurrió un error al actualizar")`

# Documento de Ingresos (Verificar Registro de Postulación (1)) - [validatePersonalRequirement] ## 🧾 Descripción *Este servicio valida si un postulante (que ya es empleado o está en proceso de contratación) **cumple con las condiciones necesarias para continuar el proceso de Alta y Requerimiento de Personal**.* La validación se basa en: - Información del **Employee** - Su **postulación (Job Applicant)** - Su **Convocatoria (Job Opening)** - Su **Terminal / Sucursal (Branch)** - El **Requerimiento de Personal** asociado a la convocatoria Este servicio permite determinar si se puede generar su trámite de contratación y qué parámetros corresponden a su modalidad de trabajo y tipo de jornada. --- # 🚀 Endpoint **POST /validate-personal-requirement** ### 📥 Request Body Parámetros: - **document**: DNI o pasaporte del postulante. --- # 🔐 Seguridad Requiere autenticación interna hacia el ERP mediante `dbErp()` y rutas definidas en `APICAPACITACION`. --- # 🧠 Flujo del Servicio (Resumen) ### 1️⃣ Validar si el documento pertenece a un *Employee* Consulta en `tabEmployee`: - Si no existe → ❌ devuelve error. --- ### 2️⃣ Buscar su postulación más reciente (Job Applicant) Consulta: - Si no tiene postulación → ❌ retorna error. --- ### 3️⃣ Obtener información de la Convocatoria (Job Opening) Consulta: - Determina: - **Tipo de jornada / modalidad** de la convocatoria. - **Sucursal asignada** al postulante. --- ### 4️⃣ Obtener información de la Sucursal (Branch) Consulta: - Determina la zona RRHH responsable. - Según la zona, define qué tabla usar para el Requerimiento de Personal: - **Lima → `tabRequerimiento de Personal Lima`** - **Otros → `tabRequerimiento de Personal`** --- ### 5️⃣ Obtener el Requerimiento de Personal asociado a la convocatoria - Si no existe RP → ❌ el proceso de contratación debe repetirse. --- ### 6️⃣ Respuesta exitosa Devuelve: - Tipo de jornada - Modalidad del puesto - Código de convocatoria --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. No existe empleado con el documento --- ### 2. No existen postulaciones válidas --- ### 3. Convocatoria no encontrada --- ### 4. Sucursal/Terminal inexistente --- ### 5. Requerimiento de Personal no creado --- ### 6. Error del servidor --- # 📚 Esquemas utilizados ### **Employee** Campos consultados: --- ### **Job Applicant** --- ### **Job Opening** --- ### **Branch** --- ### **Requerimiento de Personal** --- # 🗃 Lógica en Pseudocódigo

`employee = GET Employee WHERE passport_number = documentif not employee: error("Empleado no encontrado")postulacion = GET Job Applicant WHERE document = document ORDER BY creation DESCif not postulacion: error("Postulación no encontrada")convocatoria = GET Job Opening WHERE name = postulacion.job_titleif not convocatoria: error("Convocatoria no encontrada")branch = GET Branch WHERE name = convocatoria.sucursalselect RP_table = Branch.zone == Lima ? RP_Lima : RP_Normalrp = GET RP_table WHERE documento_convocatoria = job_titleif not rp: error("RP no creada")return { tipo_jornada: rp.tipo_de_jornada, modalidad: convocatoria.modalidad || modalidad_de_trabajo, convocatoria: job_title}`

# Documento de Ingresos (Registrar Proceso de Descarga (1)) - [registerProcessApp] ## 🧾 Descripción *Registra en la tabla `historial_procesos_app` cada evento o proceso realizado por un usuario dentro de la aplicación móvil.* *Además, dependiendo del tipo de proceso, realiza validaciones adicionales como:* - Validación de renovación de contrato - Validación de cambio de modalidad - Creación automática de usuario conductor en sistema externo - Validación de existencia del empleado en ERP Este servicio funciona como logger centralizado de acciones críticas del trabajador. --- ## 🚀 Endpoint **POST** **`/register-process-app`** --- ## 📥 Parámetros de Entrada (Body) --- ## 🔐 Seguridad - Acceso interno del sistema - Requiere conexión válida a BD secundaria (`mysql2`) - Valida datos contra API ERP mediante `dbErp` y `ServiceErp` --- ## 🧠 Flujo del Servicio (Resumen Real) ### 1️⃣ Obtiene parámetros principales del request: - usuario - empleado - agencia - lat/long - proceso - month / year --- ### 2️⃣ Si el proceso es **descargaContratoReingreso** - Ejecuta validación de renovación del contrato: - Ejecuta validación de cambio de modalidad: --- ### 3️⃣ Si el proceso es **descargaContratoTrabajo** #### a) Obtiene datos del empleado en el ERP (Documento, sucursal, nombre y puesto) #### b) Si el puesto contiene la palabra **CONDUCTOR** El sistema crea un **usuario conductor** en un sistema externo:

`POST EMPRESARIAL/api/crearUsuarioConductor{ documento: DNI, ter_id: id_sucursal, nombre: nombre_completo}`

Cualquier error en este paso retorna: --- ### 4️⃣ Inserta el registro del proceso en `historial_procesos_app` Campos insertados:

Campo	Descripción
usuario	Usuario que ejecuta el proceso
empleado	Código del empleado
agencia	ID de la agencia
latitude	Latitud
longitude	Longitud
proceso	Nombre del proceso ejecutado
fecha	Fecha y hora actual
estado	1 (registrado)
month	Mes
year	Año

--- ### 5️⃣ Devuelve respuesta exitosa --- ## 📤 Respuestas ### ✔ **200 – Éxito** --- ### ❗ Error al insertar registro --- ### ❗ Empleado no encontrado --- ### ❗ Error de creación de usuario conductor --- ## 📚 Estructuras utilizadas ### Tabla: historial\_procesos\_app ### ERP: Employee Campos usados: --- ## 🗃 Lógica en Pseudocódigo # Documento de Ingresos (Registrar Equipamiento (1)) - [store_equipament] ## 🧾 Descripción *Registra o actualiza las tallas de **equipamiento de EPP** (botas, polo, pantalón) para un postulante, validando previamente:* - Que el documento exista en el sistema. - Que las tallas enviadas sean válidas según los rangos permitidos. - Que el postulante exista. - Que ya tenga o no un registro previo en **Triaje de Postulante 2**, para decidir entre **crear (POST)** o **actualizar (PUT)**. *Es un servicio que integra:* - Validaciones locales. - Consulta de postulantes. - Inserción o actualización en el ERP vía **ServiceErp()**. --- # 🚀 Endpoint **POST** **`/store-equipament`** --- # 🔐 Seguridad Requiere autenticación interna contra el ERP mediante: - `ServiceErp()` - `searchPostulanteByDocument()` No hace validaciones de token en el controlador; se maneja internamente por los métodos usados. --- # 🧠 Flujo del Servicio (explicación real) 1. **Lee los parámetros enviados en la petición**: - documento - botas - polo - pantalon 2. **Valida la estructura y tallas permitidas**:

Elemento	Tallas permitidas
botas	36–45
polo	S, M, L, XL
pantalón	S, M, L, XL

3. **Busca al postulante por documento**: Llama a: Si no existe → retorna error. 4. **Busca si ya existe un registro de triaje activo en el ERP**: GET `/resource/Triaje de Postulante 2` con filtros: 5. Dependiendo del resultado: - **No existe registro → crea uno (POST)** - **Sí existe → actualiza el existente (PUT)** 6. **Realiza el POST o PUT correspondiente** hacia el ERP. 7. **Si ERP devuelve error**, intenta decodificar `_server_messages` para obtener error real del ERP. 8. **Retorna respuesta final** indicando éxito o error. --- # 📥 Request Body Ejemplo: --- # 📤 Response 200 – Ejemplos ### ✔️ Registro/Actualización exitosa ### ❌ Documento no enviado ### ❌ Talla inválida ### ❌ Postulante no encontrado ### ❌ Error del ERP --- # ❗ Posibles Errores del Servicio

Tipo	Ejemplo
Documento no enviado	`"Falta enviar el documento"`
Talla no válida	`"Ingrese una talla de botas válida"`
Postulante no encontrado	respuesta directa del servicio `searchPostulanteByDocument`
Error al crear/actualizar en ERP	Mensaje del `_server_messages` o mensaje genérico
Error inesperado	Devuelve el error capturado del ERP

--- # 🗃 ERP: Documentos involucrados ### **Triaje de Postulante 2 (GET / POST / PUT)** Campos usados:

Campo	Tipo
documento	string
botas	int
polo	string
pantalon	string
name	string (clave para PUT)

--- # 🧩 Lógica en Pseudocódigo

`read document, botas, polo, pantalonvalidate documentvalidate botas in [36..45]validate polo in [S,M,L,XL]validate pantalon in [S,M,L,XL]postulante = searchPostulanteByDocument(document)if postulante.invalid: return errortriaje = GET TriajeDePostulante2 where documento=document and docstatus != 2if triaje exists: method = PUT url = recurso + "/" + triaje.nameelse: method = POST url = recursobody = { documento, botas, polo, pantalon}result = CALL ERP with method, body, urlif result.error: return readable ERP errorreturn success`

# Documento de Ingresos (Registrar Proceso de Descarga (1, 2,3,4,5)) - [registerProcessApp] ### 🧾 Descripción *Registra en la tabla `historial_procesos_app` todas las acciones (procesos) que el usuario realiza dentro del aplicativo móvil, como descargas de documentos, validación de contratos, marcaciones, entre otros.* Antes de registrar el proceso: 1. **Valida si corresponde un proceso de Reingreso o Renovación de Contrato.** 2. **Procesa el registro especial para Conductores**, creando su usuario en el sistema empresarial cuando descarga su contrato. 3. **Guarda la información del evento** (geolocalización, mes, año, proceso, etc.) en la base de datos MySQL2. Este servicio constituye una pieza clave para los módulos de: - Marcación - Documentos obligatorios - Control de procesos del trabajador - Contratos / renovaciones --- # 🚀 Endpoint ### `POST /register-process-app` --- # 📥 Request Body --- # 🔐 Seguridad - Requiere **token válido** para consumir servicios internos del ERP. - Conexión interna a MySQL2 para registrar procesos. - Algunos procesos hacen integración con APIs externas (como Empresarial → creación de usuario conductor). --- # 🧠 Flujo del Servicio (resumen real) ### 1️⃣ Obtiene los parámetros enviados desde la App Usuario, empleado, agencia, geolocalización, proceso, mes y año. ### 2️⃣ Si el proceso es **descargaContratoReingreso** Ejecuta: - **validateProcessContractRenovation()** - **validateProcessContractChangeModality()** Estas funciones validan: - Si el empleado tiene renovación pendiente - Si debe descargar documentos obligatorios - Si existen cambios de modalidad pendientes ### 3️⃣ Si el proceso es **descargaContratoTrabajo** 1. Obtiene datos del empleado desde ERP: - DNI (passport\_number) - Sucursal - Nombre completo - Puesto (designation) 2. Si el puesto contiene `"CONDUCTOR"`, registra el usuario en el sistema empresarial:

`POST EMPRESARIAL/api/crearUsuarioConductor`

Enviando: ### 4️⃣ Inserta el proceso en la tabla MySQL: Tabla: **historial\_procesos\_app** Campos guardados: - usuario - empleado - agencia - latitude - longitude - proceso - fecha - estado - month - year ### 5️⃣ Retorna la respuesta del proceso --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. No se puede registrar el proceso en MySQL ### 2. No se encuentra el empleado en el ERP ### 3. Error creando usuario conductor ### 4. Error genérico --- # 📚 Schemas – Objetos usados ### 🗂 Employee (GET ERP) Campos usados: ### 🗂 Registro MySQL – historial\_procesos\_app --- # 🗃 Lógica en pseudo-código # Contrato de Trabajo(Url Contrato de trabajo PDF (1)) - [printContractPerDesignation] ## 🧾 Descripción *Genera y descarga el **Contrato de Trabajo** correspondiente a un empleado, seleccionando de forma automática el **formato de contrato correcto** según:* - Tipo de documento del empleado (DNI / PAS / CE) - Modalidad laboral (Full time, Part time, Teletrabajo) - Tipo de puesto (Ej. Conductor, Vigilante) - Número de contratos previos - Funciones asociadas al contrato (solo extranjeros) El servicio determina internamente qué plantilla PDF debe usarse y devuelve el archivo final generado. Es un servicio interno que consulta múltiples recursos del ERP: - Employee - Contrato de Trabajo - Funciones del Contrato - Otros contratos previos --- ## 🚀 Endpoint **`GET /print-contract-per-designation/{employee}`** ### 📥 Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
employee	string	Sí	Código único del empleado en ERP

--- ## 🔐 Seguridad Requiere autenticación interna: - Consulta ERP vía `dbErp()` - Obtención de PDF vía `PDF::loadView()` --- ## 🧠 Flujo del Servicio (Resumen Real) ### **1️⃣ Validación del empleado** Consulta al ERP:

`POST send-query-databaseFROM tabEmployeeWHERE name = employeeSELECT fecha_de_ingreso_real`

Si no existe → retorna error: *"No existe empleado"*. --- ### **2️⃣ Obtiene el contrato activo más reciente** Se buscan contratos con: - `empleado = employee` - `docstatus = 1` - `fecha_de_ingreso_real = fecha_ingreso_empleado` - Ordenado por creación descendente

`POST send-query-databaseFROM tabContrato de TrabajoLEFT JOIN tabEmployee`

Si no existe contrato → retorna *"No cuenta con Contrato"*. --- ### **3️⃣ Obtiene funciones asociadas (solo extranjeros)** Busca funciones del contrato:

`FROM tabtabla_funcion_extranjeroWHERE parent = contrato.name`

Estas funciones se agregan al contrato en el PDF. --- ### **4️⃣ Determina el número de contratos previos** Solo aplica a empleados con documento **PAS** o **CE**. Consulta cantidad de contratos registrados después del ingreso real. Esto permite determinar si el contrato es: - Primer contrato - Segundo contrato - Tercer contrato - Etc. (usando arreglo ordinal: primero, segundo, tercero, …) --- ### **5️⃣ Selección automática de la plantilla PDF** En base a reglas:

Condición	Plantilla
modalidad\_de\_trabajo = Teletrabajo	contrato\_teletrabajo
labor contiene "CONDUCTOR"	contrato\_conductor\_interprovincial
labor = "VIGILANTE"	contrato\_full\_time\_vigilante
tipo\_doc PAS o CE, primer contrato	contrato\_extranjero
tipo\_doc PAS o CE, más de 1 contrato	contrato\_extranjero\_mas\_de\_segundo\_contrato
tipo\_contrato = PART TIME, labor=CALL CENTER ATC	contrato\_call\_center\_part\_time
tipo\_contrato = PART TIME	contrato\_part\_time
tipo\_contrato = FULL TIME	contrato\_full\_time

El método retorna el PDF con: --- ## 📤 Response – Archivo PDF Retorna directamente la descarga del contrato correspondiente. Si ocurre algún error, retorna un JSON: ### ✔️ Empleado válido, pero sin contrato ### ❌ Empleado no encontrado --- ## ❗ Posibles Errores

Error	Descripción
Empleado no existe	No se encontró en tabEmployee
No tiene contratos vigentes	No existe Contrato de Trabajo activo
Error DB ERP	Respuesta inesperada en dbErp
Plantilla no encontrada	Error al cargar vista PDF (muy raro)

--- ## 📚 Tablas y Campos Utilizados ### **Employee (GET)** Campos usados: ### **Contrato de Trabajo** ### **Funciones del Contrato (Extranjeros)** --- ## 🗃 Lógica en Pseudocódigo # Módulo Boletas de Pago # Boleta Mensual(Obtener Proceso de Descarga (1)) - [obtener] ### 🧾 Descripción *Este servicio permite **buscar y obtener información detallada de una denuncia** registrada en el ERP, usando un **código aleatorio** generado para consulta pública.* La función: - Busca la denuncia usando el campo `codigo_aleatorio`. - Retorna información clave como: - estado de la denuncia, - fecha de creación, - fecha de atención, - fecha de proceso, - respuesta, - y un archivo asociado (si existe). - Construye la URL completa del archivo para ser descargado por el cliente. Es un servicio de consulta directa, sin dependencias entre módulos. --- # 🚀 Endpoint ### **POST /obtener** ### 📥 Request Body --- # 🔐 Seguridad No requiere token especial más allá del utilizado internamente por `apiService()` o `ServiceErp()`. La autenticación se maneja dentro del sistema ERP. --- # 🧠 Flujo del Servicio (resumen real) 1. Recibe el parámetro: `codigo = $request->codigo` 2. Construye un request hacia el ERP: `GET Denuncias?fields=[...]&filters=[["codigo_aleatorio","=",codigo]]` Campos obtenidos: - name - creation - estado\_denuncias - fecha\_atendido - fecha\_proceso - archivo\_denuncia - respuesta\_de\_denuncia\_atendido 3. Si no existe la denuncia → se responde: 4. Si existe y tiene archivo, se concatena la URL base: 5. Se devuelve la **primera denuncia encontrada**, ya que el código es único. --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. No se encuentra la denuncia ### 2. Error del ERP ### 3. Código vacío o inválido --- # 📚 Schemas Usados ### **Denuncias (GET)** Campos usados: --- # 🗃 Lógica del Servicio (Pseudo-código)

`codigo = request.codigobody = { limit = None fields = [name, creation, estado_denuncias, fecha_atendido, fecha_proceso, archivo_denuncia, respuesta...] filters = [["codigo_aleatorio", "=", codigo]]}response = GET Denuncias using ServiceErpif !response.valor or response.response is empty: return error "No se encontró la denuncia"denuncia = response.response[0]if denuncia.archivo_denuncia != "": denuncia.archivo_denuncia = BASE_CAPACITACION + denuncia.archivo_denunciareturn success with denuncia`

# Utilidades(Consultar Utilidades (1)) - [getYearUtilidades] ## 🧾 Descripción Este servicio obtiene: 1. **La lista de años registrados en el ERP** (tabla *Year*), ordenados de forma descendente. 2. **Valida si el empleado tiene utilidades asignadas** para al menos un año (tabla *Utilidades*). El objetivo es determinar si el empleado cuenta con utilidades cargadas y retornar la lista de años disponibles para consulta. --- ## 🚀 Endpoint **`POST /get-year-utilidades`** --- ## 📥 Parámetros de entrada (Request Body) ### Campos

Campo	Tipo	Obligatorio	Descripción
employee	string	✔	ID del empleado para validar si tiene utilidades.

--- ## 🔐 Seguridad Utiliza autenticación mediante `ServiceErp()` (token interno del ERP). No requiere permisos adicionales, ya que solo consulta información. --- ## 🧠 Flujo del Servicio (explicación real) ### 1️⃣ Obtener los años disponibles (tabla Year) Llama al ERP: `GET Year?limit=None&fields=["name"]` - Extrae todos los registros. - Toma únicamente la columna `name`. - Ordena los años de forma descendente. --- ### 2️⃣ Validar si el empleado tiene utilidades registradas Consulta al ERP: `GET Utilidades?limit=None&fields=["name"]&filters=[["empleado","=", employee]]` - Si no existe ningún registro → El empleado **no tiene utilidades asignadas**. - Si existe al menos un registro → El empleado **sí tiene utilidades asignadas**. --- ## 📤 Response 200 – Ejemplo ### Caso 1 — El empleado **NO tiene utilidades** ### Caso 2 — El empleado **SÍ tiene utilidades** 📌 *Nota:* El mensaje es el mismo en ambos escenarios, siguiendo el comportamiento del código original. --- ## ❗ Posibles Errores

Caso	Respuesta
Error al obtener años del ERP	years → \[\] (no rompe el flujo)
Error de conexión con el ERP	years → \[\]
El empleado no tiene utilidades	`"valor": false`
El empleado sí tiene utilidades	`"valor": true"`

--- ## 📚 Tablas usadas (schemas) ### 📄 Year (GET) Campos usados: `{ "name": "string"}` ### 📄 Utilidades (GET) Campos usados: `{ "name": "string"}` --- ## 🗃 Lógica en pseudo-código # Utilidades(Obtener Proceso de Descarga (1, 2, 3,4,5)) - [show] ## 🧾 Descripción *Este servicio permite **consultar el último registro** almacenado en la tabla `historial_procesos_app` según:* - Empleado - Proceso - (Opcional) Año - (Opcional) Mes Es usado para validar si un empleado ya realizó o no un proceso específico dentro del aplicativo. --- # 🚀 Endpoint **POST** `/show` --- # 📥 Parámetros de Entrada (Request Body) ### 🔎 Descripción de parámetros

Parámetro	Tipo	Obligatorio	Descripción
empleado	string	✔	Código del empleado a consultar
proceso	string	✔	Nombre del proceso a buscar
anio	int	✖	Año del proceso (filtrado opcional)
mes	int	✖	Mes del proceso (filtrado opcional)

--- # 🔐 Seguridad Utiliza conexión directa a la base de datos `dbapp`. No requiere token ERP, pero depende de la autenticación interna del backend. --- # 🧠 Flujo del Servicio (Resumen real) 1. **Validar parámetros obligatorios** - Si no se envía *empleado* → retorna error - Si no se envía *proceso* → retorna error 2. **Construir filtros dinámicos** - Base: empleado + proceso - Si llega año → se agrega al `WHERE` - Si llega mes → se agrega al `WHERE` 3. **Consultar la tabla interna** Query sobre: Utiliza `first()` para obtener el último registro. 4. **Validar si existe registro** - Si no existe, devuelve mensaje informando que no se encontró el proceso. 5. **Retornar información del proceso encontrado** Incluye toda la fila obtenida desde la base de datos. --- # 📤 Response 200 – Ejemplos ### ✅ Caso exitoso ### ❌ Faltan parámetros ### ❌ No existe el proceso --- # ❗ Posibles Errores 1. **No se envía `empleado`** 2. **No se envía `proceso`** 3. **No se encontró el registro** 4. **Error interno de base de datos** (Puede retornar error 500 desde DB, manejado por Laravel) --- # 📚 Estructura usada (historial\_procesos\_app) --- # 🗃 Lógica en Pseudo-código # CTS(Url CTS PDF (1)) - [pdfCTS] ### 🧾 Descripción *Genera el **PDF de la Compensación por Tiempo de Servicios (CTS)** de un empleado para un periodo específico (mes y año).* *El servicio consulta la información almacenada en el ERP y retorna el archivo PDF ya renderizado desde una vista Blade (`pdf/cts`).* También valida si la descarga está habilitada según la fecha definida por la empresa: - CTS de **Mayo** se habilita **desde el 16 de mayo** - CTS de **Noviembre** se habilita **desde el 16 de noviembre** Si el usuario intenta descargar antes de esas fechas, el servicio lo bloquea. --- # 🚀 Endpoint **GET /pdf-cts/{employee}/{month}/{year}** ### Parámetros

Parámetro	Tipo	Descripción
employee	string	ID del empleado
month	string/int	5 ó 11 (Mayo / Noviembre)
year	string/int	Año del cálculo CTS

--- # 🔐 Seguridad Este servicio requiere una **autenticación interna** mediante `apiService()` para consumir los datos del ERP. No necesita token del cliente, pero sí credenciales válidas para el ERP. --- # 🧠 Flujo del Servicio (resumen real) ### 1️⃣ Validación del Mes Convierte el mes recibido:

Valor recibido	Se interpreta como
`"5"`	`"MAYO"`
`"11"`	`"NOVIEMBRE"`

### 2️⃣ Validación de Fecha de Bloqueo El servicio verifica si la fecha actual está dentro del periodo permitido: - Para **Mayo**: 📅 Debe ser **a partir del 16-05-<año>** - Para **Noviembre**: 📅 Debe ser **a partir del 16-11-<año>** Si aún no llega la fecha → se retorna: --- ### 3️⃣ Obtiene la CTS del ERP Se consulta la API del ERP: Se recuperan campos como: - remuneración computable - días computables - banco del empleado - CTS total a pagar - datos personales Si no existen registros → retorna: --- ### 4️⃣ Genera el PDF Si existe el registro, el servicio envía la información a la vista: `resources/views/pdf/cts.blade.php` Luego devuelve el PDF: --- # 📥 Request Body No utiliza body. --- # 📤 Response – Ejemplo exitoso El servicio no retorna JSON cuando es exitoso, sino un **PDF vía stream**, por lo que la respuesta es un archivo. Ejemplo conceptual: `CTS Mayo 2024>` --- # ❗ Posibles Errores ### 1. CTS no habilitado por fecha ### 2. CTS inexistente para el periodo ### 3. Parámetros mal enviados ### 4. Error interno del ERP Retorna el error capturado del servicio `apiService()`. --- # 📚 Schemas involucrados ### **Compensación por Tiempo de Servicios (CTS)** Campos usados:

`{ "dias_ausencias": int, "dias_de_licencia_sin_goce": int, "dias_de_descanso_medico": int, "descuento_de_dias_de_ausencia": number, "promedio_remunerativo": number, "name": string, "nombre_de_compañia": string, "ruc": string, "ubicacion": string, "nombre_completo": string, "mes": "MAYO/NOVIEMBRE", "año": string, "cuenta_de_banco": string, "nombre_de_banco": string, "asignacion_familiar": number, "gratificacion_entre_seis": number, "horas_extras_entre_seis": number, "horas_nocturnas_entre_seis": number, "remuneracion_computable_cts": number, "meses_computables_cts": number, "pago_meses": number, "dias_computables_cts": number, "pago_dias": number, "cts_total_a_pagar": number, "tipo_de_documento": string, "dni": string}`

--- # 🗃 Lógica en pseudo-código # Reconocimiento de deuda( Url Reconocimiento de deuda PDF (1) ) - [debtRecognition] ## 🧾 Descripción *Este servicio valida si un empleado tiene un **Reconocimiento de Deuda pendiente de firma**, y en caso afirmativo, **genera y descarga el archivo PDF del documento**, incluyendo el detalle de cuotas asociadas.* *El servicio consume directamente información del ERP, consultando tanto el documento principal como sus tablas hijas (detalles de deuda por mes).* --- ## 🚀 Endpoint **POST /debt-recognition** ### 📥 Parámetros Recibe como parámetro directo el **ID del empleado**: --- ## 🔐 Seguridad El servicio requiere autenticación interna vía `dbErp()` para consultas SQL y usa `PDF::loadView()` para generar el documento final. --- ## 🧠 Flujo del Servicio (resumen real) ### 1. **Verifica si existe un Reconocimiento de Deuda pendiente** Consulta en el ERP: - Documento: **Reconociemientos de Deuda** - Condiciones: - `docstatus = 0` (borrador) - `empleado = ` - El archivo firmado **no existe** → `reconocimiento_escaneado_firmado IS NULL or = ''` Si no encuentra ningún registro: --- ### 2. **Obtiene los datos del Reconocimiento de Deuda** Si existe un documento pendiente: - Recupera el primer registro encontrado. - Extrae datos generales del reconocimiento. --- ### 3. **Obtiene el detalle (tabla hija) del reconocimiento** Consulta: - Tabla hija: **tabtable\_reconocimiento\_deuda** - Llaves: - `parent`: ID del reconocimiento - `parentfield = table_21` - `parenttype = Reconociemientos de Deuda` Los campos recuperados: --- ### 4. **Construye la data final** Une: - Información principal del reconocimiento (`dataEmployee`) - Detalle de cuotas (`dataTable`) --- ### 5. **Genera el documento PDF** Renderiza la vista: **pdf/Doctype/ReconocimientoDeDeuda/reconocimiento\_de\_deuda.blade.php** Y retorna la descarga del PDF. --- ## 📤 Response – Archivo PDF El servicio retorna directamente un PDF generado con domPDF:

`Content-Type: application/pdfContent-Disposition: attachment; filename="ReconocimientoDeDeuda.pdf"`

No devuelve un JSON en caso de éxito, sino **una descarga directa del documento**. --- ## ❗ Posibles Errores ### 1. No existe reconocimiento pendiente ### 2. Error en la consulta ERP ### 3. Error inesperado en PDF o datos --- ## 📚 Schemas usados ### Reconociemientos de Deuda (principal) ### table\_reconocimiento\_deuda (detalle) --- ## 🗃 Pseudocódigo del Servicio # Módulo de Solicitudes # Solicitud de Adelanto( Solicitar de adelanto de sueldo (1) ) - [guardarAdelantosMensual] ## 🧾 Descripción *Registra la **solicitud de adelanto salarial mensual** para un empleado, validando una serie de reglas de negocio relacionadas con:* - Fecha permitida para solicitar adelanto - Tipo de trabajador - Área, puesto y compañía - Situación laboral (activo/licencia) - Contratos y antigüedad mínima - Restricciones internas por área o cargo - Estructura mensual del ERP (“Solicitud de Adelanto Mensual”) El servicio crea o actualiza el registro correspondiente al empleado dentro del documento mensual de adelantos. --- # 🚀 Endpoint **POST** /guardar-adelantos-mensual/{employee}/{amount} ✔ **Recibe:** - `employee` (string) — ID del empleado - `amount` (int/string) — Monto seleccionado --- # 🔐 Seguridad Requiere autenticación del ERP (realizada internamente vía `ServiceErp()`). --- # 🧠 Flujo del Servicio (lógica real) ### 1️⃣ Validación inicial del monto - Si el monto es `"Seleccionar"` → **error** ### 2️⃣ Obtiene la ficha del empleado Se validan: - Compañía = "Shalom Empresarial" - Estado = "Active" ### 3️⃣ Validaciones por fecha - Solo se puede solicitar entre el **día 1 y 14** - Excepción especial: julio 2023 (solo hasta el día 13) - Si el empleado ingresó este mes y su día de ingreso ≥ 5 → no puede solicitar ### 4️⃣ Validaciones por tipo de trabajo - Part time → máximo S/ 100 - Gerencia → no permitido - Jefes o Supervisores (excepto Atención al cliente - SE) - Administrativos (excepto Atención al cliente - SE) - Conductores → prohibido solicitar ### 5️⃣ Validación de asistencia Se verifica si hoy está con licencia: Si está con licencia → **no puede solicitar adelanto**. ### 6️⃣ Ubica o crea el documento mensual tipo "Solicitud de Adelanto Mensual" Se busca: - Si **no existe**, se crea un nuevo documento para el mes ### 7️⃣ Registra o actualiza al trabajador dentro de la tabla interna `table_12` - Si el empleado **no existe** → se crea un nuevo registro (POST) - Si ya existe → se actualiza solo el campo `monto` (PUT) ### 8️⃣ Devuelve la respuesta con todos los registros procesados. --- # 📥 Request Body No recibe body (los parámetros son por URL). --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Monto inválido ### 2. Empresa no permitida ### 3. Empleado deshabilitado ### 4. Fecha fuera de rango ### 5. Restricción por área o tipo de empleado ### 6. Empleado con licencia ### 7. Error al crear documento mensual --- # 📚 Schemas utilizados ## Employee (GET Employee/{id}) Campos relevantes: ## Solicitud de Adelanto Mensual (GET/POST) Campos usados: ## Registro en tabla interna (table\_12) --- # 🧠 Lógica en pseudo-código # Solicitud de Adelanto(Estado solicitud (1,2,3,4) - Adelante de sueldo) - [show] 🧾 **Descripción** *Este servicio permite obtener el **estado actual** de distintos procesos vinculados a un trabajador, tales como:* - Cambio de cuenta bancaria - Solicitud de licencia - Asignación familiar - Adelanto salarial del mes en curso El servicio analiza dinámicamente el tipo de proceso solicitado. Si se envía un tipo de proceso específico, consulta su última solicitud pendiente. Si **no** se envía proceso, valida automáticamente si el trabajador tiene **adelanto salarial** en el mes actual y devuelve su estado. 📌 Es un servicio que depende totalmente de la API del ERP para obtener la información. --- # 🚀 Endpoint **POST** **`/estado-solicitud`** --- # 📥 Request Body ### Parámetros

Campo	Tipo	Obligatorio	Descripción
empleado	string	✔️	Código del empleado en ERP
proceso	string	opcional	Tipo de solicitud a consultar (“cambio de cuenta”, “licencia”, “asignación familiar”). Si no se envía, se valida “adelanto salarial”.

--- # 🔐 Seguridad Requiere autenticación interna y comunicación con el ERP vía `dbErp()` y `ServiceErp()`. --- # 🧠 Flujo del Servicio (resumen real) ### 🔸 1. Validación Inicial Obtiene: - mes actual - año actual - día actual Define tablas ERP según el proceso solicitado. --- ### 🔸 2. Cuando **se envía un proceso específico** Los procesos admitidos son:

Proceso enviado	Tabla consultada	Campo de relación
"cambio de cuenta"	`tabCambio de Cuenta Bancaria`	empleado
"licencia"	`tabSolicitud de Licencias`	id\_empleado
"asignación familiar"	`tabSolicitud Asignacion Familiar`	id\_empleado

El servicio: 1. Construye los filtros del ERP. 2. Busca la **última solicitud activa** (`docstatus < 2`). 3. Si no encuentra registros → devuelve un mensaje indicando que no existe solicitud. 4. Si existe: - Lee `motivo` - Lee `validacion_solicitud` - Lee `docstatus` - Devuelve estado traducido a texto. Estados interpretados:

docstatus	Estado
0	En proceso
1	Aprobado
2	Pagado
3	Rechazado

--- ### 🔸 3. Cuando **NO se envía proceso: Validación de adelanto salarial** 1. Obtiene el **adelanto salarial del mes** (`tabSolicitud de Adelanto Mensual` + tabla interna hija). 2. Si no existe solicitud → devuelve mensaje correspondiente. 3. Si existe, continúa: - Revisa si existe **Solicitud de Pagos** pagada relacionada al mes. - Si se encuentra, asigna estado "Pagado". - Si docstatus = 0 y el día es >= 17, se marca como "Rechazado". - Caso contrario usa el estado según docstatus. --- # 📤 Response 200 – Ejemplo de solicitud por proceso --- # 📤 Response 200 – Ejemplo para adelanto salarial --- # ❗ Posibles Errores ### 1. Proceso enviado no existe ### 2. No existen solicitudes del tipo indicado ### 3. No existe adelanto salarial para el mes ### 4. Falla consultando al ERP --- # 📚 Schemas (Estructuras utilizadas) ### Solicitud de Licencias ### Solicitud Adelanto Mensual --- # 🗃 Lógica en pseudo-código simplificada

`if request.proceso exists: tabla, where = procesos_config[proceso] data = dbErp(tabla, where) if empty(data): return sin solicitud estado = traducir_docstatus(data.docstatus) return estado, motivo, fechaelse: adelanto = dbErp(Solicitud Adelanto Mensual) if no adelanto: return "no ha solicitado" if solicitud_pagos_pagada AND adelanto.docstatus == 1: estado = Pagado else if docstatus==0 AND día >=17: estado = Rechazado else: estado = según tabla return monto, fecha, estado`

# Cambio de cuenta bancaria(Solicitar cambio de cuenta (1)) - [store] ## 🧾 Descripción *Registra una nueva **solicitud de cambio de cuenta bancaria** para un empleado, validando previamente:* - Que la información esté completa. - Que el formato del número de cuenta coincida con las reglas del banco seleccionado. - Que el empleado **no tenga ya una solicitud en estado Borrador**. - Que se adjunte el documento de acreditación de la nueva cuenta bancaria. *Si todo es correcto, crea un nuevo documento en el ERP: **`Cambio de Cuenta Bancaria`*** --- ## 🚀 Endpoint ### **POST** `/cambio-cuenta-bancaria/store` --- ## 📥 Request Body ### Campos requeridos

Campo	Tipo	Obligatorio	Descripción
empleado	string	✔️	ID del empleado
nuevo\_banco	string	✔️	Nuevo banco elegido
nueva\_cuenta\_bancaria	string	✔️	Número de cuenta del nuevo banco
documento\_cuenta	string	✔️	Archivo previamente cargado en ERP

--- ## 🔐 Seguridad Requiere autenticación interna mediante `ServiceErp()` y `dbErp()` hacia el ERP corporativo. --- ## 🧠 Flujo del Servicio (resumen real) ### **1. Validaciones iniciales** - Verifica que todos los campos obligatorios estén presentes. - Valida longitud del número de cuenta según el banco:

Banco	Longitudes válidas
BCP	14 o 20
BBVA	16, 18 o 20
Interbank	18 o 20
Otros	20

Si no cumple → devuelve error. --- ### **2. Verifica si el empleado ya tiene una solicitud en estado Borrador** Se consulta en el ERP: Si ya existe un documento en borrador → error. --- ### **3. Registrar la nueva solicitud** Si no existe borrador, crea el documento:

`POST resource/Cambio de Cuenta Bancaria{ "empleado": empleado, "nombre_de_banco_nuevo": nuevo_banco, "nuevo_num_de_cuenta_bancaria": nueva_cuenta_bancaria, "documento_cuenta": documento_cuenta}`

--- ## 📤 Response 200 – Éxitoso --- ## ❗ Posibles Errores ### 1. Falta un dato obligatorio ### 2. Número de cuenta inválido ### 3. Ya existe solicitud en borrador ### 4. Error al registrar en ERP --- ## 📚 Schemas utilizados ### **Cambio de Cuenta Bancaria (POST)** ### **Consulta de solicitudes** --- ## 🗃 Lógica en pseudo-código # Solicitud de Licencias(Combo tipos de licencias (1)) - [combos] ## 🧾 Descripción *Servicio que devuelve los valores preconfigurados para el combo **tipos\_licencias**, utilizado por el frontend o aplicación móvil para poblar listas desplegables relacionadas a licencias.* *Este servicio **no realiza operaciones en base de datos**, no consume ERP ni APIs externas.* *Simplemente retorna valores estáticos cargados en la propiedad `$this->tipos_licencias`.* --- ## 🚀 Endpoint **POST /combos** No requiere parámetros. --- ## 🔐 Seguridad No requiere validación adicional. El servicio solo retorna data estática, sin acceso a información sensible del ERP. --- ## 🧠 Flujo del Servicio (resumen real) 1. Obtiene el array interno `$this->tipos_licencias`, previamente definido en el controlador. 2. Construye un arreglo `combos` con la estructura: 3. Retorna una respuesta JSON estándar: --- ## 📥 Request Body No requiere parámetros. Ejemplo: --- ## 📤 Response 200 – Ejemplo *(La estructura real depende del contenido de `$this->tipos_licencias`.)* --- ## ❗ Posibles Errores Este servicio **no genera errores internos**, pues no consulta APIs externas. Solo pueden ocurrir fallas del servidor: ### 1. Error por variable no definida ### 2. Error inesperado del servidor --- ## 📚 Schemas (estructuras usadas) ### Response --- ## 🗃 Lógica en pseudo-código # Solicitud de Licencias(Solicitar solicitud de licencia (1)) - [store] 🧾 **Descripción** *Crea una **Solicitud de Licencias** para un empleado, validando previamente:* - Tipo de licencia permitido - Fechas y rangos máximos establecidos por normativa interna - Archivos obligatorios según el tipo de licencia - Que el empleado no tenga otra solicitud en borrador El servicio registra en el ERP un nuevo documento **"Solicitud de Licencias"** si cumple todas las reglas definidas. --- # 🚀 Endpoint ### **POST /solicitud-licencias/store** --- # 📥 Request Body – Parámetros

Campo	Tipo	Obligatorio	Descripción
empleado	string	sí	ID del empleado
tip\_licencia	string	sí	Tipo de licencia (validado contra `$this->tipos_licencias`)
fecha\_ini	date	sí	Fecha de inicio de la licencia
fecha\_fin	date	sí	Fecha fin de la licencia
declaracion\_jurada	file/url	depende	Obligatorio si tip\_licencia = "Familiar Enfermo"
hoja\_hospitalizacion	file/url	depende	Obligatorio si tip\_licencia = "Familiar Enfermo"
uci	file/url	depende	Obligatorio si tip\_licencia = "Familiar Enfermo"
acta\_nacimiento	file/url	depende	Obligatorio si tip\_licencia = "Paternidad"
acta\_defuncion	file/url	depende	Obligatorio si tip\_licencia = "Licencia Por Luto"

--- # 🧠 Flujo del Servicio (resumen real) 1. **Validación de campos obligatorios** - Verifica empleado, tipo de licencia válido, fecha\_ini y fecha\_fin. 2. **Cálculo de días de licencia** 3. **Validaciones específicas por tipo de licencia**

Tipo de licencia	Requisitos	Máximo días
Familiar Enfermo	declaracion\_jurada, hoja\_hospitalizacion, uci	7
Paternidad	acta\_nacimiento	10
Licencia Por Luto	acta\_defuncion	5
Licencia sin goce	—	30

4. **Validación: El empleado no debe tener una solicitud en borrador** 5. **Construcción del body para enviar al ERP** - Incluye campos adicionales dependiendo del tipo de licencia. 6. **Creación de la solicitud** 7. **Retorno de respuesta estándar** --- # 📤 Response 200 – Ejemplo exitoso *(El campo data retorna el borrador encontrado, si existía.)* --- # ⚠️ Posibles Errores ### 1. Falta de parámetros ### 2. Tipo de licencia inválido ### 3. Fechas incompletas ### 4. Exceso de días permitidos ### 5. Documentación obligatoria faltante ### 6. Solicitud duplicada en borrador ### 7. Error al registrar en ERP --- # 🗃 Lógica en Pseudocódigo

`if empleado vacío → errorif tipo no permitido → errorif fechas vacías → errordias = fecha_fin - fecha_iniswitch tipo_licencia: Familiar Enfermo: validar documentos validar dias <= 7 Paternidad: validar acta_nacimiento validar dias <= 10 Luto: validar acta_defuncion validar dias <= 5 Licencia sin goce: validar dias <= 30buscar borradores: GET Solicitud de Licencias where empleado & docstatus=0 si existe → errorbody = { empleado, tipo, fechas, documentos }crear solicitud: POST Solicitud de Licenciassi ERP responde error → retornar errorretornar éxito`

--- # 📚 Estructuras usadas ### **Solicitud de Licencias (POST)** Campos enviados: # Asignación Familiar(Buscar dni empleado (1)) - [searchJobApplicant] ## 🧾 Descripción *Este servicio consulta información de un postulante (Job Applicant) enviando su número de documento a un endpoint externo.* *El servicio actúa como un **proxy directo**: recibe un documento, llama por cURL al endpoint de EMPRESARIAL y retorna la respuesta tal cual viene de la API.* No realiza validaciones ni transformaciones adicionales. --- ## 🚀 Endpoint interno **POST /search-job-applicant** --- ## 📥 Parámetros de entrada (Request Body) ### Campo | Tipo | Obligatorio | Descripción \---|---|---|--- document | string | Sí | Número de documento del postulante a buscar. --- ## 🔐 Seguridad No usa autenticación interna ni tokens propios. El servicio simplemente reenvía el dato al endpoint: `POST {EMPRESARIAL}/api/search_job_applicant` --- ## 🧠 Flujo del Servicio (Resumen Real) 1. Recibe el campo `document` desde la solicitud. 2. Prepara una petición **cURL** hacia: 3. Envía el documento como parámetro form-data: 4. Ejecuta la llamada. 5. Decodifica la respuesta JSON. 6. Retorna la data al cliente sin modificaciones. --- ## 📤 Respuesta 200 – Ejemplo Respuesta depende totalmente del servicio externo. Un ejemplo típico puede ser: --- ## ❗ Posibles Errores ### 1. No se puede conectar con EMPRESARIAL ### 2. EMPRESARIAL devuelve error interno ### 3. Respuesta no válida o JSON corrupto --- ## 📚 Esquema esperado desde el API externo (referencial) El API no está documentado en tu código, pero normalmente una estructura de Job Applicant incluye: *La estructura real depende 100% del sistema EMPRESARIAL.* --- ## 🗃 Lógica en pseudo-código --- ## 🧩 Código documentado

`/** * Servicio: searchJobApplicant * * Descripción: * Busca información de un postulante enviando su documento al API externo EMPRESARIAL. * Este servicio actúa como un puente: manda el documento vía cURL y retorna la respuesta * sin transformaciones adicionales. * * Endpoint interno: * POST /search-job-applicant * * Parámetros: * - document (string): Documento de identidad del postulante. * * Flujo: * 1. Recibe el documento del request. * 2. Ejecuta cURL hacia EMPRESARIAL/api/search_job_applicant enviando el documento. * 3. Obtiene y decodifica la respuesta JSON. * 4. Retorna directamente la respuesta del servicio externo. * * Posibles errores: * - Fallo en la conexión cURL * - Respuesta inválida del servidor externo */public function searchJobApplicant(Request $request){ $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => EMPRESARIAL.'api/search_job_applicant', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array('document' => $request->document), )); $response = curl_exec($curl); curl_close($curl); return json_decode($response,true);}`

# Asignación Familiar(Solicitar asignacion familiar (1)) - [store] ## 🧾 Descripción Este servicio registra una **Solicitud de Asignación Familiar** para un empleado, validando previamente que: 1. Se hayan enviado las **dos imágenes del DNI** (anverso y reverso). 2. El empleado tenga un género válido y registrado. 3. No exista ya una asignación familiar duplicada para el mismo hijo (DNI del menor). 4. No existan más de dos solicitudes asociadas al mismo DNI de hijo (límite máximo permitido). El registro se almacena directamente en el ERP mediante el recurso **Solicitud Asignacion Familiar**. --- ## 🚀 Endpoint **POST** **`/solicitud-asignacion-familiar`** --- ## 📥 Request Body --- ## 🔐 Seguridad ✔ Requiere autenticación interna vía `ServiceErp()` del ERP. ✔ Se validan datos del empleado antes de crear la solicitud. --- ## 🧠 Flujo del Servicio (Resumen) 1. **Validación de archivos obligatorios** Verifica que se envíen `img_dni` y `reverso`. Si falta uno → retorna error. 2. **Obtiene datos del empleado** Usa el método `verifyEmployeeGender($empleado)` para traer: - género - fecha de ingreso real 3. **Revisa si ya existe una solicitud similar** Busca solicitudes para: - el mismo DNI del hijo - la misma fecha de ingreso del empleado 4. **Valida duplicidades según reglas** - Si existe **1 solicitud previa**, compara géneros: - Si el género coincide → ❌ ya tiene asignación familiar. - Si existen **2 solicitudes previas** → ❌ no puede registrar más. 5. **Crea la nueva solicitud** Realiza un POST hacia: `POST /resource/Solicitud Asignacion Familiar` Con los campos: 6. **Retorna respuesta final** --- ## 📤 Response 200 – Ejemplos ### ✔ Registro exitoso ### ❌ Faltan imágenes del DNI ### ❌ Asignación ya existente para el DNI del menor ### ❌ DNI ya usado en dos asignaciones previas ### ❌ Error al registrar en el ERP --- ## 📚 Schemas utilizados ### 🔹 Solicitud Asignacion Familiar (POST) ### 🔹 Solicitud Asignacion Familiar (GET/FILTER) ### 🔹 Datos del empleado (verifyEmployeeGender) --- ## 🗃 Lógica en pseudocódigo # Solicitudes de Pagos(Obtener Lista de Solicitudes (1)) - [paymentRequestList] ## 🧾 Descripción *Este servicio obtiene la **lista de solicitudes de pago** realizadas en el ERP, aplicando restricciones dependientes del usuario, su departamento y reglas de validación definidas por el área de Gerencia.* El módulo: - Valida si el usuario tiene configuraciones de **validación personalizadas** (`Validacion de Pagos Gerencia`). - Filtra solicitudes de pago según: - Estado de validación - Concepto - Montos permitidos según reglas del usuario - Solicitudes de los últimos 6 meses - Obtiene y agrupa los **archivos transados** (imágenes, documentos y archivos) asociados a cada solicitud. Si el usuario **no está autorizado**, el módulo devuelve un mensaje de bloqueo. --- # 🚀 Endpoint ### **POST /payment-request-list** --- # 📥 Request Body Ejemplo: ### Campos:

Campo	Tipo	Descripción
department	string	Departamento del usuario
concepto	string	Concepto filtrado (opcional)
usuario	string	User ID
status	string	Estado de validación (opcional). Si es vacío, se excluyen "No requiere" y "Rechazado".

--- # 🔐 Seguridad Requiere conexión válida con el ERP vía `dbErp()` y `ServiceErp()`. --- # 🧠 Flujo del Servicio (resumen funcional) ### 1️⃣ Validación de permisos del usuario Se consulta: `tabValidacion de Pagos Gerencia` Si no existe configuración para ese usuario: ### 2️⃣ Construcción de filtros principales - Se restringe a solicitudes con: - `estado_documento NOT IN ('Pago Rechazado')` - Fecha dentro de los últimos 6 meses. Si existen reglas personalizadas: - Se aplican límites de **concepto/monto** por cada configuración. - Se agregan múltiples filtros OR en el WHERE. ### 3️⃣ Filtrado por estado - Si se envía un estado explícito → búsqueda exacta. - Si no → se excluyen `"No requiere"` y `"Rechazado"`. ### 4️⃣ Filtrado por concepto Si el body incluye un concepto → se agrega un `WHERE concepto = X`. ### 5️⃣ Consulta principal Se obtiene: Desde: `tabSolicitud de Pagos` ### 6️⃣ Obtención de archivos transados Por cada solicitud encontrada se consultan los archivos: `tabArchivos Transados` Clasifica: - **Imagen** (.jpg, .jpeg, .png) - **Documento** (.pdf, .xlsx, .xls) - **Archivo** (otros) Y asigna nombres: ### 7️⃣ Construcción de la respuesta final Cada solicitud incluye: --- # 📤 Response 200 – Ejemplo exitoso

`{ "valor": true, "msn": "Lista de Solicitudes generada correctamente", "data": [ { "name": "SP-0001", "fecha": "2025-01-10", "estado": "Validado", "moneda": "PEN", "departamento": "LOGISTICA", "proveedor": "Proveedor SAC", "ruc": "20123456789", "concepto": "Transacción / Compensaciones", "monto": 1500, "numero": "F001-12345", "documento_factura": "/files/factura.pdf", "archivos_transados": [ { "name": "ARCH-001", "parent": "SP-0001", "url": "/file-download/123.jpg", "nombre_archivo": "Imagen 1" } ] } ]}`

--- # ❌ Posibles Errores ### 1️⃣ Usuario sin permisos para usar el módulo ### 2️⃣ Error al cargar solicitudes ### 3️⃣ No existen solicitudes dentro de los filtros --- # 📚 Tablas / Recursos Usados ### ✔ `tabValidacion de Pagos Gerencia` Campos usados: - usuario - concepto - monto ### ✔ `tabSolicitud de Pagos` Campos: - name, fecha, estado\_de\_validación, moneda, proveedor, ruc, concepto - monto, number\_factura, voucher ### ✔ `tabArchivos Transados` Campos: - name, url, parent --- # 🗃 Lógica en pseudo-código

`usuario_rules = GET ValidacionPagos where usuario = Xif empty(usuario_rules): return módulo inhabilitadobuild base filters: estado_documento NOT IN ('Pago Rechazado') fecha >= hoy - 6 mesesif usuario_rules exist: for each rule: add OR (concepto = rule.concepto AND monto > rule.monto)if status enviado: add estado_de_validación = Xelse: exclude ['No requiere', 'Rechazado']if concepto enviado: add concepto = Xrequests = query SolicitudPagos with filtersif no requests: return lista vacíaget archivos_transados for all requestsgroup and classify archivos by typereturn lista final con archivos agrupados`

# Solicitudes de Pagos(Obtener Combos Conceptos (1)) - [getComboSolicitudPago] 🧾 **Descripción** *Obtiene la lista de **conceptos permitidos** para un usuario específico, basándose en la tabla del ERP **"Validación de Pagos Gerencia"**.* *El servicio filtra los registros por el usuario ingresado y retorna un **array único de conceptos** asociados a dicho usuario.* *Se utiliza para validar qué tipos de pagos puede solicitar un trabajador.* --- # 🚀 Endpoint ### **POST /get-combo-solicitud-pago** --- # 📥 Request Body Debe incluir el campo: ### ❗ Validación Si **no se envía usuario**, responde: --- # 🔐 Seguridad El servicio usa el método interno `dbErp()` que requiere autenticación interna vía ERPNext. Por ello, se asume que el cliente ya cuenta con **token/credenciales válidas**. --- # 🧠 Flujo del Servicio (Explicación Real) 1. **Validar parámetro usuario** - Si está vacío → responde error de validación. 2. **Construir filtros para ERP** 3. **Consultar al ERP** Usando: con el SQL: - **SELECT** concepto - **FROM** `tabValidacion de Pagos Gerencia` - **WHERE** usuario = %(usuario)s 4. **Obtener resultados** - Se extrae la columna `concepto` de la respuesta. - Se eliminan duplicados mediante `array_unique`. 5. **Retornar los conceptos permitidos.** --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Usuario no enviado ### 2. Usuario sin conceptos asignados *(El servicio no devuelve error — solo retorna lista vacía.)* ### 3. Error del ERP Si `dbErp()` falla internamente, el servicio responderá una lista vacía debido a su estructura actual. --- # 📚 Tablas y Estructuras Usadas ### Tabla: `tabValidacion de Pagos Gerencia` **Campos utilizados:** --- # 🗃 Lógica en Pseudocódigo # Solicitudes de Pagos(Validar Solicitud (1)) - [validatePaymentRequest] ## 🧾 Descripción *Servicio encargado de **validar o rechazar** una Solicitud de Pagos en el ERP.* *Actualiza el campo **estado\_de\_validación** del documento Solicitud de Pagos y devuelve una respuesta indicando si la operación fue exitosa.* *El servicio no procesa lógica adicional más allá de actualizar el estado del documento y devolver el resultado.* --- ## 🚀 Endpoint ### **PUT /validate-payment-request** 📩 **Recibe parámetros mediante el body del Request (Laravel Request)**: --- ## 🔐 Seguridad Requiere autenticación contra el ERP, manejada internamente mediante: `$this->general->ServiceErp()` No requiere headers adicionales desde el lado del cliente. --- ## 🧠 Flujo del Servicio (explicación real) 1. Recibe: - **name** → ID del documento (*Solicitud de Pagos*) - **status** → Puede ser `"Validado"` o `"Rechazado"` 2. Determina internamente mensajes para usuario según status: - `"Validado"` → aprobar - `"Rechazado"` → rechazar 3. Construye el body con el nuevo estado: 4. Envía: 5. Si el ERP responde con error → devuelve mensaje indicando fallo al aprobar o rechazar. 6. Si la operación es correcta → responde con: - valor = true - mensaje: "Solicitud de Pago Aprobado/Rechazado correctamente" - data → respuesta del ERP --- ## 📥 Request Body (Laravel) --- ## 📤 Response 200 – Ejemplo (Aprobado) ### Ejemplo (Rechazado) --- ## ❗ Posibles Errores ### 1. Error durante el PUT ### 2. El ERP responde con "valor = false" ### 3. Excepción inesperada --- ## 📚 Schema del documento afectado ### Solicitud de Pagos (PUT) Campos utilizados: `{ "estado_de_validación": "string"}` --- ## 🗃 Lógica en pseudo-código # Cambio Salarial Administrativo(Empleados Activos (1)) - [getEmployeeActive] ## 🧾 Descripción Servicio que obtiene el listado completo de **empleados activos** desde el ERP. Solo devuelve empleados cuyo `status = "active"` y expone información básica: - `nombre_completo` - `passport_number` (DNI u otro documento) - `name` (ID interno del empleado) Este servicio se utiliza para obtener la lista de empleados habilitados dentro del sistema. --- ## 🚀 Endpoint **POST /get-employee-active** 📌 *El método es POST, pero internamente realiza una consulta GET al ERP.* --- ## 📥 Request Body El servicio **no requiere parámetros en el body**. Todo se obtiene directamente del ERP mediante `ServiceErp()`. --- ## 🔐 Seguridad Requiere conexión autorizada al ERP. La autenticación se maneja internamente mediante: `$this->general->ServiceErp(...)` --- ## 🧠 Flujo del Servicio (Resumen Real) 1. Construye la solicitud hacia el ERP: 2. Envía la solicitud al ERP mediante:

`$this->general->ServiceErp('GET', null, $body, APICAPACITACION . 'resource/Employee');`

3. Verifica: - Si el ERP respondió con error. - Si no existen registros de empleados activos. 4. En caso de éxito: - Devuelve la lista completa de empleados encontrados. --- ## 📤 Response 200 – Ejemplo ### ✅ Caso exitoso ### ❗ Error interno del ERP ### ❗ Sin registros encontrados --- ## ❗ Posibles Errores ### 1. Error en la llamada al ERP Ocurre cuando `ServiceErp()` devuelve `valor = false`. ### 2. No existen empleados activos ### 3. Error inesperado del servidor *(si se implementara un try/catch)* --- ## 📚 Schemas utilizados ### Employee (GET) Campos usados: --- ## 🗃 Lógica en Pseudo-Código

`body = { limit = none fields = ["nombre_completo","passport_number","name"] filters = [["status","=","active"]]}response = GET ERP Employee with bodyif response.valor == false: return errorif response.data.count == 0: return "No se encontraron registros"return { valor: true, msn: "Busqueda Existosa", data: response.data}`

# Cambio Salarial Administrativo(Obtener Salario (1)) - [getEmployeeActive] ### 🧾 Descripción Este servicio obtiene **todos los empleados activos** desde el ERP, retornando únicamente la información básica necesaria para listarlos: - **nombre\_completo** - **passport\_number** - **name** (ID interno del empleado) Es un servicio de consulta que solo consume los datos de la API del ERP usando `ServiceErp()`. --- # 🚀 Endpoint **GET /get-employee-active** No recibe parámetros en el body; todo se obtiene del ERP. --- # 🔐 Seguridad Requiere autenticación válida hacia el ERP (manejada internamente por `ServiceErp()`). --- # 🧠 Flujo del Servicio (Resumen Real) 1. Construye el body de consulta para el ERP: 2. Realiza el request: `GET Employee` 3. Valida: - Si hubo error en el ERP → retorna error. - Si la respuesta está vacía → retorna mensaje "No se encontraron registros". 4. Si hay resultados, retorna: - valor = true - msn = "Busqueda Exitosa" - data = lista de empleados activos --- # 📥 Request Body Este endpoint **no recibe body**. --- # 📤 Response 200 – Ejemplo ### ✔️ Con empleados encontrados ### ❗ Sin registros ### ❌ Error interno --- # ❗ Posibles Errores ### 1️⃣ Error del ERP Ocurre cuando `ServiceErp()` retorna `"valor" => false` --- ### 2️⃣ No hay registros activos --- ### 3️⃣ Error inesperado en servidor --- # 📚 Schemas Usados ## 📄 Employee (GET) Campos utilizados: --- # 🗃 Lógica en Pseudo-código

`body = { limit: none fields: ["nombre_completo", "passport_number", "name"] filters: [["status","=","active"]]}response = GET ERP Employeeif response.valor == false: return errorif response.data is empty: return no registrosreturn { valor: true msn: "Busqueda Exitosa" data: response.data}`

# Cambio Salarial Administrativo(Actualizar Salario (1)) - [updateSalarialbyEmployee] ## 🧾 Descripción Este servicio registra una **solicitud de actualización salarial** para un empleado. Envía al ERP los nuevos valores de: - Sueldo - Movilidad - Bono nocturno - Fecha de actualización *El servicio **solo valida la estructura y los datos requeridos**, mientras que el proceso interno de aprobación o registro es manejado por el ERP a través del recurso **Cambio Salarial Administrativo**.* --- ## 🚀 Endpoint **POST** **`/update-salarial-by-employee`** --- ## 📥 Request Body (JSON) Todos los campos son **obligatorios**.

Campo	Tipo	Descripción
empleado	string	ID del empleado
sueldo	number	Nuevo sueldo propuesto
movilidad	number	Nuevo monto de movilidad
bono\_nocturno	number	Monto de bono nocturno
fecha	string (YYYY-MM-DD)	Fecha de aplicación del cambio salarial

### Ejemplo de entrada --- ## 🔐 Seguridad Requiere token válido del ERP (interno), administrado desde: --- ## 🧠 Flujo del Servicio (resumen real) 1. **Valida que se hayan enviado todos los campos requeridos.** Si falta alguno, retorna error. 2. **Valida formato de fecha** usando `validateDate()`. 3. **Construye el body** que será enviado al ERP: 4. **Envía la solicitud al ERP**: `POST resource/Cambio Salarial Administrativo` 5. **Devuelve al cliente el resultado**, incluyendo la respuesta del ERP. --- ## 📤 Response 200 – Ejemplo exitoso --- ## ❗ Posibles Errores ### 1. Campos faltantes ### 2. Empleado vacío ### 3. Sueldo vacío ### 4. Movilidad vacío ### 5. Bono nocturno vacío ### 6. Fecha inválida --- ## 📚 Schemas ### Cambio Salarial Administrativo (ERP) Body enviado: --- ## 🗃 Lógica en Pseudocódigo # Cambio de Sistema Pensionario(Sistema de Pension Combos (1)) - [combos] ## 🧾 Descripción *Este servicio retorna un conjunto de listas predefinidas utilizadas en la aplicación móvil, específicamente los **tipos de AFP** disponibles para selección en formularios o procesos del sistema.* *No realiza consultas a base de datos ni al ERP; solo devuelve información estática utilizada para poblar combos (selects) en la interfaz.* *Es un servicio simple y de uso general dentro del módulo de onboarding o actualización de datos personales.* --- ## 🚀 Endpoint **POST /combos** Este servicio **no requiere parámetros** en el body ni en la URL. --- ## 🔐 Seguridad Utiliza el flujo regular del controlador. No solicita autenticación directa dentro de la función, pero su acceso depende de la configuración del backend (middleware del módulo). No realiza llamadas externas al ERP. --- ## 🧠 Flujo del Servicio (resumen real) 1. Define internamente una lista fija con los tipos de AFP: - AFP Habitat - AFP Profuturo - AFP Prima - AFP Integra 2. Organiza los datos dentro de un arreglo asociado a la clave `"tipos_afp"`. 3. Retorna un JSON con: - `valor: true` - `data: { "tipos_afp": [...] }` --- ## 📥 Request Body Este servicio **no recibe parámetros**. --- ## 📤 Response 200 – Ejemplo --- ## ❗ Posibles Errores Este servicio **no genera errores**, dado que devuelve datos estáticos. Sin embargo, errores genéricos podrían producirse por: 1. **Error interno del servidor** --- ## 📚 Schemas usados ### **Respuesta del servicio** --- ## 🗃 Lógica en pseudo-código # Cambio de Sistema Pensionario(Enviar solicitud cambio AFP (1)) - [store] ## 🧾 Descripción Este servicio registra una **solicitud de cambio de sistema pensionario** para un empleado, validando previamente: - Que el empleado exista. - Que el sistema pensionario seleccionado sea válido (ONP o AFP). - Que el tipo de AFP sea correcto cuando corresponda. - Que no se intente cambiar al mismo sistema actual. - Regla especial: si el empleado está en **ONP**, solo puede migrar a **AFP Integra**. - Que no exista un documento previo en estado “Borrador”. - Validación de estructura del **CUSPP** cuando aplica. El servicio crea un nuevo documento en el ERP: `Solicitud de Cambio de Sistema Pensionario` --- # 🚀 Endpoint **POST** `/cambio-sistema-pensionario/store` --- # 🔐 Seguridad - Requiere autenticación interna vía `ServiceErp()`. - Solo accesible desde el backend con credenciales del ERP. --- # 🧠 Flujo del Servicio (resumen real) ### 1. Validación de parámetros El servicio valida: - `empleado` obligatorio. - `sistema_pensionario` debe ser `AFP` u `ONP`. - Si es AFP → validar AFP válida. - `tipo_cambio` debe estar dentro de: - `"ENTRE AFP"` - `"DE ONP A AFP"` - `"DE AFP A ONP"` ### 2. Trae los datos del empleado Si el empleado no existe → error. ### 3. Determina si el cambio es permitido Reglas del negocio: - No puede cambiar al mismo sistema. - Si está en ONP, solo puede pasar a AFP Integra. - Cuando el cambio involucra AFP, se valida el **CUSPP**: - Longitud 12 - Primeros 6 caracteres numéricos - Último caracter numérico ### 4. Verifica si ya existe una solicitud "Borrador" Consulta a la base ERP: Si existe una, retorna error. ### 5. Crea la solicitud de cambio

`POST resource/Solicitud de Cambio de Sistema Pensionario{ "id_empleado": , "sistema_pensionario": "AFP"|"ONP", "tipo_de_afp": "...", "tipo_cambio": "...", "cuspp": "..." // cuando aplica}`

--- # 📥 Request Body (ejemplo) --- # 📤 Response 200 – Ejemplo ### ✔ Cambio enviado correctamente ### ❌ Tipo de cambio inválido ### ❌ Ya existe solicitud en borrador ### ❌ No puede cambiar al mismo sistema ### ❌ Error al crear solicitud --- # 📚 Validaciones importantes del servicio ### ✔ Validación de CUSPP - Debe medir 12 caracteres. - Primeros 6 numéricos. - Último carácter numérico. ### ✔ Validación de sistema pensionario - Solo **AFP** o **ONP**. - Tipos válidos AFP: `"AFP Habitat","AFP Profuturo","AFP Prima","AFP Integra"`. ### ✔ Regla especial ONP → AFP Si el empleado está en ONP, solo puede migrar a AFP Integra: --- # 🗃 Lógica en pseudo-código # Módulo Centro de Ayuda # Denuncias(Consultar Sucursal (1,2)) - [getBranchsDesignations] 🧾 **Descripción** Servicio que obtiene dinámicamente: - **La lista de sucursales activas con más de 1 empleado asignado**, o - **La lista de puestos (Designations)** disponibles en el ERP, dependiendo del parámetro `type` recibido en la solicitud. Este servicio consulta directamente al ERP mediante los métodos internos `dbErp()` y `ServiceErp()`. --- # 🚀 **Endpoint** **POST** `/get-branchs-designations` --- # 📥 **Request Body** ### Valores permitidos:

type	Acción
`"Sucursal"`	Retorna sucursales con empleados asociados.
`"Puesto"`	Retorna todos los puestos (Designation).

--- # 🔐 **Seguridad** - Requiere autenticación interna del ERP. - Las consultas se realizan vía `dbErp()` (SQL ERPNext) o `ServiceErp()` (REST del ERP). --- # 🧠 **Flujo del Servicio** ## ✔️ Si type = `"Sucursal"` 1. Construye la consulta SQL: - Selecciona sucursales (`tabBranch`). - Hace JOIN con empleados (`tabEmployee`). - Agrupa y retorna solo sucursales con **más de 1 empleado registrado**. 2. Ejecuta la consulta vía: 3. Si encuentra resultados: - Devuelve solo el nombre de la sucursal (`br.name`). 4. Si ocurre error: - Retorna mensaje de error controlado. --- ## ✔️ Si type = `"Puesto"` 1. Solicita al ERP la lista completa de Designations: 2. Extrae solo el nombre del puesto (`name`). 3. Devuelve la lista al cliente. --- ## ❌ Si type ≠ “Sucursal” ni “Puesto” Retorna error indicando que la opción no es válida. --- # 📤 **Response 200 – Ejemplos** ## ✔️ Respuesta para type = `"Sucursal"` ## ✔️ Respuesta para type = `"Puesto"` ## ❌ Opción no válida ## ❌ Error del servidor --- # 📚 **Schemas que utiliza** ### **Branch (SQL ERP)** Campos relevantes: ### **Employee** Relacionada solo para contar empleados por sucursal: ### **Designation** Campos relevantes: --- # 🗃 **Lógica en Pseudocódigo** # Denuncias(Crear demanda (1)) - [store] ## 🧾 Descripción *Este servicio crea un registro oficial de una **denuncia interna** realizada por un colaborador o usuario del sistema.* *Permite registrar denuncias anónimas o identificadas, incluir detalles del hecho, denunciados, fechas, archivos adjuntos y otros campos relevantes.* La información se almacena directamente en el ERP, creando un nuevo documento del tipo: Incluye reglas de validación para asegurar que los datos enviados cumplan los requisitos mínimos según la normativa interna del área de cumplimiento. --- ## 🚀 Endpoint **POST** `/denuncias/store` --- ## 🔐 Seguridad Requiere autenticación interna: - La creación se realiza vía `ServiceErp()`, que requiere un token válido del ERP. - No se permiten denuncias sin validar los campos obligatorios. --- ## 🧠 Flujo del Servicio (Resumen Real) 1. **Lee parámetros del request:** - Identificación del denunciante - Datos de contacto (si aplica) - Motivo de denuncia - Fechas del hecho - Sucursal - Denunciados (en JSON) - Archivo adjunto - Otros detalles relacionados 2. **Valida que el JSON de denunciados sea correcto.** 3. **Ejecuta múltiples validaciones obligatorias:** - Si se identifica → celular y correo son obligatorios. - Campos `motivo`, `sucursal`, `desde`, `hasta`, `detalle` deben existir. - Si conoce involucrados → mínimo 1 y máximo 3 denunciados. - Cada denunciado debe tener nombre, sucursal y área. 4. **Valida y arma estructura del archivo adjunto** si se envía. 5. **Genera un código aleatorio único** que identificará la denuncia. 6. **Crea el documento Denuncias en el ERP:** 7. **Guarda los denunciados como tabla hija (table\_16).** 8. **Devuelve confirmación y el código de seguimiento.** --- ## 📥 Request Body (Ejemplo) --- ## 🧪 Validaciones Importantes

Campo	Requerido	Condición
identificar	Sí	Debe ser 0 o 1
celular, correo	Obligatorios si identificar = 1	—
motivo	Sí	—
sucursal	Sí	—
continua\_ocurriendo	Sí	Debe ser 0 o 1
desde / hasta	Sí	Fechas del hecho
conoce\_involucrados	Sí	0 o 1
denunciados	Condicional	1 a 3 registros si conoce\_involucrados = 1
detalle	Sí	—

Si el archivo existe, se formatea a: `https://fileserver.shalomcontrol.com/file-view/` --- ## 📤 Response 200 – Ejemplo exitoso --- ## ❗ Posibles Errores ### 1. JSON malformado en denunciados ### 2. Campos obligatorios faltantes ### 3. Número incorrecto de denunciados ### 4. Error al registrar en el ERP ### 5. Error inesperado del servidor --- ## 📚 Esquema del DocType Denuncias (Campos usados) --- ## 🗃 Lógica en Pseudocódigo # Denuncias(Url Demanda PDF (1)) - [pdf] ## 🧾 Descripción *Este servicio obtiene la información completa de una denuncia registrada en el ERP (Frappe/ERPNext), validando primero que exista una denuncia cuyo **código aleatorio** coincida con el parámetro enviado.* Una vez encontrada: 1. Obtiene la información principal de la denuncia. 2. Consulta nuevamente la denuncia para traer sus tablas hijas (por ejemplo table\_16). 3. Construye un array final con los datos completos. 4. Genera un **PDF oficial de la denuncia** usando una plantilla Blade. 5. Retorna el archivo descargable **Demanda.pdf**. Este servicio se utiliza para permitir a los usuarios descargar un reporte o constancia oficial de la denuncia registrada. --- ## 🚀 Endpoint **GET /pdf/{codigo}** 📌 *El parámetro `{codigo}` corresponde al campo `codigo_aleatorio` de la denuncia.* --- ## 📥 Parámetros ### URL Params

Parámetro	Tipo	Obligatorio	Descripción
`codigo`	string	✔	Código aleatorio que identifica la denuncia

📌 *No recibe parámetros en el body.* --- ## 🔐 Seguridad El servicio realiza llamadas internas al ERP a través de **ServiceErp()**, por lo que requiere autenticación válida configurada internamente. No necesita token desde el cliente. --- ## 🧠 Flujo del Servicio (Resumen real) ### 1️⃣ Buscar denuncia por código aleatorio Realiza un GET al recurso: `GET Denuncias?filters=[["codigo_aleatorio","=",]]` Si no encuentra coincidencias → retorna error. --- ### 2️⃣ Para cada denuncia encontrada Hace un GET para traer la información completa del documento con sus tablas hijas: `GET Denuncias/{name}` Guarda el contenido de la tabla `table_16` y arma un arreglo final. --- ### 3️⃣ Generar el PDF Usa: `PDF::loadView("pdf/demanda", ["data" => $demandas_final[0]])` Lo genera en tamaño **A5**, orientación **portrait**, y lo retorna como descarga: `Demanda.pdf` --- ## 📤 Response – Ejemplo exitoso (PDF descargable) El navegador descargará directamente: `Demanda.pdf` Con el contenido renderizado desde la vista `pdf/demanda.blade.php`. --- ## ❗ Posibles Errores ### 1. No existe la denuncia ### 2. Error consultando el ERP ### 3. La denuncia existe, pero falla la obtención completa (No rompe el flujo; simplemente ignora la denuncia afectada.) --- ## 📚 Schemas utilizados ### Denuncias (GET) Campos utilizados: ### PDF Output Basado en la vista: `resources/views/pdf/demanda.blade.php` --- ## 🗃 Lógica en Pseudo-código

`body = { filters: [["codigo_aleatorio", "=", codigo]], fields: ["*"]}demandas = GET Denuncias WHERE codigo_aleatorio=codigoif demandas is empty: return errorforeach denuncia in demandas: detalle = GET Denuncias/{name} agregar table_16 al resultado finalgenerar PDF usando vista "pdf/demanda"retornar archivo: Demanda.pdf`

# Denuncias(Consultar demanda (1)) - [obtener] ### 🧾 Descripción Permite **consultar una denuncia registrada** en el ERP usando un **código aleatorio** como identificador de búsqueda. El servicio: - Recibe un código único (`codigo`) enviado al usuario. - Busca en el ERP la denuncia asociada. - Retorna sus datos principales (estado, creación, fechas de proceso, archivo adjunto, etc.) - Ajusta la URL del archivo si existe. Es un servicio utilizado para que un usuario pueda revisar: - El estado de su denuncia, - La respuesta del área responsable, - Y descargar el archivo asociado (si lo tiene). --- # 🚀 Endpoint ### **POST /obtener** --- # 📥 Request Body ### Parámetros

Campo	Tipo	Obligatorio	Descripción
codigo	string	✔️ Sí	Código aleatorio generado al registrar la denuncia

--- # 🔐 Seguridad Requiere autenticación interna mediante `$this->general->ServiceErp()` (usa cookies o token ya configurado en el backend). --- # 🧠 Flujo del Servicio (resumen real) 1. **Obtiene el código** enviado en el request. 2. Construye el body para consultar la denuncia en el ERP: - fields: name, creation, estado\_denuncias, fechas, archivo, respuesta. - filters: `[["codigo_aleatorio","=", $codigo]]` 3. Llama al ERP: `GET resource/Denuncias` 4. Si **no existe denuncia**, retorna error. 5. Si existe: - Verifica si `archivo_denuncia` no está vacío. - Si tiene archivo, le agrega la URL base del servidor. 6. Retorna toda la información encontrada. --- # 📤 Response 200 – Ejemplo exitoso --- # ❗ Posibles Errores ### 1️⃣ Denuncia no encontrada ### 2️⃣ Error en la comunicación con el ERP ### 3️⃣ Respuesta vacía del ERP --- # 📚 Esquema utilizado (Denuncias – GET) Campos usados: --- # 🗃 Lógica en pseudo-código # Módulo Convocatorias # Lista de convocatorias internas (1) - [getInternalCalls] 🧾 **Descripción** *Obtiene todas las **convocatorias internas vigentes** dentro del ERP, incluyendo información del puesto, sede y su archivo adjunto (PDF u otro documento del Job Opening).* El servicio cruza información entre: - **Job Opening** - **File** (archivos adjuntos al Job Opening) Solo trae convocatorias internas **activas (status = "Open")** y marcadas como **convocatoria interna = 1**. --- # 🚀 Endpoint **GET /get-internal-calls** > No recibe parámetros. > Toda la información se obtiene mediante apiService() hacia el ERP. --- # 🔐 Seguridad Requiere conexión autorizada vía `apiService()`, usando token interno del ERP. --- # 🧠 Flujo del Servicio (Resumen) 1. **Obtener todos los Job Openings internos activos** 2. **Obtener todos los archivos relacionados al Job Opening** 3. Si alguno de los endpoints devuelve error, se retorna: 4. Si no hay convocatorias abiertas: 5. Para cada convocatoria se agrega: - La descripción de la sede: `"PARA LA SEDE {sucursal}"` - El archivo correspondiente (`file_url`), si existe. 6. Se retorna listado de convocatorias internas enriquecidas. --- # 📥 Request Body No tiene body. --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Error en consulta de Job Opening ### 2. Error en consulta de archivos File ### 3. No existen convocatorias internas activas ### 4. Error inesperado del servidor --- # 📚 Esquemas (estructuras utilizadas) ### Job Opening Campos usados: ### File Campos usados: --- # 🗃 Pseudo-código de la lógica # Obtiene combos (1) - [combosJobApplicant] 🧾 **Descripción** *Este servicio obtiene y devuelve todos los combos (listas de valores) necesarios para el registro o postulación de un **Job Applicant** (Postulante) dentro del sistema.* *Los datos se obtienen directamente desde el ERP mediante el método interno `getCombo()`, que consulta tablas maestras como Country, Branch, Department y Gender.* *Además, incluye una lista estática de tipos de documentos admitidos (DNI, Pasaporte, Carnet de Extranjería)*. --- # 🚀 Endpoint **GET /combos-job-applicant** No requiere parámetros. --- # 🔐 Seguridad Requiere autenticación válida en la API del ERP, ya que las consultas internas se realizan mediante: `$this->getCombo("")` --- # 🧠 Flujo del Servicio (resumen real) 1. Inicializa un arreglo vacío `$combo`. 2. Obtiene desde el ERP las siguientes listas: - Países → Doctype: `Country` - Sucursales → Doctype: `Branch` - Departamentos → Doctype: `Department` - Género → Doctype: `Gender` 3. Agrega una lista fija de tipos de documentos: 4. Retorna la estructura completa con todos los combos. 5. En caso de error, devuelve una respuesta controlada. --- # 📥 Request Body Este servicio **no recibe body**, ni parámetros. --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Error de ejecución o conexión con el ERP --- # 📚 Schemas (estructuras usadas) ### Resultado de getCombo() El servicio asume que `getCombo()` devuelve una estructura similar a: ### Lista fija de tipos de documentos: --- # 🗃 Lógica en pseudo-código # Aplicar convocatoria (1) - [setJobApplicantPerApp] ## 🧾 Descripción Registra una nueva **solicitud de postulación (Job Applicant)** desde la aplicación móvil, validando previamente: - Que el usuario autenticado no tenga ya una solicitud creada para el mismo puesto. - Que exista un empleado vinculado al email de sesión. - Que los campos obligatorios del formulario estén correctamente enviados. - Que la información personal del empleado se complemente para generar el registro. Este servicio crea un documento `Job Applicant` en el ERP y también registra un `Error Log` con la data enviada al ERP (para auditoría). --- ## 🚀 Endpoint **POST /set-job-applicant-per-app** --- ## 📥 Parámetros requeridos (Request Body) --- ## 🔐 Seguridad - Requiere usuario autenticado en la app. - La comunicación con el ERP se realiza mediante `apiService()`. - No requiere token específico del usuario final, es un servicio interno controlado. --- ## 🧠 Flujo del Servicio (Explicación Detallada) ### 1️⃣ Validaciones iniciales - Verifica que exista `email_logued`. - Verifica que el email del formulario (`email_id`) sea válido y contenga “@”. - Valida campos obligatorios: dirección, documentos, sucursal, CV, grado de instrucción, job\_title. ### 2️⃣ Verifica si ya existe una postulación previa Consulta en el ERP: Si ya existe un registro → **retorna error**. ### 3️⃣ Obtiene datos del empleado Busca el empleado vinculado al email logueado: Si no existe → **retorna error**. ### 4️⃣ Calcula la edad del postulante Usando la fecha de nacimiento del empleado mediante `DateTime::diff`. ### 5️⃣ Construye el cuerpo del nuevo Job Applicant Incluye: - Datos del empleado (nombres, apellidos, género, fecha de nacimiento, DNI, nacionalidad). - Datos enviados desde la app (CV, copia de documento, email, sucursal, carrera, etc.). - Estado inicial del proceso: `"status": "Open"` - Email logueado para relacionarlo a la cuenta APP. ### 6️⃣ Crea el registro Job Applicant

`POST Job ApplicantBODY: { ...data }`

### 7️⃣ Registra error interno en Error Log (auditoría) La respuesta del ERP se envía también a: `POST Error Log` ### 8️⃣ Retorna la respuesta al cliente Si se creó correctamente: Si falló: --- ## 📤 Respuesta 200 – Ejemplo (Éxito) ## ❌ Respuesta 200 – Ejemplo (Error) --- ## ❗ Posibles Errores Comunes ### 1. Falta email\_logued ### 2. Email sin “@” ### 3. Empleado no existe ### 4. Solicitud duplicada ### 5. Error al crear Job Applicant --- ## 🗃 Estructuras usadas (Schemas) ### ▶ Employee (GET) Campos consultados: ### ▶ Job Applicant (POST) Campos enviados: --- ## 🧩 Pseudocódigo del Servicio # Módulo Documentos Internos # Lista de categorias - documentos (1) - [getInternalDocuments] ## 🧾 Descripción Obtiene **todos los documentos internos del ERP**, los agrupa por categoría y devuelve cuáles corresponden a un puesto específico (si aplica). Este servicio combina información procedente de: - `tabDocumentos Internos` - `tabDocumentos especificos` (relación hijo por puesto) También determina dinámicamente qué archivo debe adjuntarse para la categoría **IPERC**, según el puesto del trabajador. 📌 **Es un servicio de consulta sin paginación.** 📌 **No requiere parámetros en el body (solo el parámetro $puesto en la URL).** --- # 🚀 Endpoint ### **GET /internal-documents/{puesto}** - `{puesto}` → Nombre del puesto (Designation). - Si no se envía o es null, el servicio igualmente devolverá las categorías, pero sin personalizar la categoría IPERC. --- # 🔐 Seguridad Requiere autenticación válida vía `dbErp` usando el token del ERP. El servicio accede directamente a vistas y tablas internas del ERP. --- # 🧠 Flujo del Servicio ### **1. Consulta documentos internos** Ejecuta la sentencia SQL: Si falla la consulta → devuelve error 500 del servicio. --- ### **2. Normaliza categorías** Si un documento no tiene categoría, se asigna por defecto: `categoria = "POLITICAS"` --- ### **3. Agrupa documentos por categoría** Genera una estructura como: --- ### **4. Caso especial: categoría IPERC** Para IPERC: - Se toma el adjunto por defecto → `campo_para_adjuntar` - Si el puesto recibido coincide con algún registro hijo (`tabDocumentos especificos`) → se usa el archivo personalizado (`adjuntar`) Ejemplo lógica: --- ### **5. Construye la respuesta final** La respuesta incluye: - Lista de categorías - Lista agrupada con sus documentos y el archivo a adjuntar según la lógica --- # 📤 Response 200 – Ejemplo Real

`{ "valor": true, "msn": "Lista de categorias generado correctamente", "data": { "categorias": [ "POLITICAS", "IPERC", "MOF" ], "categorias_registro": { "POLITICAS": [ { "name": "DOC-001", "nombre_del_archivo": "reglamento_interno.pdf", "campo_para_adjuntar": "/files/reglamento_interno.pdf" } ], "IPERC": [ { "name": "IPERC-001", "nombre_del_archivo": "iperc_almacen.pdf", "campo_para_adjuntar": "/files/iperc_almacen.pdf" } ] } }}`

--- # ❗ Posibles errores ### **1. Error de servicio ERP** ### **2. Error interno** --- # 📚 Estructuras de datos utilizadas ### **Documentos Internos (`tabDocumentos Internos`)** Campos utilizados: ### **Documentos Específicos (`tabDocumentos especificos`)** Campos utilizados: --- # 🗃 Pseudocódigo del servicio # Guardar documento (1) - [saveInternalDocuments] ## 🧾 Descripción *Registra internamente un documento aceptado o gestionado por un usuario dentro de una terminal específica.* Este servicio guarda un log en la tabla **documentos\_internos**, permitiendo rastrear: - Qué usuario aceptó o gestionó un documento. - Desde qué terminal lo realizó. - Qué tipo de documento fue. - En qué fecha y hora se registró. Es utilizado para auditoría y trazabilidad dentro del sistema. --- # 🚀 Endpoint **POST** `/save-internal-documents` --- # 📥 Parámetros (Request Body) ### Campos:

Campo	Tipo	Requerido	Descripción
usuario	string	✔️ Sí	ID o username del usuario que realiza la acción
terminal	string	✔️ Sí	Código de la terminal donde se ejecuta la acción
tipo	string	❌ No	Tipo de documento o acción registrada

--- # 🔐 Seguridad No requiere token de ERP. Acceso interno del backend usando conexión directa a la base de datos **mysql2**. --- # 🧠 Flujo del Servicio (resumen) 1. Valida que **usuario** y **terminal** existan en la solicitud. 2. Establece zona horaria **America/Lima**. 3. Inserta un registro en la tabla `documentos_internos` con: - usuario - terminal - tipo - fecha actual 4. Si el registro falla, retorna un error. 5. Si todo es exitoso, responde confirmación de inserción. --- # 🗃 Base de Datos Utilizada **Tabla:** `documentos_internos` (BD: mysql2)

Campo	Tipo	Descripción
usuario	varchar	Usuario que registra
terminal	varchar	Terminal desde donde registra
tipo	varchar	Tipo de documento
fecha	datetime	Fecha y hora del registro

--- # 🔎 Pseudocódigo --- # 📤 Respuestas del Servicio ### ✅ **200 – Inserción exitosa** --- ### ❗ Error: Falta usuario --- ### ❗ Error: Falta terminal --- ### ❗ Error al insertar --- # 📚 Ejemplo completo de Request # Examen Medico (1) - [obtain] ## 🧾 Descripción *Este servicio permite **consultar los resultados del examen EMO** (Evaluación Médica Ocupacional) de un empleado utilizando su **DNI (passport\_number)**.* *El servicio valida que el DNI haya sido enviado, busca la información correspondiente mediante el método interno `getExamenEmo()` y retorna los resultados si existen.* *Es un servicio de consulta rápida y directa.* --- ## 🚀 Endpoint ### **POST /obtain** --- ## 📥 Request Body ### Campos:

Campo	Tipo	Obligatorio	Descripción
passport\_number	string	✔️	DNI del empleado para consultar su examen EMO

--- ## 🔐 Seguridad Este servicio **no requiere autenticación externa**, pero su funcionamiento depende de un método interno: - `getExamenEmo(passport_number)` → Consulta la información del examen EMO. --- ## 🧠 Flujo del Servicio (Explicación) 1. **Validación inicial del DNI** - Si el parámetro `passport_number` no está presente, el servicio responde con error. 2. **Consulta del examen EMO** - Se llama al método interno `getExamenEmo($passport_number)`. 3. **Validación del resultado** - Si el método no retorna datos, se responde con un mensaje indicando que no se encontraron resultados. 4. **Respuesta exitosa** - Si sí existen resultados, se retorna el contenido del examen EMO. --- ## 📤 Response 200 – Ejemplos ### ✔️ Caso exitoso --- ### ❗ Error: DNI no enviado --- ### ❗ Error: Sin resultados EMO --- ## ❗ Posibles Errores

Código	Motivo	Descripción
400	DNI faltante	No se envió el `passport_number`
404	Sin resultados	El empleado no tiene examen EMO registrado
500	Error en método interno	Fallo en `getExamenEmo()`

--- ## 📚 Schemas ### **Request Schema** ### **Response Schema (éxito)** ### **Response Schema (error)** --- ## 🗃 Lógica en pseudocódigo # Módulo QR # Verificar QR (1) - [verifyQR] ### 🧾 Descripción Este servicio permite **validar si un empleado tiene permitido registrarse** (por ejemplo, marcar asistencia) **en función del último escaneo de QR del bus** registrado en el ERP. La lógica se basa en verificar si el empleado escaneó su QR dentro de las **últimas 4 horas (14400 segundos)**. El servicio consulta la tabla: - `Registro de Escaneres de Bus` - `Tabla Lista Blanca` Mediante `dbErp()` para obtener el escaneo más reciente disponible. --- # 🚀 Endpoint ### **POST /verify-qr** --- # 📥 Request Body (Ejemplo) ### Parámetros

Campo	Tipo	Obligatorio	Descripción
employee	string	✔️	Código de empleado a validar

--- # 🔐 Seguridad El servicio usa comunicación interna con ERP mediante: - `dbErp()` - Autenticación interna utilizando cookies o token del ERP. No requiere autenticación adicional desde el cliente. --- # 🧠 Flujo del Servicio (Explicación real) 1. **Validación inicial del parámetro** - Si `employee` está vacío → se devuelve error. 2. **Consulta del último escaneo registrado en ERP** Se ejecuta: 3. **Si no existen registros** - Se retorna mensaje indicando que no se encontró escaneo. 4. **Cálculo de la diferencia de tiempo** Se obtiene el tiempo transcurrido entre: - Fecha del escaneo (`fecha`) - Fecha actual Se obtiene con: 5. **Aplicación de la regla de validación** - Si la diferencia es **menor a 4 horas (14400 segundos)** → **permitido** - Si es mayor → **denegado** 6. **Manejo de excepciones** Si ocurre un error interno, se retorna el mensaje de error. --- # 📤 Response 200 – Ejemplos ### ✔️ Caso permitido (último escaneo dentro de 4 horas) --- ### ✔️ Caso denegado (más de 4 horas sin escanear) --- ### ❌ No existe escaneo asociado al empleado --- ### ❌ Parámetro inválido --- ### ❌ Error interno --- # 📚 Schemas utilizados ### **Registro de Escaneres de Bus (consulta)** Campos consultados: --- # 🗃 Lógica en Pseudo-código # Leer QR (1) - [leerCodigoQR] ## 🧾 Descripción Este servicio valida un **código QR de acceso a buses internos** y determina si un empleado puede registrar un nuevo escaneo. El flujo consulta los registros previos, controla tiempos de reescaneo (mínimo 4 horas) y registra un nuevo ingreso si corresponde. El servicio interactúa con: - **Tabla “Registro de Escaneres de Bus”** (documento principal con el QR) - **Tabla “Tabla Lista Blanca”** (registros de escaneo por empleado) - **ERP vía dbErp() y ServiceErp()** - **Carbon** para manejo de fechas --- ## 🚀 Endpoint **POST** `/leer-codigo-qr` --- ## 📥 Request Body ### Parámetros

Campo	Tipo	Obligatorio	Descripción
qr	string	✔️	Código QR escaneado
employee	string	✔️	Código del empleado que intenta registrar el escaneo

--- ## 🔐 Seguridad Requiere autenticación interna del ERP (vía `dbErp()` y `ServiceErp()`). --- ## 🧠 Flujo del Servicio (resumen real) ### 1️⃣ Validaciones iniciales - El QR no puede venir vacío - El código de empleado tampoco Si falla, retorna error inmediato. --- ### 2️⃣ Buscar el documento del QR Consulta el ERP: Campos devueltos: - `name` (documento padre) - `empleado` - `fecha` del escaneo Si no hay resultados: **QR inválido**. --- ### 3️⃣ Filtrar último registro por empleado Construye una lista de empleados únicos y toma el último escaneo para cada uno. Si el empleado actual tiene un registro: - Calcula diferencia de horas entre el último registro y ahora. - Si es **menor a 4 horas**, se retorna: --- ### 4️⃣ Registrar nuevo escaneo Si cumple la validación, inserta un registro en la tabla:

`POST Tabla Lista Blanca{ fecha, parent, empleado, parentlink: Registro de Escaneres de Bus}`

Si falla el registro → error Si se registra correctamente → "permitido" --- ## 📤 Response 200 – Ejemplos ### ✔️ Permitido ### ⛔ Denegado por escaneo reciente ### ❌ QR sin registros ### ❌ Error interno --- ## ❗ Posibles Errores 1. **QR vacío** 2. **Empleado vacío** 3. **QR inexistente en ERP** 4. **Error al insertar registro** 5. **Error interno (try–catch)** --- ## 🗃 Tablas / Schemas utilizados ### **Registro de Escaneres de Bus (tpr)** Campos usados: ### **Tabla Lista Blanca (teas)** Campos usados: ### Registro Insertado --- ## 🧩 Pseudocódigo del flujo

`if qr is empty → errorif employee is empty → error// Buscar registros del QRdataQR = SELECT * FROM RegistroEscaneresBus JOIN TablaListaBlanca WHERE qr = qr ORDER BY fecha DESCif dataQR is empty → error// Obtener últimos registros por empleadoempleadosUnicos = agrupar_por_empleado(dataQR)if empleadosUnicos[employee] existe: diffHoras = horas_entre(último registro, ahora) if diffHoras < 4: return "denegado"// Registrar nuevo escaneoinsert = POST TablaListaBlanca { fecha: now, empleado, parent: documentoPrincipal}if insert.error: return errorreturn "permitido"`

# Módulo Supervision # Lista Sucursales (1) - [listSucursalSupervition] ## 🧾 Descripción Este servicio obtiene todas las supervisiones realizadas por un **Supervisor Nacional**, junto con información adicional relacionada a: - Las sucursales supervisadas - La fecha de registro - El documento generado - La programación de supervisión vinculada - La fecha real en la que se ejecutó dicha supervisión El servicio consolida datos procedentes de: - `Check List del Supervisor Nacional 2` - `Tabla supervisores` - `Programación de Supervisores` y devuelve una lista enriquecida de supervisiones. --- ## 🚀 Endpoint **POST** `/list-sucursal-supervition` --- ## 📥 Parámetros de Entrada (Request) ### Body / FormData

Parámetro	Tipo	Obligatorio	Descripción
`Employe`	string	✔️	Código del empleado supervisor cuyo historial de supervisiones será consultado.

Ejemplo: --- ## 🔐 Seguridad - Requiere autenticación interna del ERP (token manejado por `ServiceErp()` y `dbErp()`). - Solo accesible para usuarios válidos dentro del entorno de capacitación. --- ## 🧠 Flujo del Servicio (Resumen Detallado) ### **1️⃣ Validar parámetro recibido** Si `Employe` viene vacío, se retorna un mensaje de validación. ### **2️⃣ Listar supervisiones creadas por el supervisor** Consulta en el ERP: - Si no hay resultados → Retorna mensaje indicando ausencia de registros. ### **3️⃣ Obtener la relación con Tabla Supervisores** Con los `name` obtenidos, se consulta:

`POST send-query-databaseFROM tabCheck List del Supervisor Nacional 2 sprLEFT JOIN tabTabla supervisores tab ON spr.name = tab.id_doctypeWHERE spr.name IN (...)SELECT spr.name, tab.parent`

Construye: - `$datanew[parent] = name` - `$data_alrevez[name] = parent` ### **4️⃣ Obtener programación de supervisores** Si existen supervisiones relacionadas, consulta:

`POST send-query-databaseFROM tabProgramacion de SupervisoresWHERE name IN parentsSELECT name, prog_supervisores, fecha_real_de_la_supervicion`

Se agrega esta información a cada supervisión detectada. ### **5️⃣ Unir los datos** Cada supervisión final contendrá: - sucursal - fecha del checklist - nombre del documento checklist - programación de supervisión (`prog_supervisores`) - fecha real de supervisión (`fecha_real_de_la_supervicion`) --- ## 📤 Response (200 – Ejemplo) --- ## ❗ Posibles Errores ### 1. Supervisor no enviado ### 2. Error del servicio ERP ### 3. Supervisor sin supervisiones registradas --- ## 📚 Tablas / Recursos involucrados ### **Check List del Supervisor Nacional 2** Campos usados: ### **Tabla supervisores** Relación entre registros checklist y programaciones. ### **Programación de Supervisores** Campos utilizados: --- ## 🗃 Pseudocódigo del Servicio # Informacion de sucursal (1) - [infosupervitionName] ### 🧾 Descripción Obtiene la información general de un checklist del **Supervisor Nacional**, incluyendo: - Datos principales de la cabecera del checklist - Promedio de progreso de todas las categorías evaluadas - Puntaje total acumulado El servicio combina información proveniente de: - ERP (doc: *Check List del Supervisor Nacional 2*) - Servicio interno `listCategory()` (el cual obtiene las secciones/categorías del checklist) --- # 🚀 Endpoint ### POST /infosupervition-name 🔸 **Recibe un parámetro obligatorio en el body:** --- # 🔐 Seguridad Requiere autenticación interna mediante `ServiceErp()` y dependencias del módulo `general`. --- # 🧠 Flujo del Servicio (resumen real) 1. **Valida parámetro `name`** Si viene vacío, retorna error utilizando `responseValidate()`. 2. **Obtiene todas las categorías** asociadas al checklist Usa: 3. **Valida respuesta de categorías** - Si ocurre error → retorna mensaje de fallo. - Si la data viene vacía → indica que no existen registros creados. 4. **Calcula progresos y puntajes totales** Recorre cada categoría para: - Sumar `section_puntaje` - Sumar `progreso` - Contar categorías Luego obtiene: - `all_progress = total_progreso / cantidad_categorias` - `all_point = round(total_puntaje)` 5. **Consulta información de cabecera del checklist en ERP** Realiza: Campos obtenidos: - sucursal - fecha - name 6. **Agrega métricas calculadas** al resultado: - `all_progress` - `all_point` 7. **Retorna respuesta final con la información consolidada** --- # 📥 Request Body --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. name vacío ### 2. Error al obtener categorías ### 3. No existen registros en categorías ### 4. Error consultando al ERP --- # 📚 Schemas usados ### Categoría (respuesta de listCategory) ### Check List del Supervisor Nacional 2 (ERP) --- # 🗃 Lógica en pseudo-código # Puntajes de las categorias (1) - [listCategory] ## 🧾 Descripción Obtiene y procesa dinámicamente todas las **categorías**, **preguntas** y **porcentajes de avance** del **Check List del Supervisor Nacional 2**, basándose en su estructura de campos del DocType y los valores registrados en un documento específico. Este servicio: 1. Lee la estructura del DocType para identificar: - Secciones (categorías). - Preguntas tipo **Check**, **Data**, **Attach Image**. 2. Recupera los valores reales del documento filtrado por `name`. 3. Agrupa los campos por categoría. 4. Calcula el avance (%) y puntaje por sección. 5. Devuelve un resumen por categoría con: - Total de campos. - Campos completados. - Progreso (%). - Puntaje asignado. --- # 🚀 Endpoint **POST /list-category** --- # 📥 Request Body ### Parámetros

Campo	Tipo	Requerido	Descripción
name	string	✔	ID del documento cuyo checklist se evaluará

--- # 🔐 Seguridad El servicio utiliza autenticación interna mediante: `$this->general->ServiceErp()` Por lo tanto, requiere credenciales válidas para consumir el ERP. --- # 🧠 Flujo del Servicio (Explicación Técnica Real) ### 1️⃣ Obtener estructura del DocType Se consulta: `GET resource/DocType/Check List del Supervisor Nacional 2` Esto trae **todos los campos** del formulario. El servicio filtra únicamente: - Section Break → marca inicio de categoría - Check - Data - Attach Image También **omite** los campos de puntaje global: - porcentaje\_de\_imagen\_y\_presentación - puntaje\_de\_imagen\_y\_presentación --- ### 2️⃣ Construcción dinámica de categorías y preguntas Ejemplo de agrupación generada: --- ### 3️⃣ Recuperar valores del documento Se unen todos los fields encontrados y se hace: Esto trae los valores registrados del documento. --- ### 4️⃣ Agrupar los valores por categoría El servicio arma una estructura: --- ### 5️⃣ Calcular puntajes y progreso Para cada categoría: - Se cuenta el total de campos (Check, Data, Imagen) - Se cuentan los completados: - Check → valor 1 - Se asigna un puntaje: - Cada check activo suma **1.82** - Se calcula: ⚠ Nota: El servicio divide el total de campos entre 3 (`$maxFields = $maxFields / 3`) para compensar que cada pregunta tiene 3 tipos de fields (check, data, image). --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. No se puede obtener el DocType ### 2. Documento no encontrado (El servicio devolverá valores vacíos por categoría) --- # 🗃 Estructuras Utilizadas ### DocType (GET) Campos analizados: --- # 🧩 Lógica en pseudocódigo

`doctype = GET DocType fieldscategorias = {}foreach field in doctype.fields: if field is Section Break: categoria_actual = field.label if field is Check/Data/Image: categorias[categoria_actual].append(field.fieldname)# Obtener valores reales del documentovalues = GET Check List del Supervisor Nacional 2 where name = request.name# Agrupar valores por categoríaforeach categoria in categorias: newQuestions[categoria] = tomar valores según fieldname# Calcular porcentaje y puntajeforeach categoria in newQuestions: total = count(fields) / 3 completos = fields con valor 1 puntaje = completos * 1.82 agregar resultado al response`

# Respuestas formulario (1) - [missing_questions_form] ### 🧾 Descripción Este servicio identifica **qué preguntas no han sido completadas** dentro de un formulario del DocType: **Check List del Supervisor Nacional 2** El servicio analiza: - Una **categoría** específica del formulario (Section Break). - Un documento del Doctype, identificado por **name**. - Obtiene **todos los campos relevantes** (Check, Data, Attach Image). - Compara estos campos con los valores del documento - Devuelve **solo los campos incompletos**, agrupados por categoría. Se usa principalmente para: ✔ Validar formularios incompletos ✔ Mostrar al usuario qué preguntas faltan llenar ✔ Controlar flujos de supervisión/inspecciones --- # 🚀 Endpoint **POST** `/missing-questions-form` --- # 📥 Parámetros del Request

Campo	Tipo	Obligatorio	Descripción
category	string	✔ Sí	Nombre de la sección del formulario (label del Section Break).
name	string	✔ Sí	ID del documento del Doctype "Check List del Supervisor Nacional 2".

### Ejemplo de request: --- # 🔐 Seguridad Utiliza autenticación interna a través de: No requiere autenticación externa del usuario final. Toda la data se obtiene desde el ERP. --- # 🧠 Flujo del Servicio (Resumen Técnico) ### 1️⃣ Validaciones iniciales - Verifica que **category** no esté vacío. - Verifica que **name** no esté vacío. Si falta un campo → retorna error inmediato. --- ### 2️⃣ Obtiene estructura del formulario GET al Doctype: `GET /resource/DocType/Check List del Supervisor Nacional 2` De ahí obtiene: - Section Breaks - Campos tipo Check - Campos tipo Data - Campos tipo Attach Image Y construye un arreglo organizado por secciones: **Se excluyen automáticamente:** - porcentaje\_de\_imagen\_y\_presentación - puntaje\_de\_imagen\_y\_presentación --- ### 3️⃣ Filtra solo la categoría solicitada Busca dentro de todas las secciones y selecciona solo: `questions[category]` Si no existe → retorna vacío. --- ### 4️⃣ Obtiene valores del documento filtrado por name Aquí obtiene los valores reales del formulario. --- ### 5️⃣ Determina qué preguntas faltan completar Compara para cada campo: `si campo == 0 → está incompleto → se agrega a la lista` Guarda: - fieldnames faltantes - Texto de la pregunta - Identificación por sección --- ### 6️⃣ Retorna solo las preguntas faltantes --- # 📤 Response 200 – Ejemplo Real --- # ❗ Posibles Errores ### 1️⃣ category vacío --- ### 2️⃣ name vacío --- ### 3️⃣ El Doctype no responde --- ### 4️⃣ Error en consulta de valores del documento --- # 🗃 Estructuras Usadas ### 📌 DocType: Check List del Supervisor Nacional 2 Campos analizados: - Section Break - Check - Data - Attach Image Se ignoran: - porcentaje\_de\_imagen\_y\_presentación - puntaje\_de\_imagen\_y\_presentación --- # 🧩 Algoritmo en Pseudocódigo # Respuestas (1) - [missing_questions] ## 🧾 Descripción Este servicio obtiene las **preguntas incompletas y completas** de una categoría específica del Doctype **“Check List del Supervisor Nacional 2”**, basándose en un registro identificado por su `name`. El servicio: 1. Obtiene toda la estructura de campos del Doctype. 2. Identifica qué campos pertenecen a cada categoría (Section Break). 3. Filtra únicamente los campos tipo: - **Check** - **Data** *(comentado actualmente)* - **Attach Image** *(comentado actualmente)* 4. Consulta los valores reales del formulario (`0` o `1`). 5. Determina qué preguntas están completas o incompletas. 6. Devuelve solo la categoría solicitada. Es un servicio orientado a auditorías y evaluación operacional. --- # 🚀 Endpoint **POST /missing-questions** --- # 📥 Parámetros (Request Body)

Campo	Tipo	Obligatorio	Descripción
`name`	string	✔️	Identificador del documento del Doctype “Check List del Supervisor Nacional 2”.
`category`	string	✔️	Nombre de la categoría (Section Break) a analizar.

Ejemplo: --- # 🔐 Seguridad Requiere autenticación ERP válida, manejada internamente por **ServiceErp()**. --- # 🧠 Flujo del Servicio (Resumen) 1. **Validación de parámetros** Si `name` o `category` vienen vacíos → error inmediato. 2. **Obtener estructura del Doctype** GET `/resource/DocType/Check List del Supervisor Nacional 2` - Extrae los campos agrupados por sección (Section Break). - Identifica solo campos tipo **Check**. 3. **Agrupar preguntas por categoría** - Mapea `category` → lista de campos (fieldname → label). 4. **Construir lista total de fields para consultar sus valores** Ejemplo: 5. **Consultar valores reales del registro** GET `/resource/Check List del Supervisor Nacional 2?fields=[...]&filters=[["name","=",name]]` 6. **Clasificar por categoría**: - Si campo = `0` → **Incompleta** - Si campo = `1` → **Completa** 7. **Retornar solo la categoría solicitada.** --- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Parámetro vacío ### 2. Error al consultar el DocType ### 3. Error consultando los valores del registro --- # 📚 Estructuras utilizadas ### ✔️ Doctype: **Check List del Supervisor Nacional 2** Campos relevantes:

Tipo	Uso
Section Break	Agrupar preguntas por categoría
Check	Representa preguntas de Sí/No
Data	(comentado, no procesado actualmente)
Attach Image	(comentado, no procesado actualmente)

Ejemplo de estructura procesada: --- # 🧠 Pseudocódigo Real # Adjuntar imagen (1) - [uploadFileErp] ### 🧾 Descripción Este servicio permite **subir un archivo al ERP** utilizando el endpoint interno `method/upload_file`. Funciona enviando el archivo recibido desde el request PHP (`$_FILES["file"]`) mediante **cURL** hacia el servicio de carga del ERP y devuelve los metadatos del archivo subido: - URL pública - Fecha de creación - Nombre del archivo - Tamaño del archivo Es un servicio auxiliar utilizado por funcionalidades que requieren cargar documentos o imágenes hacia el servidor del ERP. --- # 🚀 Endpoint ### POST `/upload-file-erp` 📌 **Requiere enviar un archivo en el campo `file` del formulario.** --- # 🔐 Seguridad No utiliza el token del usuario. El servicio realiza la subida como **Guest**, usando los headers de cookie: ➡️ Esto significa que la API de ERP ya está configurada para permitir carga de archivos desde clientes externos bajo permisos Guest. --- # 🧠 Flujo del Servicio (resumen) 1. Captura el archivo enviado en `$_FILES["file"]`. 2. Crea un objeto `CURLFile` con: - ruta temporal (`tmp_name`) - tipo MIME - nombre original 3. Envía el archivo al endpoint: 4. Espera la respuesta del ERP. 5. Decodifica la respuesta JSON. 6. Retorna un objeto con: - url del archivo - fecha de creación - nombre - tamaño --- # 📥 Request Body Debe enviarse como `multipart/form-data`. ### Ejemplo (form-data):

Campo	Tipo	Descripción
file	File	Archivo a subir

Ejemplo en HTML:

`<form method="POST" enctype="multipart/form-data"> <input type="file" name="file">form>`

--- # 📤 Response 200 – Ejemplo --- # ❗ Posibles Errores ### 1. Error al procesar el archivo ### 2. Error en cURL ### 3. El ERP no devuelve estructura válida --- # 📚 Estructura de respuesta del ERP El ERP retorna algo como:

`{ "message": { "file_url": "/files/image.png", "creation": "2025-01-15 10:45:00.12584", "file_name": "image.png", "file_size": 48204 }}`

--- # 🗃 Lógica en pseudo-código # Actualizar terminos de supervision (1) - [updatequestion] ## 🧾 Descripción Actualiza los campos (preguntas) de un documento del Doctype **“Check List del Supervisor Nacional 2”** dentro del ERP, permitiendo modificar dinámicamente cualquier grupo de preguntas o valores enviados desde la aplicación. El servicio **solo actualiza los campos enviados**, y valida previamente que realmente existan cambios antes de ejecutar la operación. --- ## 🚀 Endpoint ### **POST /updatequestion** --- ## 📥 Request Body

`{ "questions": "{...}", "name": "CHK-LIST-0001"}`

### 📌 Parámetros

Campo	Tipo	Obligatorio	Descripción
questions	string (JSON-stringified)	✔️	Objeto JSON con los campos a modificar.
name	string	✔️	ID del documento del check list que se actualizará.

Ejemplo del campo **questions**: --- ## 🔐 Seguridad Requiere autenticación interna mediante: `$this->general->ServiceErp(...)` ➡️ Se usa el token y contexto configurado internamente para comunicarse con el ERP. --- ## 🧠 Flujo del Servicio (resumen real) 1. **Valida parámetros obligatorios** Si `questions` o `name` viene vacío, retorna error de validación. 2. **Valida que existan cambios reales** Si `questions == '{}'`, se considera que no hubo modificación. 3. **Convierte a array el JSON recibido** 4. **Genera el payload a actualizar** Todos los campos recibidos se envían directamente al ERP. 5. **Realiza la actualización mediante API ERP** 6. **Retorna el resultado de la operación** --- ## 📤 Response 200 – Ejemplos ### ✅ Actualización correcta ### ⚠️ No hubo cambios enviados ### ❌ Error de validación ### ❌ Falla en el PUT --- ## ❗ Posibles Errores

Error	Descripción
Parámetros vacíos	Si `questions` o `name` está vacío.
Sin cambios	Cuando el JSON está vacío (`{}`).
Error en ERP	Si el PUT falla por permisos, campos inexistentes o problemas del servidor.
Error inesperado	Respuesta falsa o nula desde ServiceErp.

--- ## 📚 Schemas (datos usados) ### ✔ Check List del Supervisor Nacional 2 (PUT) Campos dinámicos según las preguntas. Ejemplo: --- ## 🗃 Lógica en pseudo-código

`questionsForm = request.questionsname = request.nameif questionsForm empty → return errorif name empty → return errorif questionsForm == "{}" → return "no hizo cambios"questions = decode(questionsForm)fields = questionsupdate = PUT /resource/Check List del Supervisor Nacional 2/{name} with fieldsif update fails → return errorreturn success`

# Módulo Auth # Autenticacion por dos (1) - [generateCodeAuthenticator] ## 🧾 Descripción Genera un **código de verificación de 6 dígitos** para un usuario y lo envía al servicio externo encargado del sistema de **autenticación de doble factor (2FA)**. Este servicio: 1. Recibe el número de documento del usuario. 2. Genera un código aleatorio numérico de 6 dígitos. 3. Envía ese código al servicio `https://sistema.shalomcontrol.com/api/generate_code_two_factor`. 4. Devuelve la respuesta del servicio externo. Es usado para validar la identidad del usuario durante procesos de autenticación reforzada. --- ## 🚀 Endpoint **POST** `/generate-code-authenticator` --- ## 📥 Request Body ### Parámetros

Campo	Tipo	Obligatorio	Descripción
`username`	string	✔️	DNI, pasaporte o documento del usuario

--- ## 🔐 Seguridad No requiere token del ERP. Sin embargo, el envío del código es gestionado mediante una llamada a un **servicio externo** con autenticación interna del cliente `Piero()`. --- ## 🧠 Flujo del Servicio (resumen real) 1. **Valida** que el request incluya `username`. - Si no existe, retorna error. 2. **Genera un código numérico aleatorio de 6 dígitos**, cada uno seleccionado de `"0123456789"`. 3. **Envía el código** al servicio: Con los parámetros: 4. **Recibe y retorna** la respuesta proporcionada por el servicio externo. 5. Si ocurre un error en la solicitud HTTP (BadResponseException), devuelve: --- ## 📤 Response 200 – Ejemplo *(La estructura exacta depende del servicio externo `sistema.shalomcontrol.com`.)* --- ## ❗ Posibles Errores ### 1. Falta el número de documento ### 2. Error del servicio externo ### 3. Error inesperado (validación interna) --- ## 📚 Código que genera el servicio (resumen simplificado)