Fee management sits at the heart of Comunidades Vecinos. When an ADMIN creates a fee (Documentation Index
Fetch the complete documentation index at: https://mintlify.com/GuillermoNavarro/Proyecto_comunidades/llms.txt
Use this file to discover all available pages before exploring further.
Cuota), the platform automatically generates individual receipts (Recibo) for every active resident in the community, applying each resident’s ownership share (coeficiente) to calculate the exact amount due. This eliminates manual data entry and ensures every resident always has a corresponding payment record.
Fee Types
TheTipoCuota enum defines three kinds of fees:
ORDINARIA
Regular recurring fee. Used for monthly or quarterly community charges that apply to all residents equally in proportion to their
coeficiente. Example: monthly maintenance contribution.EXTRAORDINARIA
One-time special assessment. Applied to the whole community for unplanned expenses such as a major repair or emergency fund top-up. Receipts are still generated for every active resident based on their
coeficiente.INDIVIDUAL
Single-resident charge. Assigned to one specific user, bypassing the community-wide distribution. The full
importe of the fee is assigned to that resident (equivalent to a coeficiente of 100%). Requires the ?idUsuario= query parameter on creation.The Cuota Entity
| Field | Column | Type | Description |
|---|---|---|---|
id | id_cuota | Long (auto) | Primary key |
nombre | nombre | String | Descriptive name of the fee |
fechaEmision | fecha_emision | LocalDate | Date the fee was issued |
fechaVencimiento | fecha_vencimiento | LocalDate | Payment due date |
importe | importe_total | BigDecimal | Total fee amount in euros |
tipo | tipo | TipoCuota enum | ORDINARIA, EXTRAORDINARIA, or INDIVIDUAL |
comunidad | id_comunidad (FK) | Comunidad | The community this fee belongs to |
The Recibo Entity
| Field | Column | Type | Description |
|---|---|---|---|
id | id_recibo | Long (auto) | Primary key |
cuota | id_cuota (FK) | Cuota | The fee this receipt belongs to |
comunidad | id_comunidad (FK) | Comunidad | The community |
usuario | id_usuario (FK) | Usuario | The resident charged |
importe | importe | BigDecimal | Amount due from this specific resident |
estadoRecibo | estado | EstadoRecibo enum | PENDIENTE or PAGADO |
Receipt States
Receipts are marked as
PAGADO when an ADMIN creates an INGRESO financial movement and links it to a receipt. The movement service calls marcarPagado on the receipt at save time. See Finances for details on how this feeds the community ledger.How Receipt Generation Works
Admin creates a fee
The ADMIN calls
POST /api/cuotas with the fee details. For INDIVIDUAL fees, the target user ID is passed as ?idUsuario={id}.Backend calculates per-resident amounts
For For an
ORDINARIA and EXTRAORDINARIA fees, the service iterates over all active users in the community. Any user with a null or zero coeficiente is skipped. Each receipt’s importe is:INDIVIDUAL fee, coeficiente is treated as 100, so the receipt amount equals the full importe of the fee.Example: fee for a 3-resident community
| Resident | coeficiente | Receipt importe | State |
|---|---|---|---|
| María García (3B) | 35.0 | 105.00 € | PENDIENTE |
| Carlos Ruiz (1A) | 40.0 | 120.00 € | PENDIENTE |
| Ana Torres (2C) | 25.0 | 75.00 € | PENDIENTE |
Querying Receipts
- My receipts (USER)
- All community receipts
- Delinquency report
- By fee
- Pending by user
USER and ADMIN. The frontend RecibosPage uses this endpoint to display the resident’s payment history and outstanding balance.Fee Lifecycle and Constraints
Modifying a fee
Fees can be updated via
PUT /api/cuotas/{id}. If the importe changes, the service automatically deletes all existing receipts for that fee and regenerates them with the new amount. Modifications are blocked if any receipt has already been linked to a financial movement (i.e., at least one payment has been recorded).Deleting a fee
DELETE /api/cuotas/{id} deletes the fee and all its associated receipts. Deletion is blocked if any movement references a receipt from that fee, preserving financial history integrity.