General

Perfil

Inicio

Resumen Funcional por Caso de Uso

1. Autenticación (AuthenticationUseCase)

Gestiona el acceso de usuarios mediante un servicio de autenticación externo (RPC). Soporta login con credenciales, renovación de tokens, verificación de tokens de registro y verificación de códigos temporales. Incluye modo super-admin con credenciales configuradas por entorno.

2. Condominios (CondominiumUseCase)

CRUD de condominios. Los usuarios pueden listar sus condominios asociados. Los administradores pueden actualizar datos del condominio y gestionar metadatos configurables (logo, dirección, contacto, etc.).

3. Usuarios (UserUseCase + UserFinderUseCase)

Gestión completa del ciclo de vida de usuarios: registro, invitación por email, actualización de perfil, recuperación y reseteo de contraseña, activación/desactivación. Los administradores pueden buscar usuarios con filtros paginados y reenviar invitaciones. Valida pertenencia de usuarios a condominios.

4. Propiedades (PropertyUseCase)

Gestión de propiedades dentro de un condominio. Permite buscar propiedades con filtros paginados, asignar propietarios (creando el vínculo condominio-usuario si no existe), registrar pagos manuales y generar facturas en PDF. Envía notificaciones por email al propietario tras un pago.

5. Carga Masiva de Propiedades (PropertyBulkloadUseCase)

Módulo para cargar propiedades de forma masiva mediante archivos XLSX. (En desarrollo)

6. Configuración de Gastos Comunes (CommonExpenseConfigurationUseCase)

Permite a los administradores definir configuraciones de gastos comunes por condominio: montos, rangos de año, fechas de inicio. Valida que no se solapen configuraciones existentes y que los montos sean positivos.

7. Gastos Comunes por Propiedad (CommonExpensePropertyUseCase)

Núcleo del cálculo de gastos comunes. Calcula el monto a pagar incluyendo: configuraciones base, intereses por mora, acuerdos de pago y ajustes de saldo. Gestiona la creación de registros de gastos comunes, acuerdos de pago en cuotas, y el estado de deuda de cada propiedad (meses atrasados, meses pendientes, al día).

8. Pagos (PropertyPaymentUseCase)

Gestión integral de pagos: consulta con filtros paginados, búsqueda por ID y por propiedad, descarga de reportes en XLSX, cancelación de pagos pendientes (eliminando gastos comunes asociados) y anulación por administradores. Valida permisos de usuario sobre cada pago.

9. Pagos de Terceros (ThirdPartyPaymentUseCase)

Integración con pasarelas de pago externas (Transbank). Genera URLs de redirección para pagos de terceros, procesa webhooks de confirmación/annulación verificando firmas HMAC-SHA256, y actualiza el estado de los pagos según la respuesta de la pasarela.

10. Dashboard (DashboardUseCase)

Panel de estadísticas para administradores. Genera datos para gráficos de 12 meses y 4 tarjetas resumen: total pagado, pagos autogestionados, dinero entrante del mes (con comparación porcentual vs mes anterior) y usuarios activos.

11. Depósitos de Gastos Comunes (CommonExpenseDepositUseCase)

Permite a los administradores registrar abonos (depósitos) para el pago de gastos comunes de una propiedad. El monto se aplica primero como crédito acumulado y cuando cubre un período completo, crea el registro correspondiente del gasto común. Envía notificación por email al propietario. Devuelve el resultado con información del crédito acumulado y si cubrió o no el período actual.

12. Suscripciones (SubscriptionUseCase)

Gestión de suscripciones de condominios a la plataforma. Permite buscar suscripciones por condominio, crear nuevas suscripciones vía pago, cancelar suscripciones, consultar el estado de pago del usuario y calcular montos a pagar. Incluye manejo de errores de transacciones de pago.

13. Planes de Suscripción (SubscriptionPlanUseCase)

Gestión de los planes de suscripción disponibles en la plataforma. Permite listar todos los planes configurados para que los administradores puedan consultar las opciones disponibles.

14. Notificaciones (NotificationUseCase)

Envío y gestión de notificaciones por email: invitaciones a nuevos usuarios, confirmaciones de pago de propiedades, y notificaciones generales del sistema.

15. Control de Acceso (AccessControlUseCase)

Registro de entrada y salida de vehículos en el condominio. Gestiona vehículos por patente, crea registros de acceso con detalle y genera reportes en XLSX.

Documentación Técnica de la API

Autenticación — /v1/auth

Método Path Descripción Request Response
POST /login Login de usuario LoginRequest LoginResponse (token, userId, roleName)

Usuarios — /v1/users

Método Path Descripción Request Response
GET /{id} Obtener usuario por ID PathParam: id UserResponse
GET /search Buscar usuarios UserFinderRequest (query params) Pagination<UserResponse>
GET ?email={email} Buscar usuario por email QueryParam: email UserResponse
PUT /update-password Actualizar contraseña PasswordUpdateRequest -
PUT /deactivate/{id} Desactivar usuario PathParam: id -
GET /complete/{tenantId} Redirigir a completar registro PathParam: tenantId -
POST /password-recovery Solicitar recuperación de contraseña PasswordRecoveryRequest -
PATCH /reset-password Resetear contraseña ResetPasswordRequest -

Condominios — /v1/condominium

Método Path Descripción Request Response Seguridad
GET /search Buscar condominios CondominiumFinderRequest (query params) Paginado -
GET ?userId={userId} Listar condominios del usuario QueryParam: userId List<CondominiumResponse> -
GET /{id} Obtener condominio por ID PathParam: id CondominiumResponse user, admin
PUT / Actualizar condominio CondominiumRequest - admin
POST /metadata/{condominiumId} Agregar/actualizar metadatos PathParam + List<MetadataRequest> - admin

Propiedades — /v1/property

Método Path Descripción Request Response
GET /{propertyId} Obtener propiedad por ID PathParam: propertyId PropertyResponse
GET / Buscar propiedades con filtros Query params (condominiumId, number, street, userId, page, rowsPerPage) Paginado
POST /owner Actualizar propietario UpdateOwnerRequest -
POST /payment Registrar pago de propiedad Payment - (201)
GET /invoice/{id} Descargar factura PDF PathParam: id PDF binary

Pagos — /v1/payment

Método Path Descripción Request Response
GET / Buscar pagos con filtros PaymentFinderRequest (query params) Paginado
GET /download Descargar reporte de pagos QueryParams: condominiumId, from, to XLSX binary
GET /{id} Obtener pago por ID PathParam: id PaymentResponse
GET /last/{propertyId} Último pago de propiedad PathParam: propertyId PaymentResponse
PUT /cancel/{id} Cancelar pago PathParam: id -
PUT /delete/{id} Anular pago (admin) PathParam: id -

Pagos de Terceros — /v1/third-party-payment

Método Path Descripción Request Response
GET /properties/{paymentId} Obtener URL de pago externo PathParam: paymentId {"url":"..."}
POST /properties Confirmar/anular pago de propiedad ConfirmPaymentRequest ConfirmThirdPartyPaymentResponse
POST /subscription Confirmar/anular pago de suscripción ConfirmPaymentRequest ConfirmThirdPartyPaymentResponse

Gastos Comunes por Propiedad — /v1/common-expense-property

Método Path Descripción Request Response
POST /amount Calcular monto a pagar GetAmountToPayRequest AmountToPayResponse
POST /agreement Registrar acuerdo de pago PropertyAgreementRequest - (201)
POST /agreement/amount Calcular monto de acuerdo GetAmountToPayForAgreementRequest AmountToPayResponse
POST / Crear gasto común de propiedad NewCommonExpensePropertyRequest - (201)
GET /last/{propertyId} Último gasto común de propiedad PathParam: propertyId CommonExpensePropertyResponse
GET /status/{propertyId} Estado de gastos de propiedad PathParam: propertyId CommonExpensePropertyStatusResponse

Configuración de Gastos Comunes — /v1/common-expense-configuration

Método Path Descripción Request Response
GET ?condominiumId={id} Listar configuraciones QueryParam: condominiumId List<CommonExpenseConfigurationResponse>
POST / Crear configuración CommonExpenseConfigurationRequest - (201)

Dashboard — /v1/dashboard

Método Path Descripción Request Response
GET /{condominiumId} Obtener datos del dashboard PathParam: condominiumId DashboardResponse

Depósitos — /v1/common-expense-property/deposit

Método Path Descripción Request Response Seguridad
POST /deposit Registrar depósito/abono DepositRequest DepositResult admin

Suscripciones — /v1/subscriptions

Método Path Descripción Request Response Seguridad
GET /{condominiumId} Obtener suscripción del condominio PathParam: condominiumId Subscription user, admin, platform_admin
GET /search Buscar suscripciones con filtros Query params (page, pageSize, criteria) Pagination<Subscription> user, admin, platform_admin
PUT /cancel/{subscriptionId} Cancelar suscripción PathParam: subscriptionId - admin, platform_admin
POST / Crear nueva suscripción Long (condominiumId) String (payment URL/ID) admin, platform_admin
POST /confirm Confirmar/cancelar pago de suscripción PaymentConfirmationDto void -
GET /payment-status/{userId} Estado de pago del usuario PathParam: userId {"inPaymentRange": boolean} admin, platform_admin
GET /amount-to-pay/{userId} Monto a pagar por suscripción PathParam: userId BigDecimal admin, platform_admin

Planes de Suscripción — /v1/plans

Método Path Descripción Request Response Seguridad
GET / Listar planes disponibles - List<SubscriptionPlan> admin, platform_admin

Health Check — /v1/health

Método Path Descripción Response
GET / Estado del servicio {"status": "UP"}

Variables de Entorno

Variable Descripción Default
SERVER_PORT Puerto del servidor 8080
ENV Entorno (local/staging/prod) local
APP_VERSION Versión de la aplicación 1.0.0
DB_HOST Host de PostgreSQL localhost
DB_PORT Puerto de PostgreSQL 5432
DB_NAME Nombre de la base de datos condominium_api
DB_USER Usuario de la base de datos -
DB_PASSWORD Contraseña de la base de datos -
REDIS_HOST Host de Redis localhost
REDIS_PORT Puerto de Redis 6379
JWT_PUBLIC_KEY Clave pública JWT -
JWT_PRIVATE_KEY Clave privada JWT -
TBK_API_KEY_ID API Key ID de Transbank -
TBK_API_KEY_SECRET API Key Secret de Transbank -
TBK_RETURNER_URL URL de retorno Transbank -
PAYMENT_SUCCESS_URL URL de pago exitoso -
AKEYLESS_USER Usuario de Akeyless (vault) -
AKEYLESS_PASSWORD Contraseña de Akeyless -

Docker

Build de imagen

./gradlew build
docker build -t residefacil-api .

Ejecutar contenedor

docker run -p 8080:8080 \
  -e DB_HOST=host.docker.internal \
  -e DB_USER=postgres \
  -e DB_PASSWORD=secret \
  -e REDIS_HOST=host.docker.internal \
  residefacil-api

Perfiles de Ejecución

Perfil Descripción
dev Desarrollo con DevServices (PostgreSQL/Redis en Docker), Swagger UI habilitado
test Testing con Flyway desactivado, Hibernate drop-and-create
staging Staging, Swagger UI deshabilitado
prod Producción, Swagger UI deshabilitado 
./gradlew quarkusDev -Dquarkus.profile=staging