Recurso: Conceptos de Retenciones

Tabla: boniret

---

1. Propósito

Este recurso gestiona los conceptos de retenciones que pueden ser aplicados en diversas transacciones financieras, como la generación de recibos de pago. Permite definir y configurar diferentes tipos de deducciones que afectan los montos finales de las operaciones.

El objetivo principal es centralizar la administración de estas retenciones, asegurando que se apliquen de manera consistente y correcta en todo el sistema.

---

2. Atributos de la Entidad

Cada concepto de retención se define por los siguientes atributos:

Atributo	Descripción
Nombre	Un identificador textual breve y único para el concepto (ej: "IIBB", "Ganancias", "SUSS").
Cuenta Contable	El número de la cuenta contable asociada a la que se imputará la retención.
Valor	El monto o porcentaje a aplicar. Puede ser un valor fijo o un porcentaje.
Tipo de Cálculo	Define si el Valor se interpreta como un porcentaje (%) o un monto fijo ($).
Es Impuesto o Servicio	Un indicador para clasificar si la retención corresponde a impuestos y servicios, o no.
Acumulable	Determina si el cálculo de esta retención se suma a otras retenciones aplicadas en la misma transacción.

---

3. Operaciones del Recurso

La API debe permitir la gestión completa del ciclo de vida de los conceptos de retenciones a través de las siguientes operaciones:

Operación	Verbo HTTP	Descripción
Listar Conceptos	GET	Devuelve una lista de todos los conceptos de retenciones activos. Permite filtrar los resultados por Tipo de Cálculo, si es Impuesto o Servicio y si es Acumulable.
Obtener un Concepto	GET /{id}	Recupera la información detallada de un único concepto de retención a partir de su identificador.
Crear un Concepto	POST	Registra un nuevo concepto de retención en el sistema.
Actualizar un Concepto	PUT /{id}	Modifica los atributos de un concepto de retención existente.
Eliminar un Concepto	DELETE /{id}	Desactiva un concepto de retención (mediante borrado lógico o soft delete) para que no pueda ser utilizado en nuevas transacciones.

---

4. Reglas de Negocio y Validaciones

Para garantizar la integridad de los datos, el sistema debe aplicar las siguientes reglas:

• Unicidad del Nombre: No pueden existir dos conceptos de retención activos con el mismo Nombre.
• Validación de Cuenta Contable: La Cuenta Contable proporcionada debe existir y ser válida dentro del plan de cuentas de la empresa.
• Consistencia del Valor:
  • Si el Tipo de Cálculo es porcentaje, el Valor debe estar en un rango válido (ej: entre 0 y 100).
  • Si el Tipo de Cálculo es fijo, el Valor debe ser un número positivo.
• Integridad Referencial: Un concepto de retención no puede ser eliminado si ya ha sido utilizado en transacciones existentes (como recibos de pago). Solo se permitirá su desactivación.

---

5. Consideraciones Adicionales

• Consistencia de Datos: Las operaciones que modifican la base de datos (crear, actualizar, eliminar) deben ejecutarse dentro de transacciones para asegurar la atomicidad y la consistencia de los datos.
• Borrado Lógico (Soft Delete): La eliminación de un concepto debe ser lógica. El registro debe ser marcado como inactivo en lugar de ser borrado físicamente, preservando así la integridad de los datos históricos.

---

6. Pendientes de Implementación

Tests de Integración

Descripción: Actualmente solo existen tests unitarios del Service layer. Se requiere implementar tests de integración que validen:

Documentación OpenAPI/Swagger

Descripción: Se requiere documentar la API REST del recurso usando especificación OpenAPI 3.0 para:

• Generar documentación interactiva
• Facilitar integración con clientes
• Validar contratos de API