Cuotas API — Community Fee Schedule and Cuota Guide

The Fees API manages Cuota resources — the scheduled charges raised against residents of a community. When a fee is created, the system automatically generates a Recibo (receipt) for every active user in the community (or for a single user when the type is INDIVIDUAL). This ensures that payment tracking is always in sync with the fee schedule. The community for every new fee is derived automatically from the caller’s JWT — it is not supplied in the request body. All endpoints require a valid JWT Bearer token in the Authorization header.

GET /api/cuotas

Returns every fee across all communities on the platform.

Required role: SUPER_ADMIN

curl -X GET https://api.example.com/api/cuotas \
  -H "Authorization: Bearer <token>"

Response 200 OK — array of Cuota objects.

[].id

number

Unique identifier of the fee.

[].nombre

string

Descriptive name for the fee (e.g. "Cuota Ordinaria Enero 2025").

[].fechaEmision

string

Issue date in YYYY-MM-DD format.

[].fechaVencimiento

string

Due date in YYYY-MM-DD format.

[].importe

number

Total fee amount (e.g. 85.00). Each resident’s individual receipt amount may differ based on their coeficiente.

[].tipo

string

Fee type. One of ORDINARIA, EXTRAORDINARIA, or INDIVIDUAL.

[].comunidad

object

The community this fee belongs to.

Show comunidad fields

number

Community identifier.

nombre

string

Community display name.

direccion

string

Street address.

ciudad

string

City.

codPostal

string

Postal code.

Example response

[
  {
    "id": 10,
    "nombre": "Cuota Ordinaria Enero 2025",
    "fechaEmision": "2025-01-01",
    "fechaVencimiento": "2025-01-31",
    "importe": 85.00,
    "tipo": "ORDINARIA",
    "comunidad": {
      "id": 1,
      "nombre": "Comunidad Los Pinos",
      "direccion": "Calle Mayor 10",
      "ciudad": "Madrid",
      "codPostal": "28001"
    }
  }
]

Status	Meaning
`200`	OK — list returned (may be empty).
`403`	Forbidden — caller does not have `SUPER_ADMIN` role.

GET /api/cuotas/comunidad

Returns all fees that belong to the community encoded in the caller’s JWT.

Required role: ADMIN

curl -X GET https://api.example.com/api/cuotas/comunidad \
  -H "Authorization: Bearer <token>"

Response 200 OK — array of Cuota objects scoped to the caller’s community (same schema as above).

Status	Meaning
`200`	OK — list returned (may be empty).
`403`	Forbidden — caller does not have `ADMIN` role.

GET /api/cuotas/{id}

Retrieves a single fee by its numeric id. Returns 403 if the fee belongs to a different community than the caller’s JWT community.

Required role: ADMIN

Path parameters

number

required

The unique identifier of the fee to retrieve.

curl -X GET https://api.example.com/api/cuotas/10 \
  -H "Authorization: Bearer <token>"

Response 200 OK — a single Cuota object.

Example response

{
  "id": 10,
  "nombre": "Cuota Ordinaria Enero 2025",
  "fechaEmision": "2025-01-01",
  "fechaVencimiento": "2025-01-31",
  "importe": 85.00,
  "tipo": "ORDINARIA",
  "comunidad": {
    "id": 1,
    "nombre": "Comunidad Los Pinos",
    "direccion": "Calle Mayor 10",
    "ciudad": "Madrid",
    "codPostal": "28001"
  }
}

Status	Meaning
`200`	OK — fee found and returned.
`403`	Forbidden — fee belongs to a different community, or caller lacks `ADMIN` role. Returns `"No tienes permiso para ver cuotas de otra comunidad"`.
`404`	Not Found — no fee with the given `id` exists.

POST /api/cuotas

Creates a new fee and automatically generates receipts for all active users in the community. If the fee type is INDIVIDUAL, pass the target user’s id as the idUsuario query parameter — only that user receives a receipt.

Required role: ADMIN or SUPER_ADMIN

The community is set automatically from the caller’s JWT. Any comunidad object included in the request body will be overwritten.

For INDIVIDUAL fees, include the idUsuario query parameter to target a specific resident. Omitting it will issue receipts to all active community members regardless of fee type.

Query parameters

idUsuario

number

Optional. The id of a specific user to issue an INDIVIDUAL fee against. Required when tipo is INDIVIDUAL; ignored for ORDINARIA and EXTRAORDINARIA types.

Request body

nombre

string

required

Descriptive name for the fee.

fechaEmision

string

required

Issue date in YYYY-MM-DD format.

fechaVencimiento

string

required

Due date in YYYY-MM-DD format.

importe

number

required

Total fee amount (e.g. 85.00).

tipo

string

required

Fee type. One of ORDINARIA, EXTRAORDINARIA, or INDIVIDUAL.

curl -X POST https://api.example.com/api/cuotas \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Cuota Ordinaria Enero 2025",
    "fechaEmision": "2025-01-01",
    "fechaVencimiento": "2025-01-31",
    "importe": 85.00,
    "tipo": "ORDINARIA"
  }'

Response 200 OK — the newly created Cuota object including its generated id and the auto-assigned comunidad.

Example response

{
  "id": 11,
  "nombre": "Cuota Ordinaria Enero 2025",
  "fechaEmision": "2025-01-01",
  "fechaVencimiento": "2025-01-31",
  "importe": 85.00,
  "tipo": "ORDINARIA",
  "comunidad": {
    "id": 1,
    "nombre": "Comunidad Los Pinos",
    "direccion": "Calle Mayor 10",
    "ciudad": "Madrid",
    "codPostal": "28001"
  }
}

Status	Meaning
`200`	OK — fee created; receipts generated automatically.
`403`	Forbidden — caller does not have the required role.

PUT /api/cuotas/{id}

Replaces the editable fields of an existing fee. The fee must belong to the caller’s JWT community.

Required role: ADMIN or SUPER_ADMIN

Path parameters

number

required

The unique identifier of the fee to update.

Request body

nombre

string

Updated fee name.

fechaEmision

string

Updated issue date (YYYY-MM-DD).

fechaVencimiento

string

Updated due date (YYYY-MM-DD).

importe

number

Updated fee amount.

tipo

string

Updated fee type (ORDINARIA, EXTRAORDINARIA, or INDIVIDUAL).

curl -X PUT https://api.example.com/api/cuotas/10 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Cuota Ordinaria Enero 2025 (Revisada)",
    "fechaEmision": "2025-01-01",
    "fechaVencimiento": "2025-02-07",
    "importe": 90.00,
    "tipo": "ORDINARIA"
  }'

Response 200 OK — the updated Cuota object.

Status	Meaning
`200`	OK — fee updated and returned.
`404`	Not Found — no fee with that `id` exists.
`409`	Conflict — update violates a business rule (e.g. associated paid receipts exist).
`403`	Forbidden — caller does not have the required role.

DELETE /api/cuotas/{id}

Deletes a fee. The fee must belong to the caller’s JWT community. Deletion may be rejected if the fee has associated paid receipts.

Required role: ADMIN or SUPER_ADMIN

Path parameters

number

required

The unique identifier of the fee to delete.

curl -X DELETE https://api.example.com/api/cuotas/10 \
  -H "Authorization: Bearer <token>"

Status	Meaning
`200`	OK — fee deleted. Returns `"Cuota eliminada correctamente"`.
`404`	Not Found — no fee with that `id` exists.
`409`	Conflict — fee cannot be deleted because it has associated receipts in a final state.
`403`	Forbidden — caller does not have the required role.

Overview

Endpoints

Cuotas API — Community Fee Schedule and Cuota Guide

GET /api/cuotas

GET /api/cuotas/comunidad

GET /api/cuotas/{id}

Path parameters

POST /api/cuotas

Query parameters

Request body

PUT /api/cuotas/{id}

Path parameters

Request body

DELETE /api/cuotas/{id}

Path parameters

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/cuotas

​GET /api/cuotas/comunidad

​GET /api/cuotas/{id}

​Path parameters

​POST /api/cuotas

​Query parameters

​Request body

​PUT /api/cuotas/{id}

​Path parameters

​Request body

​DELETE /api/cuotas/{id}

​Path parameters

Build docs developers (and LLMs) love

GET /api/cuotas

GET /api/cuotas/comunidad

GET /api/cuotas/{id}

Path parameters

POST /api/cuotas

Query parameters

Request body

PUT /api/cuotas/{id}

Path parameters

Request body

DELETE /api/cuotas/{id}

Path parameters