Community Charges & Statements

Overview

The Community Charges API provides comprehensive statement views that combine charges (cargos) and payments (pagos) for contracts and communities. This API is designed for viewing and querying charge data, not for creating or modifying charges.

All endpoints in this section require ADMIN_COMPANY or SYSTEM_ADMIN role.

Statement Object

A statement provides a complete financial view combining charges and payments.

cargos

array

Array of charge objects

Show Cargo Object

string (guid)

Unique identifier for the charge

contratoId

string (guid)

ID of the associated contract

comunidadId

string (guid)

ID of the associated community

montoCargo

number (decimal)

Base charge amount

fechaDePago

string (datetime)

Due date for the charge (ISO 8601 format)

montoRecargos

number (decimal)

Late fee amount added to the charge

estatus

string

Current charge status:

No vencido - Not yet due
vencido - Overdue
pagado - Fully paid
pago parcial - Partially paid

notas

string

Additional notes about the charge

isActive

boolean

Whether the charge is active

createdAt

string (datetime)

Timestamp when the charge was created

updatedAt

string (datetime)

Timestamp of the last update

pagos

array

Array of payment objects

Show Pago Object

string (guid)

Unique identifier for the payment

montoPago

number (decimal)

Total payment amount

formaDePago

string

Payment method used:

transferencia - Bank transfer
tarjeta - Credit/debit card
efectivo - Cash
cheque - Check

fechaDePago

string (datetime)

Date when the payment was made (ISO 8601 format)

isActive

boolean

Whether the payment is active

createdAt

string (datetime)

Timestamp when the payment was recorded

updatedAt

string (datetime)

Timestamp of the last update

updatedByUserId

string (guid)

ID of the user who last updated the payment

pagoCargos

array

Array of payment-to-charge associations showing how this payment was applied

Show PagoCargo Object

string (guid)

Unique identifier for the payment-charge association

pagoComunidadId

string (guid)

ID of the payment

cargosComunidadId

string (guid)

ID of the charge this payment was applied to

montoAplicado

number (decimal)

Amount of the payment applied to this specific charge

createdAt

string (datetime)

Timestamp when the application was created

Get Statement by Contract

Retrieve a complete statement (charges and payments) for a specific contract.

GET /api/charges/contrato/{contratoId}

Path Parameters

contratoId

string (guid)

required

The unique identifier of the contract

Authorization

Requires ADMIN_COMPANY or SYSTEM_ADMIN role.

Response

Returns a StatementDto object containing arrays of charges (cargos) and payments (pagos).

Example Response

{
  "cargos": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "contratoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "comunidadId": "8d9e6679-7425-40de-944b-e07fc1f90ae8",
      "montoCargo": 1500.00,
      "fechaDePago": "2024-03-15T00:00:00Z",
      "montoRecargos": 75.00,
      "estatus": "pagado",
      "notas": "Cuota mensual marzo 2024",
      "isActive": true,
      "createdAt": "2024-02-25T10:00:00Z",
      "updatedAt": "2024-03-15T14:30:00Z"
    },
    {
      "id": "4fa85f64-5717-4562-b3fc-2c963f66afa7",
      "contratoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "comunidadId": "8d9e6679-7425-40de-944b-e07fc1f90ae8",
      "montoCargo": 1500.00,
      "fechaDePago": "2024-04-15T00:00:00Z",
      "montoRecargos": 0.00,
      "estatus": "No vencido",
      "notas": "Cuota mensual abril 2024",
      "isActive": true,
      "createdAt": "2024-03-25T10:00:00Z",
      "updatedAt": null
    }
  ],
  "pagos": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "montoPago": 1575.00,
      "formaDePago": "transferencia",
      "fechaDePago": "2024-03-15T14:30:00Z",
      "isActive": true,
      "createdAt": "2024-03-15T14:35:00Z",
      "updatedAt": null,
      "updatedByUserId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "pagoCargos": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "pagoComunidadId": "550e8400-e29b-41d4-a716-446655440000",
          "cargosComunidadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "montoAplicado": 1575.00,
          "createdAt": "2024-03-15T14:35:00Z"
        }
      ]
    }
  ]
}

Example Request

curl -X GET "https://api.happyhabitat.com/api/charges/contrato/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer {your_jwt_token}"

Get Statement by Community

Retrieve a complete statement (charges and payments) for all contracts in a specific community.

GET /api/charges/comunidad/{comunidadId}

Path Parameters

comunidadId

string (guid)

required

The unique identifier of the community

Authorization

Requires ADMIN_COMPANY or SYSTEM_ADMIN role.

Response

Returns a StatementDto object containing all charges and payments for contracts in the specified community.

Example Request

curl -X GET "https://api.happyhabitat.com/api/charges/comunidad/8d9e6679-7425-40de-944b-e07fc1f90ae8" \
  -H "Authorization: Bearer {your_jwt_token}"

Get Charges by Community

Retrieve only the charges (without payments) for a specific community.

GET /api/charges/comunidad/{comunidadId}/cargos

Path Parameters

comunidadId

string (guid)

required

The unique identifier of the community

Authorization

Requires ADMIN_COMPANY or SYSTEM_ADMIN role.

Response

Returns an array of CargoComunidadDto objects for the specified community.

Example Response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "contratoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "comunidadId": "8d9e6679-7425-40de-944b-e07fc1f90ae8",
    "montoCargo": 1500.00,
    "fechaDePago": "2024-03-15T00:00:00Z",
    "montoRecargos": 75.00,
    "estatus": "pagado",
    "notas": "Cuota mensual marzo 2024",
    "isActive": true,
    "createdAt": "2024-02-25T10:00:00Z",
    "updatedAt": "2024-03-15T14:30:00Z"
  }
]

Get Charges by Contract

Retrieve only the charges (without payments) for a specific contract.

GET /api/charges/contrato/{contratoId}/cargos

Path Parameters

contratoId

string (guid)

required

The unique identifier of the contract

Authorization

Requires ADMIN_COMPANY or SYSTEM_ADMIN role.

Response

Returns an array of CargoComunidadDto objects for the specified contract.

Example Request

curl -X GET "https://api.happyhabitat.com/api/charges/contrato/7c9e6679-7425-40de-944b-e07fc1f90ae7/cargos" \
  -H "Authorization: Bearer {your_jwt_token}"

Resident Charges

In addition to community charges tracked at the contract level, the system also supports individual resident charges through the /api/CargosResidente endpoints.

Key Differences

Feature	Community Charges	Resident Charges
Endpoint	`/api/charges/*`	`/api/CargosResidente/*`
Associated With	Contracts & Communities	Individual Residents
Purpose	Contract-level billing	Resident-specific charges
Status Values	No vencido, vencido, pagado, pago parcial	Activo, Pagado, PagoParcial, Cancelado
Late Fees	MontoRecargos field	Not tracked
Payment Link	PagoComunidad via PagoCargoComunidad	Managed separately

Get All Resident Charges

GET /api/CargosResidente

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN Retrieves all resident charges in the system.

Get Resident Charges by Resident ID

GET /api/CargosResidente/resident/{residentId}

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Get Resident Charges by Community ID

GET /api/CargosResidente/community/{communityId}

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Create Resident Charge

POST /api/CargosResidente

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN Request Body:

{
  "residentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "fecha": "2024-04-01T00:00:00Z",
  "descripcion": "Cuota de mantenimiento - Abril 2024",
  "monto": 150.00,
  "estatus": "Activo",
  "createdByUserId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
}

Update Resident Charge

PUT /api/CargosResidente/{id}

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Delete Resident Charge

DELETE /api/CargosResidente/{id}

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Understanding Charge Status

Community Charge Status

Community charges use Spanish status values that reflect their payment timeline:

No vencido: Charge is not yet due (before fechaDePago)
vencido: Charge is overdue (after fechaDePago, not fully paid)
pagado: Charge has been fully paid
pago parcial: Charge has been partially paid but balance remains

Late Fees (Recargos)

The montoRecargos field tracks additional fees applied to overdue charges. The total amount owed is montoCargo + montoRecargos.

Payment Application

When a payment is recorded:

Payment is created in PagoComunidad table
Payment is linked to one or more charges via PagoCargoComunidad
Each link specifies montoAplicado (amount applied to that charge)
Charge status updates automatically based on total payments applied

Error Responses

401 Unauthorized

Returned when authentication is missing or invalid.

403 Forbidden

Returned when the user doesn’t have the required role.

404 Not Found

Returned when the requested contract or community doesn’t exist.

Best Practices

Use Statements: Use statement endpoints to get a complete financial view
Check Status: Monitor charge status to identify overdue accounts
Track Late Fees: Include montoRecargos when calculating total amounts due
Payment Application: Review pagoCargos to understand how payments were applied
Filter by Community: Use community-level endpoints for managing multiple contracts
Date Awareness: Consider fechaDePago when determining if charges are overdue

Authentication

Residents

Communities

Amenities

Documents

Payments & Charges

Tickets

Vehicles & Pets

Visits

Announcements & Surveys

Error Handling

​Overview

​Statement Object

​Get Statement by Contract

​Path Parameters

​Authorization

​Response

​Example Response

​Example Request

​Get Statement by Community

​Path Parameters

​Authorization

​Response

​Example Request

​Get Charges by Community

​Path Parameters

​Authorization

​Response

​Example Response

​Get Charges by Contract

​Path Parameters

​Authorization

​Response

​Example Request

​Resident Charges

​Key Differences

​Get All Resident Charges

​Get Resident Charges by Resident ID

​Get Resident Charges by Community ID

​Create Resident Charge

​Update Resident Charge

​Delete Resident Charge

​Understanding Charge Status

​Community Charge Status

​Late Fees (Recargos)

​Payment Application

​Error Responses

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Best Practices

Build docs developers (and LLMs) love

Overview

Statement Object

Get Statement by Contract

Path Parameters

Authorization

Response

Example Response

Example Request

Get Statement by Community

Path Parameters

Authorization

Response

Example Request

Get Charges by Community

Path Parameters

Authorization

Response

Example Response

Get Charges by Contract

Path Parameters

Authorization

Response

Example Request

Resident Charges

Key Differences

Get All Resident Charges

Get Resident Charges by Resident ID

Get Resident Charges by Community ID

Create Resident Charge

Update Resident Charge

Delete Resident Charge

Understanding Charge Status

Community Charge Status

Late Fees (Recargos)

Payment Application

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

Best Practices