Lluquino/ContabilidadSaPolar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0d5c6f9512990f3357ea0af1e2a68513cdf7483c
ContabilidadSaPolar/docs/tecnicas/api.md
T

12 KiB
Raw Blame History

Referencia de la API REST

Formato General

Todas las respuestas siguen el formato ApiResponse<T>:

{
  "success": true,
  "message": "OK",
  "data": { ... },
  "timestamp": "2026-07-04T12:00:00"
}

Los errores usan el mismo formato con success: false y mensaje descriptivo.

Autenticación

POST /api/auth/login

Iniciar sesión.

Request body:

{
  "username": "admin",
  "password": "admin123"
}

Response (200):

{
  "success": true,
  "message": "OK",
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "tokenType": "Bearer",
    "userId": 1,
    "username": "admin",
    "role": "ADMIN"
  }
}

POST /api/auth/register

Registrar nuevo usuario.

Request body:

{
  "username": "usuario1",
  "email": "user@example.com",
  "password": "password123",
  "fullName": "Usuario Ejemplo",
  "phone": "600123456",
  "roleName": "GERENTE"
}

POST /api/auth/refresh

Renovar token de acceso.

Request body:

{
  "refreshToken": "eyJhbGciOi..."
}

Usuarios (solo ADMIN)

Método Ruta Descripción
GET /api/users Listar todos los usuarios
GET /api/users/{id} Obtener usuario por ID
PUT /api/users/{id} Actualizar usuario
DELETE /api/users/{id} Desactivar usuario (soft-delete)

Propiedades

Método Ruta Descripción
GET /api/properties Listar propiedades activas
GET /api/properties/tree Obtener propiedades raíz (sin padre)
GET /api/properties/{id}/children Obtener hijos de una propiedad
GET /api/properties/{id} Obtener propiedad por ID
POST /api/properties Crear propiedad
PUT /api/properties/{id} Actualizar propiedad
PATCH /api/properties/{id}/status Cambiar estado de propiedad
GET /api/properties/{id}/history Historial de cambios de estado
DELETE /api/properties/{id} Eliminar propiedad (soft-delete)
GET /api/properties/types Listar tipos de propiedad
GET /api/properties/statuses Listar estados de propiedad

Estructura de Property:

{
  "id": 1,
  "parent": null,
  "group": { "id": 1, "name": "Residencial Centro" },
  "type": { "id": 2, "name": "PISO", "description": "Vivienda..." },
  "status": { "id": 2, "name": "ALQUILADO", "description": "..." },
  "reference": "PIS-001",
  "name": "Piso Centro",
  "addressStreet": "Calle Mayor",
  "addressNumber": "12",
  "addressCity": "Madrid",
  "addressPostalCode": "28001",
  "addressProvince": "Madrid",
  "cadastralRef": "1234567VK1234A",
  "surfaceM2": 85.50,
  "floor": "3",
  "door": "A",
  "rentalAmount": 850.00,
  "active": true
}

Conjuntos (Property Groups)

Método Ruta Descripción
GET /api/property-groups Listar todos los conjuntos
GET /api/property-groups/{id} Obtener conjunto por ID
POST /api/property-groups Crear conjunto
PUT /api/property-groups/{id} Actualizar conjunto
DELETE /api/property-groups/{id} Eliminar conjunto
GET /api/property-groups/{id}/properties Propiedades pertenecientes al conjunto

Estructura de PropertyGroup:

{
  "id": 1,
  "name": "Residencial Centro",
  "addressStreet": "Calle Mayor",
  "addressNumber": "10",
  "addressCity": "Madrid",
  "addressPostalCode": "28001",
  "isActive": true
}

Inquilinos

Método Ruta Descripción
GET /api/tenants?search= Listar/buscar inquilinos
GET /api/tenants/{id} Obtener inquilino por ID
POST /api/tenants Crear inquilino
PUT /api/tenants/{id} Actualizar inquilino
DELETE /api/tenants/{id} Eliminar inquilino (soft-delete)

Contratos

Método Ruta Descripción
GET /api/contracts?propertyId=&tenantId= Listar/filtrar contratos
GET /api/contracts/{id} Obtener contrato por ID
POST /api/contracts Crear contrato (auto: propiedad → ALQUILADO)
PUT /api/contracts/{id} Actualizar contrato
POST /api/contracts/{id}/terminate Terminar contrato (auto: propiedad → VACIO)

Recibos de Ingresos (Income Receipts)

Método Ruta Descripción
GET /api/income-receipts?propertyId=&contractId=&from=&to=&statusId= Listar/filtrar recibos de ingresos
GET /api/income-receipts/pending Total pendiente de cobro
GET /api/income-receipts/{id} Obtener recibo por ID
POST /api/income-receipts Crear recibo
PUT /api/income-receipts/{id} Actualizar recibo
PATCH /api/income-receipts/{id}/pay Registrar pago
DELETE /api/income-receipts/{id} Eliminar recibo

Plantillas de Gastos (Expense Templates)

Método Ruta Descripción
GET /api/expense-templates?propertyId=&categoryId= Listar/filtrar plantillas
GET /api/expense-templates/active Plantillas activas
GET /api/expense-templates/{id} Obtener plantilla por ID
POST /api/expense-templates Crear plantilla
PUT /api/expense-templates/{id} Actualizar plantilla
PATCH /api/expense-templates/{id}/toggle Activar/desactivar plantilla
POST /api/expense-templates/{id}/generate Generar recibo de gasto desde plantilla
DELETE /api/expense-templates/{id} Eliminar plantilla

Recibos de Gastos (Expense Receipts)

Método Ruta Descripción
GET /api/expense-receipts?propertyId=&templateId=&from=&to=&statusId= Listar/filtrar recibos de gastos
GET /api/expense-receipts/{id} Obtener recibo por ID
POST /api/expense-receipts Crear recibo manual
PUT /api/expense-receipts/{id} Actualizar recibo
PATCH /api/expense-receipts/{id}/pay Registrar pago
DELETE /api/expense-receipts/{id} Eliminar recibo

Incidencias

Método Ruta Descripción
GET /api/incidents?propertyId=&statusId= Listar/filtrar incidencias
GET /api/incidents/{id} Obtener incidencia por ID
POST /api/incidents Crear incidencia
PATCH /api/incidents/{id}/status Actualizar estado
PATCH /api/incidents/{id}/assign Asignar técnico
PATCH /api/incidents/{id}/schedule Programar reparación
DELETE /api/incidents/{id} Eliminar incidencia

Flujo de estados de incidencia: SIN_REVISAR → TECNICO_AVISADO → REPARACION_PREVISTA → REPARADO → IGNORADO → ANULADO

Mantenimiento Programado

Método Ruta Descripción
GET /api/maintenance?propertyId= Listar mantenimientos
GET /api/maintenance/pending Mantenimientos pendientes
GET /api/maintenance/upcoming?from=&to= Próximos mantenimientos
GET /api/maintenance/{id} Obtener por ID
POST /api/maintenance Crear mantenimiento
PUT /api/maintenance/{id} Actualizar
PATCH /api/maintenance/{id}/complete Marcar completado
DELETE /api/maintenance/{id} Eliminar

Recibos

Método Ruta Descripción Rol
GET /api/receipts Listar recibos ADMIN, GERENTE, CONTABLE
GET /api/receipts/{id} Obtener recibo ADMIN, GERENTE, CONTABLE
POST /api/receipts/generate Generar recibo individual ADMIN, GERENTE, CONTABLE
POST /api/receipts/generate-monthly Generar recibos mensuales ADMIN
GET /api/receipts/{id}/pdf Descargar PDF ADMIN, GERENTE, CONTABLE
POST /api/receipts/{id}/send-email Enviar por email ADMIN, GERENTE, CONTABLE
GET /api/receipts/reports/monthly?year=&month= Reporte Excel mensual ADMIN, GERENTE, CONTABLE

POST /api/receipts/generate

Genera un recibo individual para un contrato específico.

Request body:

{
  "contractId": 1,
  "issueDate": "2026-07-01",
  "dueDate": "2026-07-15",
  "description": "Alquiler julio 2026"
}

POST /api/receipts/generate-monthly

Genera recibos para todos los contratos activos cuyo payment_day coincida con el mes actual. Solo ADMIN.

GET /api/receipts/{id}/pdf

Devuelve el PDF del recibo como application/pdf con header Content-Disposition: attachment; filename="recibo-R-2026-00001.pdf".

POST /api/receipts/{id}/send-email

Envía el recibo por email al inquilino con el PDF adjunto.

GET /api/receipts/reports/monthly?year=2026&month=7

Descarga un informe Excel (.xlsx) con el resumen de recibos de ingresos, recibos de gastos y balance del mes.

Notificaciones

Método Ruta Descripción
GET /api/notifications?unreadOnly=true Listar notificaciones del usuario
GET /api/notifications/unread-count Contar no leídas
PATCH /api/notifications/{id}/read Marcar como leída
PATCH /api/notifications/read-all Marcar todas como leídas

Dashboard

Método Ruta Descripción
GET /api/dashboard/summary Resumen general (contadores, YTD)
GET /api/dashboard/income-expense?year=2026 Ingresos/gastos mensuales del año

Respuesta de /summary:

{
  "success": true,
  "data": {
    "totalProperties": 10,
    "rentedProperties": 5,
    "activeContracts": 5,
    "totalTenants": 8,
    "openIncidents": 2,
    "pendingMaintenance": 1,
    "incomeYtd": 42500.00,
    "expenseYtd": 12300.00,
    "pendingIncome": 2850.00
  }
}

Documentos

Método Ruta Descripción
POST /api/documents/upload Subir archivo (multipart)
GET /api/documents/entity/{entityType}/{entityId} Documentos de una entidad
GET /api/documents/types-for-entity/{entityType} Tipos de documento permitidos para una entidad
GET /api/documents/search Búsqueda avanzada con filtros
GET /api/documents/{id}/download Descargar documento
DELETE /api/documents/{id} Eliminar documento
GET /api/documents/{id}/entities Ver entidades asociadas a un documento
POST /api/documents/{id}/entities Asociar documento a otra entidad
DELETE /api/documents/{id}/entities/{entityType}/{entityId} Desasociar documento de una entidad

Tipos de entidad soportados: PROPERTY, CONTRACT, TENANT, INCIDENT, MAINTENANCE

Upload params: file (multipart), entityType, entityId, documentTypeId, description (opcional)

GET /api/documents/types-for-entity/{entityType}

Devuelve los tipos de documento permitidos para una entidad, indicando cuáles son obligatorios.

Response (200):

{
  "success": true,
  "data": [
    {
      "documentTypeId": 1,
      "documentTypeName": "CONTRATO",
      "canUpload": true,
      "mustHave": true,
      "description": "Documento principal del contrato de alquiler"
    },
    {
      "documentTypeId": 10,
      "documentTypeName": "OTRO",
      "canUpload": true,
      "mustHave": false,
      "description": "Otros documentos del contrato"
    }
  ]
}

Códigos de Error

Código Significado
200 OK
201 Creado
400 Bad Request (validación, datos incorrectos)
401 No autenticado
403 No autorizado (rol insuficiente)
404 Recurso no encontrado
409 Conflicto (duplicado)
500 Error interno del servidor

Documentación Interactiva (Swagger)

Disponible en http://localhost:8080/swagger-ui.html cuando el backend está corriendo. También se puede obtener el spec OpenAPI en http://localhost:8080/api-docs.

Reference in New Issue View Git Blame Copy Permalink