DOC. SERVICIOS APP - SHALOM FAMILIA

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)

Ejecuta check_password(usr, pwd)
- Si falla → usuario o contraseña incorrectos
Consulta el campo enabled:

frappe.db.get_value("User", usr, "enabled")
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"}'

Modulo Inicial

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:

Verifica la versión de la app contra versiones.json.
Crea o actualiza el registro de un usuario en la base de datos mysql2.users.
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.

Modulo Inicial

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

Validación inicial
Si email_logued viene vacío → error
Buscar Employee asociado al usuario
Consulta en ERP:

GET Employee?limit=None &fields=["name","terminos_y_condiciones_app"] &filters=[["user_id","=", email_logued]]
Manejo de errores:
- Respuesta sin data
- Array vacío
Actualizar Employee

PUT Employee/{employee_name} { "terminos_y_condiciones_app": 1, "fecha_terminos_y_condiciones": "Y-m-d H:i:s" }
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"}'

Modulo Inicial

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.

Modulo Inicial

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

Recibe el parámetro app.
Obtiene todas las versiones desde $this->data()
(método interno que no está mostrado pero retorna un array asociativo).
Valida si la clave app existe en el array versiones:
- No existe → error
- Existe → procede
Obtiene el nombre de la app desde: $this->apps[$app]
Obtiene la versión asociada: $versiones[$app]
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:

Modulo Inicial

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)

Toma name desde el request.
Construye una consulta SQL hacia ERP que busca:
- El usuario (rol.parent)
- El rol "Supervisor Nacional" (rol.role)
Ejecuta:
- dbErp("POST", body, method/send-query-database)
Si encuentra el rol → retorna verdadero
Si no lo encuentra → indica que no es supervisor
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"}'

Modulo Inicial

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"}'

Modulo Inicial

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

Validación por fecha
Si la fecha actual es mayor al día 7 del mes → no corresponde validación.
Obtiene el mes anterior y convierte el número en texto (ej. 01 → Enero).
Si fechaIngreso >= primer día del mes actual, entonces el trabajador ingresó recientemente → no se valida descarga.
Consulta en la BD (mysql2.historial_procesos_app) si existe un registro:
- proceso = 'NOMINA'
- empleado = <employee>
- month y year del mes anterior
- Registros con fecha ascendente
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 <MesTexto> <Año>, 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"}'

Modulo Inicial

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)

📚 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"}'

Modulo Inicial

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": []
}

{
  "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": "<detalle_del_error>"
}

🧩 Lógica Interna

Valida parámetros obligatorios: name, marked, cookie.
Construye la propiedad add:
- marked = true → "Yes"
- marked = false → "No"

Construye la llamada a ERPNext:

ERPNext registra o quita el Like.
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
}'

Modulo Inicial

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:

Consulta los comentarios del documento Publicaciones/{post_name}.
Obtiene la lista de empleados activos desde ERP para enlazar owner → nombre_completo.
Ordena todos los comentarios por fecha de creación en orden ascendente.
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

📥 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)

Validación de entradas
- Se extraen: cookie, post_name, start, limit.
Consulta de comentarios
- Endpoint Frappe llamado: GET APICAPACITACION/resource/Publicaciones/{post_name}
- Envia parámetros:
  
  fields: [] filters: [] limit_start: start limit_page_length: limit
Consulta de empleados activos
- Solicita: Employee?fields=["name","nombre_completo","user_id"]&filters=[["status","=","Active"]]
- Construye un mapa: user_id → nombre_completo
Enriquecimiento de comentarios
- A cada comentario se le agrega: nombre_completo = jsonEmployee[owner] ?? owner
Ordenamiento
- Orden ascendente por la fecha creation.
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
}'

Modulo Inicial

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

📥 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": "<mensaje de error>"
}

🧩 Lógica interna del servicio

Crea un cliente ApiRest con manejo de cookies.
Construye los datos del comentario:
- content
- parent (publicación)
- parenttype = Publicaciones
- parentfield = comments
Envía un POST al endpoint del ERP:

{APICAPACITACION}/resource/postComend2
Maneja error HTTP (BadResponseException).
Si la respuesta contiene data, devuelve éxito.
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"}'

Modulo Información Personal

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

employe vacío → se devuelve error mediante responseValidate().
Los demás campos son opcionales.
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)

Recibe parámetros del request.
Si employe está vacío → error.
Crea un arreglo updateKeys solo con los campos enviados.
Llama a:

Con el body:

Devuelve la respuesta del ERP.

📚 Schemas

Request

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

Response

🧪 Ejemplo de Uso (curl)

Modulo Información Personal

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:

Recepción de un archivo enviado desde la app.
Subida del archivo al endpoint de ERPNext: method/upload_file.
Obtención de la URL generada del archivo.
Actualización del campo user_image del User.
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.png
user: 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": "<file_url>"
}

5. Actualizar Employee si corresponde

Busca Employee cuyo user_id coincida:

Si existe:

📚 Request/Response Schemas

Request (multipart/form-data)

file: File
user: 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)

Validación de fechas
- Si el día actual es mayor a 3, no se hace validación → se retorna éxito.
Consultar datos del empleado
- Obtiene desde ERP:
  - fecha_de_ingreso_real
  - status
Casos especiales por estado
- Si el empleado está en PreActivo, no se valida.
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.
Validar si existe boleta generada
- Consulta Salary Slip del mes anterior.
- Si no existe boleta → no corresponde validar.
Validar si la boleta mensual está habilitada (Estado Boleta Mensual)
- Revisa si está habilitada para ese mes.
Verificar si ya descargó boleta
- Revisa tabla historial_procesos_app en MySQL.
- Si no descargó → retorna mensaje de pendiente.
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_date
FROM `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.)

Modulo de Asistencia y Marcaciones (Marcaciones)

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

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

📚 Consultas utilizadas

A. Obtener datos del empleado

SELECT fecha_de_ingreso_real
FROM `tabEmployee`
WHERE name = {empleado}

B. Consulta de renovaciones

C. Validación de descarga

🧪 Ejemplo de consumo (HTTP)

Request:

Response (pendiente):

Modulo de Asistencia y Marcaciones (Marcaciones)

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)

Verifica que se haya enviado un nombre de puesto.
Construye una consulta GET hacia: resource/Designation

Con:
- filters: [["name","=", puesto]]
- fields: ["mof"]
Envía la solicitud mediante: ServiceErp("GET", null, body, APICAPACITACION."resource/Designation")
Evalúa la respuesta:
- Si encuentra registros → devuelve el mof.
- Si no encuentra → error.

📚 Schema

Response

🧪 Ejemplo de Uso (curl)

Respuesta esperada:

Modulo de Asistencia y Marcaciones (Marcaciones)

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

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.
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"
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
Construcción del resumen por empleado
- Cada documento es asignado como:
  - 1 → descargado
  - 0 → pendiente
Validación del 100% de documentos
- Si todos los procesos están registrados → total_documentos = true
- Si falta alguno → total_documentos = false
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.
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

Modulo de Asistencia y Marcaciones (Marcaciones)

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

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: <mensaje>",
  "error": "<stacktrace>"
}

📚 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, date

calcular inicio y fin del día
si date >= 2022-11-10:
    buscar checkin por fecha_consolidado
else:
    buscar checkin por rango de horas

consultar Attendance
consultar Cortes del mes

si cortes vacío → error

generar fechas posteriores al corte

determinar estado (status o estado_reporte)

crear estructura de salida

iterar marcaciones:
    si log_type == Entrada → entrada
    si log_type == Salida Refrigerio → salida_refrigerio
    etc.

retornar JSON con todas las marcaciones y estado

Modulo de Asistencia y Marcaciones (Marcaciones)

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

Modulo de Asistencia y Marcaciones (Marcaciones)

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

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
Decodifica la respuesta.
Valida que exista el campo "data" en la respuesta del ERP.
- Si no existe, retorna error.
Recorre cada registro y convierte ideentificador a string.
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

Modulo de Asistencia y Marcaciones (Marcaciones)

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)

Valida que existan los parámetros obligatorios: empleado, agencia e intento.
Si falta alguno → retorna error.
Determina la fecha actual (Y-m-d).
Este valor se usa para registrar un intento por día.
Consulta si el empleado ya tiene un registro de Intento de marcacion para el día actual:

tpr.empleado = empleado AND tpr.creacion = fecha_actual
Si existe un registro previo:
- Se suma el intento nuevo al intento existente:
  
  intento_total = intento_enviado + intento_existente
- Se actualiza el Doctype:
  
  PUT resource/Intento de marcacion/{name}
Si NO existe un registro previo:
- Se crea un nuevo documento Intento de marcacion:
  
  POST resource/Intento de marcacion
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

employee = request.empleado
agencia = request.agencia
intento = request.intento
fecha = hoy (Y-m-d)

if falta algún parámetro:
    return error

consulta = GET Intento de marcacion where empleado = employee and creacion = fecha

if existe_registro:
    nuevo_intento = intento + registro.intento
    PUT Intento de marcacion/{name} con { empleado, agencia, intento: nuevo_intento, creacion }
else:
    POST Intento de marcacion con { empleado, agencia, intento, creacion }

return respuesta

Modulo de Asistencia y Marcaciones (Marcaciones)

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

if !verifyFields(request): return error

if puesto restringido: return error

if licencia activa: return error

if ingreso reciente y no Shalom Express:
    validar documentos de ingreso

validar documentos descargados

validar contrato

validar cambio de modalidad

validar información del empleado

marcacionesPrevias = getMarkingsByEmployee()

if no sujeto a fiscalización: return error

if marcación es llegada_refrigerio:
    validar inicio refrigerio

validar secuencia de tipo de marcación

return OK

Modulo de Asistencia y Marcaciones (Marcaciones)

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

verify = verifyFields(request)
if !verify.valor → return error

if fecha_asistencia > hoy AND online → return error

validateDuplicateDialing()
if duplicado → return error

turno = GET turno del empleado en ERP

if type == entrada:
    validarPreActive()

calcular tardanza / horas extra

bodyCheckin = {...}
insertERPNew("Employee Checkin", bodyCheckin)

insert DB marcaciones

if type == salida:
    storeAttendance()
    return respuesta con asistencia

return respuesta normal

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:

Si está dentro del rango de validación (solo del día 1 al 3 de cada mes).
La fecha de ingreso del trabajador.
Si tiene boleta generada el mes anterior.
Si el mes correspondiente está habilitado para descarga.
Si el empleado ya descargó la boleta (se revisa historial en MySQL).
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_date
FROM `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

Modulo de Asistencia y Marcaciones (Asistencia)

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)

Verifica la fecha actual.
- Si el día del mes es menor a 26 → No corresponde validar renovaciones.
Obtiene datos del empleado.

SELECT fecha_de_ingreso_real FROM tabEmployee WHERE name = {empleado}
Determina si el empleado aplica para renovación:
- Debe haber ingresado antes del último día del mes anterior.
Busca renovaciones validadas del empleado:

FROM tabSolicitud de Renovaciones doc JOIN tabTrabajadores pendiete de renovar tab WHERE doc.data_12 = <mes_actual_texto> AND doc.año = <año> AND tab.codigo = empleado AND tab.renueva = "Si" AND doc.estado_de_documento = "Validado"
Si existe una renovación validada:
- Consulta MySQL2 → tabla historial_procesos_app
- Revisa si el usuario ya descargó su renovación:
  
  proceso = "descargaContratoRenovacion"
Si no la descargó → bloquea ciertas funciones.
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")

Modulo de Asistencia y Marcaciones (Asistencia)

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)

Recibe parámetros del empleado y mes a consultar.

employee, month, anio, fechaIngreso
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.
Carga feriados y domingos del archivo JSON:

/public/recursos_humanos/holidays.json
Determina cuántos días del mes son feriados o domingos dentro del rango permitido.
Valida campos obligatorios.
Consulta en el ERP todas las asistencias del empleado en el mes:

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
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.
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, fechaIngreso

validar campos requeridos

calcular fecha_inicio y fecha_fin según:
    - mes actual
    - fecha de ingreso del empleado

cargar feriados y domingos (holidays.json)
contar días dentro del rango

consultar asistencias en ERP:
    SELECT attendance_date, status
    FROM tabAttendance
    WHERE employee = employee
    AND status IN (...)

inicializar contadores

foreach asistencia in resultado:
    clasificar según status
    acumular días, permisos, faltas, descansos, feriados

calcular porcentaje de asistencia

return {
    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 tabEmployee
fields = ["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 Slip
WHERE employee = empleado
AND 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 Mensual
WHERE mes = <mes anterior en texto>
AND año = <año>
AND habilitado = 1

6️⃣ Consulta si el usuario ya descargó la boleta

Busca en MySQL:

historial_procesos_app
WHERE empleado = empleado
AND proceso = 'NOMINA'
AND month = mes
AND 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

Modulo de Asistencia y Marcaciones (Horas Extras)

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

Modulo de Asistencia y Marcaciones (Horas Extras)

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

corte = GET Cortes where año=year and mes=month
if corte empty → return error

hours = GET Horas Extras where año, mes, empleado
markings = GET Marcaciones where user_id=employee and date between corte

feriados = cargar holidays.json

foreach marking:
    if fecha in feriados → 100%
    else if horas <= 2 → 25%
    else:
        agregar 2h al 25%
        agregar horas-2 al 35%

sumar horas acumuladas

return {
    marcaciones procesadas,
    horas25, horas35, horas100,
    horas_acumuladas
}

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)

Valida que el parámetro employee exista.
Valida que el parámetro year exista.
Consulta al ERP:

Verifica que exista información.
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.
Para cada coincidencia arma un objeto con:
- motivo
- monto
- año
- mes
- creation (en formato "d de Mes")
Si no hay coincidencias, retorna "Sin Descuentos".
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/<program_name>
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/<course_name>
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:

Validar si ya existe matrícula:

Si existe, se almacena como encontrado.
Si no existe, se crea:

POST Program Enrollment
{
  "student": "<student_id>",
  "program": "<program>",
  "enrollment_date": "<fecha_hoy>",
  "academic_year": "<año>",
  "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.dni

if empty(dni):
    return error

student = query Student where dni=dni order by joining_date desc limit 1
if not found:
    return error

designation = student.puesto

programas = GET all programs
mapProgramas = generar mapa curso → programas

cursos = GET all courses
mapCursos = generar mapa puesto → cursos

if designation not in mapCursos:
    return error

programas_final = programas donde cursos del puesto están incluidos

foreach programa in programas_final:
    if enrollment existe:
        agregar a enrollments encontrados
    else:
        crear enrollment
        agregar respuesta a enrollments

Módulo Capacitación(Cursos)

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

employee = GET tabEmployee 
           WHERE passport_number = dni 
           AND status = 'Active'

if employee exists:
    puesto = employee.designation
else:
    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 = puesto

if cursosAsignados empty:
    return error("Su usuario no tiene cursos asignados")

idsCursos = cursosAsignados.parents

infoCursos = GET tabCourse WHERE name IN idsCursos

return infoCursos

Módulo Capacitación(Cursos)

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)

Recibe el curso por parámetro.
Consulta al ERP el recurso:

Verifica que el curso exista; si no, devuelve error:

Su usuario no tiene cursos asignados
Extrae la lista de topics del curso.
Para cada topic:
- Inicializa sus contadores:
  
  videos = 0 articulos = 0
- Consulta el contenido del tópico:
  
  GET resource/Topic/{topic_id}
- Recorre el contenido (topic_content):
  - Si content_type == Video → incrementa contador de videos
  - Si content_type == Article → incrementa contador de artículos
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

Módulo Capacitación(Cursos)

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": "<url del video>"

📄 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": "<texto procesado o link>"

❓ Si es Quiz y hay estudiante:

Agrega: "quiz_attempts": <numero_de_intentos>

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

Módulo Capacitación(Cursos)

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

Módulo Capacitación(Cursos)

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:

Recibe el DNI del estudiante, el identificador del examen y las respuestas.
Valida que el estudiante exista en el ERP.
Obtiene la definición completa del examen (Quiz) desde el ERP.
Obtiene la información detallada de cada pregunta usando los question_link.
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)

Recibe datos del request:
- $dni
- $examen
- $respuestas (JSON string → array)
Decodifica las respuestas del examen:

$respuestas = json_decode($respuestas, true);
Busca al estudiante por DNI (solo estudiantes habilitados):

GET Student
filters=[["Student","enabled","=",1],["Student","dni","like","%<dni>%"]]
- Si no encuentra coincidencias → ❌ devuelve error:
  
  { "valor": false, "msn": "Su usuario no tiene cursos asignados" }
Obtiene la definición del examen (Quiz) desde el ERP:

GET Quiz/<examen>
- Trae todas las preguntas vinculadas.
Por cada pregunta del examen:
- Consulta la API:
  GET Question/{question_link}
- Agrega la información completa al arreglo final.
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:

puntaje = "-" estado = "No rindió"
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.email
date = request.date

if email is empty:
    return error

employee = GET Employee by user_id=email
if empty:
    return error

designation = employee.designation
if empty:
    return error

exams = GET Designation/exams

range = firstDayOfMonth(date), lastDayOfMonth(date)

quizResults = GET QuizActivity where dni = employee.passport_number and creation between range

prepare response:
    for each exam:
        set puntaje = "-"
        set estado = "No rindió"

    for each quizResult:
        keep best score
        set estado based on Pass/Fail

return 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)

Valida que existan campos obligatorios:
- employee
- banco
- fondo_pensiones
- afiliado_fondo_pensiones (“SI” o “NO”)
Construye un arreglo con los datos a actualizar:

Si el fondo de pensiones es ONP, también actualiza:

Si se envían documentos opcionales (DNI, copia de DNI de hijos, CV, certificado de trabajo, etc.), también se agregan al payload.
Realiza la actualización del empleado:

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

if employee is empty → error
if banco is empty → error
if fondo_pensiones is empty → error
if afiliado_fondo_pensiones not in ("SI","NO") → error

data = {
    eleccion_banco: banco,
    elección_fondo_pensiones: fondo_pensiones,
    afiliado_fondo_pensiones: afiliado_fondo_pensiones
}

if fondo_pensiones == "ONP":
    data["fondo_de_pensiones"] = "ONP"

Agregar campos opcionales si existen

PUT Employee/{employee} with data

return respuesta del ERP + msn "Documentos registrados correctamente"

Módulo Contratación

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_contacted
relation
emergency_phone_number
nombre_completo_conyugue
fecha_de_nacimiento_conyugue
ocupación_conyugue
centro_de_trabajo_conyugue
dirección_actual_conyugue
estado_civil_personal

historial_procesos_app (INSERT)

🗃 Lógica en pseudo-código

empleado = request.empleado
contacto = 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ónyuge

newCivil = employee.estadoCivil != "" ? employee.estadoCivil :
           (civil.nombreCompleto ? "Casado/a" : "Soltero/a")

bodyPUT = construir campos del contacto + cónyuge

update = PUT Employee/{empleado}

if update.ok:
    insertar registro en historial_procesos_app
    return success
else:
    return error("Ocurrió un error al actualizar")

Módulo Contratación

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 = document
if not employee:
    error("Empleado no encontrado")

postulacion = GET Job Applicant WHERE document = document ORDER BY creation DESC
if not postulacion:
    error("Postulación no encontrada")

convocatoria = GET Job Opening WHERE name = postulacion.job_title
if not convocatoria:
    error("Convocatoria no encontrada")

branch = GET Branch WHERE name = convocatoria.sucursal
select RP_table = Branch.zone == Lima ? RP_Lima : RP_Normal

rp = GET RP_table WHERE documento_convocatoria = job_title
if not rp:
    error("RP no creada")

return {
    tipo_jornada: rp.tipo_de_jornada,
    modalidad: convocatoria.modalidad || modalidad_de_trabajo,
    convocatoria: job_title
}

Módulo Contratación

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

Módulo Contratación

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)

Lee los parámetros enviados en la petición:
- documento
- botas
- polo
- pantalon
Valida la estructura y tallas permitidas:

Elemento Tallas permitidas

botas 36–45

polo S, M, L, XL

pantalón S, M, L, XL
Busca al postulante por documento:
Llama a:

searchPostulanteByDocument($documento)

Si no existe → retorna error.
Busca si ya existe un registro de triaje activo en el ERP:

GET
/resource/Triaje de Postulante 2
con filtros:

documento = $documento docstatus != 2
Dependiendo del resultado:
- No existe registro → crea uno (POST)
- Sí existe → actualiza el existente (PUT)
Realiza el POST o PUT correspondiente hacia el ERP.
Si ERP devuelve error, intenta decodificar _server_messages para obtener error real del ERP.
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, pantalon

validate document
validate 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 error

triaje = GET TriajeDePostulante2 where documento=document and docstatus != 2

if triaje exists:
    method = PUT
    url = recurso + "/" + triaje.name
else:
    method = POST
    url = recurso

body = {
    documento, botas, polo, pantalon
}

result = CALL ERP with method, body, url

if result.error:
    return readable ERP error

return success

Módulo Contratación

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:

Valida si corresponde un proceso de Reingreso o Renovación de Contrato.
Procesa el registro especial para Conductores, creando su usuario en el sistema empresarial cuando descarga su contrato.
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

Obtiene datos del empleado desde ERP:
- DNI (passport_number)
- Sucursal
- Nombre completo
- Puesto (designation)
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

Módulo Contratación

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-database
FROM tabEmployee
WHERE name = employee
SELECT 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-database
FROM tabContrato de Trabajo
LEFT JOIN tabEmployee

Si no existe contrato → retorna "No cuenta con Contrato".

3️⃣ Obtiene funciones asociadas (solo extranjeros)

Busca funciones del contrato:

FROM tabtabla_funcion_extranjero
WHERE 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)

Recibe el parámetro: codigo = $request->codigo
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

Si no existe la denuncia → se responde:

Si existe y tiene archivo, se concatena la URL base:

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

body = {
    limit = None
    fields = [name, creation, estado_denuncias, fecha_atendido, fecha_proceso, archivo_denuncia, respuesta...]
    filters = [["codigo_aleatorio", "=", codigo]]
}

response = GET Denuncias using ServiceErp

if !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_denuncia

return success with denuncia

Módulo Boletas de Pago

Utilidades(Consultar Utilidades (1)) - [getYearUtilidades]

🧾 Descripción

Este servicio obtiene:

La lista de años registrados en el ERP (tabla Year), ordenados de forma descendente.
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

Módulo Boletas de Pago

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)

Validar parámetros obligatorios
- Si no se envía empleado → retorna error
- Si no se envía proceso → retorna error
Construir filtros dinámicos
- Base: empleado + proceso
- Si llega año → se agrega al WHERE
- Si llega mes → se agrega al WHERE
Consultar la tabla interna
Query sobre:

historial_procesos_app ORDER BY fecha DESC LIMIT 1

Utiliza first() para obtener el último registro.
Validar si existe registro
- Si no existe, devuelve mensaje informando que no se encontró el proceso.
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

No se envía empleado

{ "valor": false, "msn": "Falta empleado." }
No se envía proceso

{ "valor": false, "msn": "Falta proceso." }
No se encontró el registro

{ "valor": false, "msn": "No se encontró el proceso." }
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

Módulo Boletas de Pago

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: <PDF STREAM - 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

Módulo Boletas de Pago

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 = <employee>
- 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/pdf
Content-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

Módulo de Solicitudes

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:

Construye los filtros del ERP.
Busca la última solicitud activa (docstatus < 2).
Si no encuentra registros → devuelve un mensaje indicando que no existe solicitud.
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

Obtiene el adelanto salarial del mes (tabSolicitud de Adelanto Mensual + tabla interna hija).
Si no existe solicitud → devuelve mensaje correspondiente.
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, fecha

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

Módulo de Solicitudes

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

Módulo de Solicitudes

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)

Obtiene el array interno $this->tipos_licencias, previamente definido en el controlador.
Construye un arreglo combos con la estructura:

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

Módulo de Solicitudes

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)

Validación de campos obligatorios
- Verifica empleado, tipo de licencia válido, fecha_ini y fecha_fin.
Cálculo de días de licencia

$dias = (new DateTime(fecha_ini))->diff(new DateTime(fecha_fin))->days;

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

Validación: El empleado no debe tener una solicitud en borrador

GET Solicitud de Licencias filters: [["id_empleado","=",empleado],["docstatus","=",0]]
Construcción del body para enviar al ERP
- Incluye campos adicionales dependiendo del tipo de licencia.
Creación de la solicitud

POST resource/Solicitud de Licencias
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 → error
if tipo no permitido → error
if fechas vacías → error

dias = fecha_fin - fecha_ini

switch 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 <= 30

buscar borradores:
    GET Solicitud de Licencias where empleado & docstatus=0
    si existe → error

body = { empleado, tipo, fechas, documentos }

crear solicitud:
    POST Solicitud de Licencias

si ERP responde error → retornar error
retornar éxito

📚 Estructuras usadas

Solicitud de Licencias (POST)

Campos enviados:

Módulo de Solicitudes

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)

Recibe el campo document desde la solicitud.
Prepara una petición cURL hacia:

{EMPRESARIAL}/api/search_job_applicant
Envía el documento como parámetro form-data:

document = <valor recibido>
Ejecuta la llamada.
Decodifica la respuesta JSON.
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);
}

Módulo de Solicitudes

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:

Se hayan enviado las dos imágenes del DNI (anverso y reverso).
El empleado tenga un género válido y registrado.
No exista ya una asignación familiar duplicada para el mismo hijo (DNI del menor).
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)

Validación de archivos obligatorios
Verifica que se envíen img_dni y reverso.
Si falta uno → retorna error.
Obtiene datos del empleado
Usa el método verifyEmployeeGender($empleado) para traer:
- género
- fecha de ingreso real
Revisa si ya existe una solicitud similar
Busca solicitudes para:
- el mismo DNI del hijo
- la misma fecha de ingreso del empleado
GET Solicitud Asignacion Familiar filters: dni_hijo, fecha_ingreso
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.
Crea la nueva solicitud
Realiza un POST hacia: POST /resource/Solicitud Asignacion Familiar

Con los campos:

{ "id_empleado": "...", "nombre_hijo": "...", "dni_hijo": "...", "edad_hijo": "...", "fecha_hijo": "...", "dni_doc": "...", "reverso": "...", "afiliacion_al_essalud": "..." }
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

if falta img_dni o reverso:
    return error

genderEmployee = verifyEmployeeGender(empleado)

solicitudesPrevias = Buscar solicitudes por dni_hijo y fecha_ingreso

if count == 1:
    otherGender = verifyEmployeeGender(solicitudesPrevias.id_empleado)
    if same gender:
        return error: ya tiene asignación

if count >= 2:
    return error: límite alcanzado

body = datos de asignación familiar

guardar = POST Solicitud Asignacion Familiar

if error:
    return error

return éxito

Módulo de Solicitudes

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 = X
if empty(usuario_rules):
    return módulo inhabilitado

build base filters:
    estado_documento NOT IN ('Pago Rechazado')
    fecha >= hoy - 6 meses

if usuario_rules exist:
    for each rule:
        add OR (concepto = rule.concepto AND monto > rule.monto)

if status enviado:
    add estado_de_validación = X
else:
    exclude ['No requiere', 'Rechazado']

if concepto enviado:
    add concepto = X

requests = query SolicitudPagos with filters

if no requests:
    return lista vacía

get archivos_transados for all requests

group and classify archivos by type

return lista final con archivos agrupados

Módulo de Solicitudes

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)

Validar parámetro usuario
- Si está vacío → responde error de validación.
Construir filtros para ERP

WHERE usuario = <usuario>
Consultar al ERP
Usando:

tabValidacion de Pagos Gerencia

con el SQL:
- SELECT concepto
- FROM tabValidacion de Pagos Gerencia
- WHERE usuario = %(usuario)s
Obtener resultados
- Se extrae la columna concepto de la respuesta.
- Se eliminan duplicados mediante array_unique.
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

Módulo de Solicitudes

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)

Recibe:
- name → ID del documento (Solicitud de Pagos)
- status → Puede ser "Validado" o "Rechazado"
Determina internamente mensajes para usuario según status:
- "Validado" → aprobar
- "Rechazado" → rechazar
Construye el body con el nuevo estado:

["estado_de_validación" => $request->status]
Envía:

PUT /resource/Solicitud de Pagos/{name}
Si el ERP responde con error → devuelve mensaje indicando fallo al aprobar o rechazar.
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

Módulo de Solicitudes

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)

Construye la solicitud hacia el ERP:

Envía la solicitud al ERP mediante:

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

Verifica:
- Si el ERP respondió con error.
- Si no existen registros de empleados activos.
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 body

if response.valor == false:
    return error

if response.data.count == 0:
    return "No se encontraron registros"

return {
    valor: true,
    msn: "Busqueda Existosa",
    data: response.data
}

Módulo de Solicitudes

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)

Construye el body de consulta para el ERP:

{ "limit": "none", "fields": ["nombre_completo", "passport_number", "name"], "filters": [["status", "=", "active"]] }
Realiza el request: GET Employee
Valida:
- Si hubo error en el ERP → retorna error.
- Si la respuesta está vacía → retorna mensaje "No se encontraron registros".
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 Employee

if response.valor == false:
    return error

if response.data is empty:
    return no registros

return {
    valor: true
    msn: "Busqueda Exitosa"
    data: response.data
}

Módulo de Solicitudes

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)

Valida que se hayan enviado todos los campos requeridos.
Si falta alguno, retorna error.
Valida formato de fecha usando validateDate().
Construye el body que será enviado al ERP:

Envía la solicitud al ERP: POST resource/Cambio Salarial Administrativo

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

Módulo de Solicitudes

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)

Define internamente una lista fija con los tipos de AFP:
- AFP Habitat
- AFP Profuturo
- AFP Prima
- AFP Integra
Organiza los datos dentro de un arreglo asociado a la clave "tipos_afp".
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:

Error interno del servidor

{ "valor": false, "msn": "Error interno del servidor", "data": [] }

📚 Schemas usados

Respuesta del servicio

🗃 Lógica en pseudo-código

Módulo de Solicitudes

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": <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"`

Construye la consulta SQL:
- Selecciona sucursales (tabBranch).
- Hace JOIN con empleados (tabEmployee).
- Agrupa y retorna solo sucursales con más de 1 empleado registrado.
Ejecuta la consulta vía:

dbErp("POST", body, /method/send-query-database)
Si encuentra resultados:
- Devuelve solo el nombre de la sucursal (br.name).
Si ocurre error:
- Retorna mensaje de error controlado.

✔️ Si type = `"Puesto"`

Solicita al ERP la lista completa de Designations:

GET resource/Designation?limit=None
Extrae solo el nombre del puesto (name).
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

Módulo Centro de Ayuda

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)

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
Valida que el JSON de denunciados sea correcto.
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.
Valida y arma estructura del archivo adjunto si se envía.
Genera un código aleatorio único que identificará la denuncia.
Crea el documento Denuncias en el ERP:

POST /resource/Denuncias
Guarda los denunciados como tabla hija (table_16).
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/<archivo>

📤 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

Módulo Centro de Ayuda

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:

Obtiene la información principal de la denuncia.
Consulta nuevamente la denuncia para traer sus tablas hijas (por ejemplo table_16).
Construye un array final con los datos completos.
Genera un PDF oficial de la denuncia usando una plantilla Blade.
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","=",<codigo>]]

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=codigo

if demandas is empty:
    return error

foreach denuncia in demandas:
    detalle = GET Denuncias/{name}
    agregar table_16 al resultado final

generar PDF usando vista "pdf/demanda"
retornar archivo: Demanda.pdf

Módulo Centro de Ayuda

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)

Obtiene el código enviado en el request.
Construye el body para consultar la denuncia en el ERP:
- fields: name, creation, estado_denuncias, fechas, archivo, respuesta.
- filters: [["codigo_aleatorio","=", $codigo]]
Llama al ERP:
GET resource/Denuncias
Si no existe denuncia, retorna error.
Si existe:
- Verifica si archivo_denuncia no está vacío.
- Si tiene archivo, le agrega la URL base del servidor.
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

codigo = request.codigo

body = {
    limit: None,
    fields: [name, creation, estado_denuncias, fecha_atendido, fecha_proceso, archivo_denuncia, respuesta_de_denuncia_atendido],
    filters: [["codigo_aleatorio", "=", codigo]]
}

response = GET Denuncias(body)

if response is error or empty:
    return error "No se encontró la denuncia"

denuncia = response[0]

if denuncia.archivo_denuncia != "":
    denuncia.archivo_denuncia = BASE_CAPACITACION + denuncia.archivo_denuncia

return success data = denuncia

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)

Obtener todos los Job Openings internos activos

GET Job Opening?limit=None &fields=["name","designation","sucursal"] &filters=[ ["convocatoria_interna","=",1], ["status","=","Open"] ]
Obtener todos los archivos relacionados al Job Opening

GET File?limit=None &fields=["name","attached_to_name","file_url"] &filters=[["attached_to_doctype","=","Job Opening"]]
Si alguno de los endpoints devuelve error, se retorna:

{ "valor": false, "msn": "Error al buscar las convocatorias internas." }
Si no hay convocatorias abiertas:

{ "valor": true, "msn": "En este momento no hay convocatorias internas..." }
Para cada convocatoria se agrega:
- La descripción de la sede: "PARA LA SEDE {sucursal}"
- El archivo correspondiente (file_url), si existe.
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

Módulo Convocatorias

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("<Doctype>")

🧠 Flujo del Servicio (resumen real)

Inicializa un arreglo vacío $combo.
Obtiene desde el ERP las siguientes listas:
- Países → Doctype: Country
- Sucursales → Doctype: Branch
- Departamentos → Doctype: Department
- Género → Doctype: Gender
Agrega una lista fija de tipos de documentos:

["DNI", "Pasaporte", "Carnet de Extranjeria"]
Retorna la estructura completa con todos los combos.
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

Módulo Convocatorias

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)

{
  "email_logued": "string (obligatorio)",
  "job_title": "string (obligatorio)",
  "email_id": "string (obligatorio, debe contener @)",
  "direccion": "string",
  "adjuntar_copia_de_documento": "string (file url)",
  "sucursal": "string",
  "resume_attachment": "string (file url)",
  "grado_instruccion": "string",
  "phone_number": "string (opcional)",
  "country": "string (opcional)",
  "ciudad": "string (opcional)",
  "nacionalidad": "string (opcional)",
  "carrera_profesional": "string (opcional)"
}

🔐 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 Applicant
BODY: { ...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

sql = SELECT documentos internos + documentos especificos

docs = dbErp(sql)

foreach doc in docs:
    if categoria is null:
        categoria = "POLITICAS"

grouped = group docs by categoria

foreach categoria in grouped:
    group by name (padre)
    
    if categoria == 'IPERC':
        adjunto = campo_para_adjuntar_default
        if puesto matches child:
            adjunto = child.adjuntar
    else:
        adjunto = campo_para_adjuntar

return {
  categorias: keys(grouped),
  categorias_registro: grouped
}

Módulo Documentos Internos

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)

Valida que usuario y terminal existan en la solicitud.
Establece zona horaria America/Lima.
Inserta un registro en la tabla documentos_internos con:
- usuario
- terminal
- tipo
- fecha actual
Si el registro falla, retorna un error.
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

Módulo Documentos Internos

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)

Validación inicial del DNI
- Si el parámetro passport_number no está presente, el servicio responde con error.
Consulta del examen EMO
- Se llama al método interno getExamenEmo($passport_number).
Validación del resultado
- Si el método no retorna datos, se responde con un mensaje indicando que no se encontraron resultados.
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)

Validación inicial del parámetro
- Si employee está vacío → se devuelve error.

Consulta del último escaneo registrado en ERP

Se ejecuta:

Si no existen registros
- Se retorna mensaje indicando que no se encontró escaneo.
Cálculo de la diferencia de tiempo

Se obtiene el tiempo transcurrido entre:
- Fecha del escaneo (fecha)
- Fecha actual
Se obtiene con:

$diff = $fechaEscaneoCarbon->diffInSeconds(now());
Aplicación de la regla de validación
- Si la diferencia es menor a 4 horas (14400 segundos) → permitido
- Si es mayor → denegado
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

Módulo QR

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

QR vacío

Empleado vacío

QR inexistente en ERP

Error al insertar registro

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 → error
if employee is empty → error

// Buscar registros del QR
dataQR = SELECT * FROM RegistroEscaneresBus JOIN TablaListaBlanca WHERE qr = qr ORDER BY fecha DESC

if dataQR is empty → error

// Obtener últimos registros por empleado
empleadosUnicos = agrupar_por_empleado(dataQR)

if empleadosUnicos[employee] existe:
    diffHoras = horas_entre(último registro, ahora)
    if diffHoras < 4:
        return "denegado"

// Registrar nuevo escaneo
insert = POST TablaListaBlanca {
    fecha: now,
    empleado,
    parent: documentoPrincipal
}

if insert.error:
    return error

return "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-database
FROM tabCheck List del Supervisor Nacional 2 spr
LEFT JOIN tabTabla supervisores tab ON spr.name = tab.id_doctype
WHERE 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-database
FROM tabProgramacion de Supervisores
WHERE name IN parents
SELECT 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

Módulo Supervision

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)

Valida parámetro name
Si viene vacío, retorna error utilizando responseValidate().
Obtiene todas las categorías asociadas al checklist
Usa:

listCategory($request)
Valida respuesta de categorías
- Si ocurre error → retorna mensaje de fallo.
- Si la data viene vacía → indica que no existen registros creados.
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)
Consulta información de cabecera del checklist en ERP

Realiza:

GET Check List del Supervisor Nacional 2?filters=[["name","=",<name>]]

Campos obtenidos:
- sucursal
- fecha
- name
Agrega métricas calculadas al resultado:
- all_progress
- all_point
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

Módulo Supervision

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:

Lee la estructura del DocType para identificar:
- Secciones (categorías).
- Preguntas tipo Check, Data, Attach Image.
Recupera los valores reales del documento filtrado por name.
Agrupa los campos por categoría.
Calcula el avance (%) y puntaje por sección.
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 fields
categorias = {}

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 documento
values = GET Check List del Supervisor Nacional 2 where name = request.name

# Agrupar valores por categoría
foreach categoria in categorias:
    newQuestions[categoria] = tomar valores según fieldname


# Calcular porcentaje y puntaje
foreach categoria in newQuestions:
    total = count(fields) / 3
    completos = fields con valor 1
    puntaje = completos * 1.82

    agregar resultado al response

Módulo Supervision

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

Módulo Supervision

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:

Obtiene toda la estructura de campos del Doctype.
Identifica qué campos pertenecen a cada categoría (Section Break).
Filtra únicamente los campos tipo:
- Check
- Data (comentado actualmente)
- Attach Image (comentado actualmente)
Consulta los valores reales del formulario (0 o 1).
Determina qué preguntas están completas o incompletas.
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)

Validación de parámetros
Si name o category vienen vacíos → error inmediato.
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.
Agrupar preguntas por categoría
- Mapea category → lista de campos (fieldname → label).
Construir lista total de fields para consultar sus valores
Ejemplo:

["documentos_autoridades", "imagen_14", "comentario_14", ...]
Consultar valores reales del registro
GET /resource/Check List del Supervisor Nacional 2?fields=[...]&filters=[["name","=",name]]
Clasificar por categoría:
- Si campo = 0 → Incompleta
- Si campo = 1 → Completa
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

Módulo Supervision

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)

Captura el archivo enviado en $_FILES["file"].
Crea un objeto CURLFile con:
- ruta temporal (tmp_name)
- tipo MIME
- nombre original
Envía el archivo al endpoint:

POST /method/upload_file
Espera la respuesta del ERP.
Decodifica la respuesta JSON.
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

Módulo Supervision

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)

Valida parámetros obligatorios
Si questions o name viene vacío, retorna error de validación.
Valida que existan cambios reales
Si questions == '{}', se considera que no hubo modificación.
Convierte a array el JSON recibido

$questions = json_decode($questionsForm, true);
Genera el payload a actualizar
Todos los campos recibidos se envían directamente al ERP.
Realiza la actualización mediante API ERP

PUT resource/Check List del Supervisor Nacional 2/{name}
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.questions
name = request.name

if questionsForm empty → return error
if name empty → return error

if questionsForm == "{}" → return "no hizo cambios"

questions = decode(questionsForm)
fields = questions

update = PUT /resource/Check List del Supervisor Nacional 2/{name} with fields

if update fails → return error

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

Recibe el número de documento del usuario.
Genera un código aleatorio numérico de 6 dígitos.
Envía ese código al servicio https://sistema.shalomcontrol.com/api/generate_code_two_factor.
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)

Valida que el request incluya username.
- Si no existe, retorna error.
Genera un código numérico aleatorio de 6 dígitos, cada uno seleccionado de "0123456789".
Envía el código al servicio:

POST https://sistema.shalomcontrol.com/api/generate_code_two_factor

Con los parámetros:

document = <username> code = <6-digit code>
Recibe y retorna la respuesta proporcionada por el servicio externo.
Si ocurre un error en la solicitud HTTP (BadResponseException), devuelve:

📤 Response 200 – Ejemplo

(La estructura exacta depende del servicio externo sistema.shalomcontrol.com.)