SDK para Gestión de Pensiones (mbcj-pensiones-sdk)

Este SDK (mbcj-pensiones-sdk) está diseñado para facilitar la interacción con la API del sistema de gestión de pensiones. Proporciona una capa de abstracción en JavaScript, construida con un enfoque en la robustez, consistencia y facilidad de uso, permitiendo a los desarrolladores integrar funcionalidades clave en sus aplicaciones cliente de manera eficiente.

El SDK utiliza un patrón singleton, lo que significa que se inicializa una única vez y su instancia puede ser utilizada a lo largo de toda la aplicación.

✨ Características Principales

El SDK ofrece un conjunto de módulos para gestionar las entidades principales del sistema:

• Personas: Gestión de datos personales, incluyendo:
  • CRUD de información de personas.
  • Administración de Contactos (teléfonos, correos).
  • Gestión de Domicilios.
  • Manejo de Vínculos familiares o de otro tipo entre personas.
• Pensiones: Administración completa de los expedientes de pensiones, abarcando:
  • Creación, consulta y actualización de pensiones.
  • Gestión de bajas y cambios de estado.
  • Manejo de suspensiones de beneficios.
  • Asociación de documentación a los expedientes.
• Obras Sociales: Administración de las obras sociales asociadas a una pensión.
• Restricciones: Gestión de restricciones judiciales o administrativas sobre las personas.
  • Asignación de sistemas de apoyo a una restricción.
• Usuarios: Administración de los usuarios del sistema.
• Tipos y Maestros: Consulta y gestión de los datos maestros del sistema, tales como:
  • Tipos de Pensiones, Obras Sociales, Vínculos.
  • Motivos de Baja o Suspensión.
  • Listado de Localidades.

architectural-improvements-icon Arquitectura y Mejoras Clave

Este SDK ha sido estructurado siguiendo las mejores prácticas para asegurar su calidad y mantenibilidad:

• Manejo de Errores Consistente: Todas las funciones asíncronas devuelven Promesas que, en caso de error, siempre son rechazadas con un objeto Error. Esto garantiza que el stack trace se preserve y que la depuración sea predecible, utilizando el mensaje de la API si está disponible.
• Validación de Entrada Robusta: Cada método incluye validaciones estrictas de los parámetros de entrada antes de realizar una llamada a la API. Esto previene el envío de datos inválidos o malformados, ahorrando recursos y proporcionando feedback inmediato al desarrollador.
• Estructura Modular Clara: La nomenclatura de archivos coincide con las clases que exportan (ej. pension/Pension.js), lo que facilita la navegación y la comprensión del código fuente.
• Singleton Simplificado: El punto de entrada del SDK (index.js) utiliza una implementación de singleton limpia y moderna, evitando código redundante y facilitando su uso.

🛠️ Tecnologías y Dependencias

• Node.js: Entorno de ejecución de JavaScript.
• axios: Cliente HTTP basado en promesas para realizar las solicitudes a la API.
• Jest & axios-mock-adapter: Para la ejecución de pruebas unitarias.

Para ver la lista completa de dependencias, consulta el archivo package.json.

🚀 Instalación

Para instalar mbcj-pensiones-sdk en tu proyecto (que debe estar configurado como un ES Module), ejecuta el siguiente comando:

npm install mbcj-pensiones-sdk

💡 Uso

El SDK se exporta como un singleton. Debes inicializarlo una sola vez en tu aplicación con la URL base de la API.

1. Inicialización

En el punto de entrada de tu aplicación (por ejemplo, main.js o app.js), importa e inicializa el SDK.

// Importa la instancia del SDK
import api from 'mbcj-pensiones-sdk';

// Define la URL base de tu API de pensiones
const API_BASE_URL = 'http://localhost:5018/api'; // Reemplaza con la URL de tu backend

// Inicializa el SDK. Esto debe hacerse solo una vez.
try {
  api.init(API_BASE_URL);
  console.log('SDK inicializado correctamente.');
} catch (error) {
  // El error se lanzará si intentas inicializarlo más de una vez.
  console.error(error.message);
}

2. Autenticación

Si tu API requiere un token de autenticación (ej. JWT), puedes configurarlo una vez que el usuario haya iniciado sesión. El SDK lo incluirá automáticamente en todas las solicitudes posteriores.

import api from 'mbcj-pensiones-sdk';

const authToken = 'TU_TOKEN_DE_AUTENTICACION_JWT'; // Obtén el token después del login
api.setToken(authToken);

3. Manejo de Errores

Gracias al manejo de errores estandarizado, siempre recibirás un objeto Error en tus bloques catch.

import api from 'mbcj-pensiones-sdk';

async function obtenerDetallesDePersona(personaId) {
  try {
    const { persona } = await api.persona.obtenerDetalles(personaId);
    return persona;
  } catch (error) {
    // 'error' siempre será una instancia de Error
    console.error(`Error al obtener la persona: ${error.message}`);
    // Maneja el error apropiadamente en tu UI
    return null;
  }
}

📚 Referencia de la API (Módulos del SDK)

A continuación se listan los principales módulos y métodos disponibles.

api.persona

Gestiona la información de las personas.

• obtener(params): Busca personas. params puede incluir { busqueda, limit, offset }.
• obtenerDetalles(persona_id): Obtiene los datos completos de una persona.
• guardar(datosPersona): Crea una nueva persona.
• actualizar(persona_id, datosPersona): Actualiza los datos de una persona.
• Sub-módulos:
  • api.persona.contacto: guardar(datosContacto), anular(contacto_id).
  • api.persona.domicilio: guardar(datosDomicilio), anular(domicilio_id).
  • api.persona.vinculo: obtener(persona_id), guardar(datosVinculo), eliminar(vinculo_id).

api.pension

Administra los expedientes de pensiones.

• obtener(params): Busca pensiones. params puede incluir { busqueda, limit, offset }.
• obtenerPension(pension_id): Obtiene el detalle de una pensión.
• guardar(datosPension): Crea un nuevo registro de pensión.
• actualizar(pension_id, datosPension): Actualiza una pensión.
• cambiarEstado(pension_id, estado): Cambia el estado de una pensión.
• baja(pension_id, datosBaja): Registra la baja de una pensión.
• Sub-módulos:
  • api.pension.documentacion: guardar(datosDocumentacion), eliminar(documentacion_id).
  • api.pension.suspension: suspender(datosSuspension), quitar(suspension_id, fecha_fin).

api.obraSocial

Gestiona las obras sociales asociadas a una pensión.

• guardar(datosObraSocial): Asocia una obra social a una pensión.
• eliminar(obra_social_id, fecha_fin): Da de baja la cobertura de una obra social.

api.restriccion

Administra las restricciones sobre personas.

• obtener(params): Busca restricciones. params puede incluir { busqueda, limit, offset }.
• guardar(datosRestriccion): Crea una nueva restricción.
• eliminar(restriccion_id, { fecha_fin }): Finaliza una restricción.
• Sub-módulos:
  • api.restriccion.sistemaApoyo: obtener(restriccion_id), guardar(datosSistemaApoyo), eliminar(sistema_apoyo_id, { fecha_fin }).

api.usuario

Gestiona los usuarios del sistema.

• obtenerUsuarios(params): Busca usuarios. params puede incluir { busqueda, limit, offset }.
• crearUsuario(datosUsuario): Crea un nuevo usuario.
• actualizarUsuario(usuario_id, datosUsuario): Actualiza un usuario.
• cambiarEstadoUsuario(usuario_id, activo): Activa o desactiva un usuario.

api.tipo

Gestiona los datos maestros (catálogos) del sistema.

• api.tipo.localidades: obtener().
• api.tipo.obrasSociales: obtener(), guardar(datos), actualizar(id, datos).
• api.tipo.pensiones: obtener(), guardar(datos), actualizar(id, datos).
• api.tipo.vinculos: obtener(), guardar(datos), actualizar(id, datos).
• Sub-módulos de Motivos:
  • api.tipo.motivos.baja: obtenerTodos(), guardar(datos), actualizar(id, datos).
  • api.tipo.motivos.suspension: obtenerTodos(), guardar(datos), actualizar(id, datos).

📧 Contacto

Para cualquier consulta, sugerencia o problema con el SDK, puedes contactar a:

• Damián E. Greco - [email protected]