Communities Endpoints - Happy Habitat

Communities Management

Get All Communities

curl -X GET "https://api.happyhabitat.com/api/communities" \
  -H "Authorization: Bearer <your_token>"

Response Example:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "nombre": "Residencial Los Pinos",
    "descripcion": "Comunidad residencial con amenidades completas",
    "direccion": "Av. Principal 123, Ciudad",
    "contacto": "Juan Pérez",
    "email": "[email protected]",
    "phone": "+1234567890",
    "tipoComunidad": "Residencial",
    "latitud": 19.4326,
    "longitud": -99.1332,
    "cantidadViviendas": 150
  }
]

Get Community by ID

curl -X GET "https://api.happyhabitat.com/api/communities/{id}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

id (string, required): Community unique identifier

Response Example:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "nombre": "Residencial Los Pinos",
  "descripcion": "Comunidad residencial con amenidades completas",
  "direccion": "Av. Principal 123, Ciudad",
  "contacto": "Juan Pérez",
  "email": "[email protected]",
  "phone": "+1234567890",
  "tipoComunidad": "Residencial",
  "latitud": 19.4326,
  "longitud": -99.1332,
  "cantidadViviendas": 150
}

Create Community

curl -X POST "https://api.happyhabitat.com/api/communities" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Residencial Los Pinos",
    "descripcion": "Comunidad residencial con amenidades completas",
    "direccion": "Av. Principal 123, Ciudad",
    "contacto": "Juan Pérez",
    "email": "[email protected]",
    "phone": "+1234567890",
    "tipoComunidad": "Residencial",
    "latitud": 19.4326,
    "longitud": -99.1332,
    "cantidadViviendas": 150
  }'

Request Body:

{
  "nombre": "string (required)",
  "descripcion": "string (required)",
  "direccion": "string (required)",
  "contacto": "string (required)",
  "email": "string (required)",
  "phone": "string (required)",
  "tipoComunidad": "string (required)",
  "latitud": "number (optional)",
  "longitud": "number (optional)",
  "cantidadViviendas": "integer (required)"
}

Update Community

curl -X PUT "https://api.happyhabitat.com/api/communities/{id}" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Residencial Los Pinos Actualizado",
    "descripcion": "Descripción actualizada",
    "direccion": "Av. Principal 123, Ciudad",
    "contacto": "Juan Pérez",
    "email": "[email protected]",
    "phone": "+1234567890",
    "tipoComunidad": "Residencial",
    "latitud": 19.4326,
    "longitud": -99.1332,
    "cantidadViviendas": 160
  }'

Path Parameters:

id (string, required): Community unique identifier

Delete Community

curl -X DELETE "https://api.happyhabitat.com/api/communities/{id}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

id (string, required): Community unique identifier

Response: 204 No Content

Community Configurations

Get All Configurations

curl -X GET "https://api.happyhabitat.com/api/communityconfigurations" \
  -H "Authorization: Bearer <your_token>"

Response Example:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "communityName": "Residencial Los Pinos",
    "codigo": "MAX_GUEST_VISITORS",
    "titulo": "Máximo de Visitantes",
    "descripcion": "Número máximo de visitantes permitidos por residente",
    "valor": "5",
    "tipoDato": "integer",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-02-20T14:45:00Z",
    "createdByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
    "updatedByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }
]

Get Configurations by Community ID

curl -X GET "https://api.happyhabitat.com/api/communityconfigurations/community/{communityId}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

communityId (Guid, required): Community unique identifier

Get Configuration by ID

curl -X GET "https://api.happyhabitat.com/api/communityconfigurations/{id}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

id (Guid, required): Configuration unique identifier

Create Configuration

curl -X POST "https://api.happyhabitat.com/api/communityconfigurations" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "codigo": "MAX_GUEST_VISITORS",
    "titulo": "Máximo de Visitantes",
    "descripcion": "Número máximo de visitantes permitidos por residente",
    "valor": "5",
    "tipoDato": "integer",
    "createdByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }'

Request Body:

{
  "communityId": "Guid (required)",
  "codigo": "string (required)",
  "titulo": "string (required)",
  "descripcion": "string (required)",
  "valor": "string (required)",
  "tipoDato": "string (required)",
  "createdByUserId": "Guid (optional)"
}

Update Configuration

curl -X PUT "https://api.happyhabitat.com/api/communityconfigurations/{id}" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "codigo": "MAX_GUEST_VISITORS",
    "titulo": "Máximo de Visitantes",
    "descripcion": "Número máximo de visitantes permitidos por residente",
    "valor": "10",
    "tipoDato": "integer",
    "updatedByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }'

Path Parameters:

id (Guid, required): Configuration unique identifier

Delete Configuration

curl -X DELETE "https://api.happyhabitat.com/api/communityconfigurations/{id}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

id (Guid, required): Configuration unique identifier

Response: 204 No Content

Community Prices

Get All Prices

curl -X GET "https://api.happyhabitat.com/api/communityprices" \
  -H "Authorization: Bearer <your_token>"

Response Example:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "communityName": "Residencial Los Pinos",
    "concepto": "Cuota de Mantenimiento Mensual",
    "monto": 250.00,
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-02-20T14:45:00Z",
    "createdByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
    "updatedByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }
]

Get Prices by Community ID

curl -X GET "https://api.happyhabitat.com/api/communityprices/community/{communityId}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

communityId (Guid, required): Community unique identifier

Get Price by ID

curl -X GET "https://api.happyhabitat.com/api/communityprices/{id}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

id (Guid, required): Price entry unique identifier

Create Price

curl -X POST "https://api.happyhabitat.com/api/communityprices" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "concepto": "Cuota de Mantenimiento Mensual",
    "monto": 250.00,
    "isActive": true,
    "createdByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }'

Request Body:

{
  "communityId": "Guid (required)",
  "concepto": "string (required)",
  "monto": "decimal (required)",
  "isActive": "boolean (default: true)",
  "createdByUserId": "Guid (optional)"
}

Update Price

curl -X PUT "https://api.happyhabitat.com/api/communityprices/{id}" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "concepto": "Cuota de Mantenimiento Mensual",
    "monto": 275.00,
    "isActive": true,
    "updatedByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }'

Path Parameters:

id (Guid, required): Price entry unique identifier

Delete Price

curl -X DELETE "https://api.happyhabitat.com/api/communityprices/{id}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

id (Guid, required): Price entry unique identifier

Response: 204 No Content

Community Providers

Get All Providers

curl -X GET "https://api.happyhabitat.com/api/communityproviders?includeInactive=false" \
  -H "Authorization: Bearer <your_token>"

Query Parameters:

includeInactive (boolean, optional): Include inactive providers (default: false)

Response Example:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "communityName": "Residencial Los Pinos",
    "businessName": "ABC Plumbing Services",
    "taxId": "12345678-9",
    "fullAddress": "Calle Principal 456, Ciudad",
    "contactPhones": "+1234567890, +0987654321",
    "primaryEmail": "[email protected]",
    "websiteOrSocialMedia": "https://www.abcplumbing.com",
    "primaryContactName": "Carlos Rodríguez",
    "directPhone": "+1234567890",
    "mobilePhone": "+1234567891",
    "contactEmail": "[email protected]",
    "productsOrServices": "Plumbing repairs, installations, and maintenance",
    "categoryOrIndustry": "Plumbing",
    "paymentMethods": "Cash, Transfer, Credit Card",
    "rating": 4.5,
    "orderHistory": "10 completed orders",
    "pastIncidentsOrClaims": "None",
    "internalNotes": "Reliable provider with quick response time",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "createdByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
    "updatedAt": "2024-02-20T14:45:00Z",
    "updatedByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }
]

Get Providers by Community ID

curl -X GET "https://api.happyhabitat.com/api/communityproviders/community/{communityId}?includeInactive=false" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

communityId (Guid, optional): Community unique identifier (nullable for general providers)

Query Parameters:

includeInactive (boolean, optional): Include inactive providers (default: false)

Get Provider by ID

curl -X GET "https://api.happyhabitat.com/api/communityproviders/{id}?includeInactive=false" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

id (Guid, required): Provider unique identifier

Query Parameters:

includeInactive (boolean, optional): Include inactive provider (default: false)

Create Provider

curl -X POST "https://api.happyhabitat.com/api/communityproviders" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "businessName": "ABC Plumbing Services",
    "taxId": "12345678-9",
    "fullAddress": "Calle Principal 456, Ciudad",
    "contactPhones": "+1234567890, +0987654321",
    "primaryEmail": "[email protected]",
    "websiteOrSocialMedia": "https://www.abcplumbing.com",
    "primaryContactName": "Carlos Rodríguez",
    "directPhone": "+1234567890",
    "mobilePhone": "+1234567891",
    "contactEmail": "[email protected]",
    "productsOrServices": "Plumbing repairs, installations, and maintenance",
    "categoryOrIndustry": "Plumbing",
    "paymentMethods": "Cash, Transfer, Credit Card",
    "rating": 4.5,
    "orderHistory": "10 completed orders",
    "pastIncidentsOrClaims": "None",
    "internalNotes": "Reliable provider with quick response time",
    "createdByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }'

Request Body:

{
  "communityId": "Guid (required)",
  "businessName": "string (required)",
  "taxId": "string (optional)",
  "fullAddress": "string (optional)",
  "contactPhones": "string (optional)",
  "primaryEmail": "string (optional)",
  "websiteOrSocialMedia": "string (optional)",
  "primaryContactName": "string (optional)",
  "directPhone": "string (optional)",
  "mobilePhone": "string (optional)",
  "contactEmail": "string (optional)",
  "productsOrServices": "string (optional)",
  "categoryOrIndustry": "string (optional)",
  "paymentMethods": "string (optional)",
  "rating": "decimal (optional)",
  "orderHistory": "string (optional)",
  "pastIncidentsOrClaims": "string (optional)",
  "internalNotes": "string (optional)",
  "createdByUserId": "Guid (optional)"
}

Update Provider

curl -X PUT "https://api.happyhabitat.com/api/communityproviders/{id}" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "7b42e8a1-9876-4321-a1b2-c3d4e5f6a7b8",
    "businessName": "ABC Plumbing Services Updated",
    "taxId": "12345678-9",
    "fullAddress": "Calle Principal 456, Ciudad",
    "contactPhones": "+1234567890",
    "primaryEmail": "[email protected]",
    "websiteOrSocialMedia": "https://www.abcplumbing.com",
    "primaryContactName": "Carlos Rodríguez",
    "directPhone": "+1234567890",
    "mobilePhone": "+1234567891",
    "contactEmail": "[email protected]",
    "productsOrServices": "Plumbing repairs, installations, and maintenance",
    "categoryOrIndustry": "Plumbing",
    "paymentMethods": "Cash, Transfer, Credit Card",
    "rating": 4.8,
    "orderHistory": "15 completed orders",
    "pastIncidentsOrClaims": "None",
    "internalNotes": "Excellent provider with quick response time",
    "updatedByUserId": "1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
  }'

Path Parameters:

id (Guid, required): Provider unique identifier

Delete Provider

Soft deletes a provider by setting IsActive to false.

curl -X DELETE "https://api.happyhabitat.com/api/communityproviders/{id}" \
  -H "Authorization: Bearer <your_token>"

Path Parameters:

id (Guid, required): Provider unique identifier

Response: 204 No Content Note: This is a soft delete operation. The provider’s IsActive field is set to false rather than physically removing the record from the database. To view soft-deleted providers, use the includeInactive=true query parameter in GET requests.

Error Handling

All endpoints may return the following error responses:

400 Bad Request

{
  "message": "Invalid operation or validation error description"
}

401 Unauthorized

{
  "message": "Unauthorized access - invalid or missing token"
}

403 Forbidden

{
  "message": "Insufficient permissions - requires ADMIN_COMPANY or SYSTEM_ADMIN role"
}

404 Not Found

{
  "message": "Resource not found"
}

Best Practices

Community Management
- Always validate email and phone formats before submission
- Provide accurate geographic coordinates for location-based features
- Use descriptive community types (TipoComunidad) for better categorization
Configuration Management
- Use consistent configuration codes (Codigo) across communities
- Specify appropriate data types (TipoDato) for proper value validation
- Include descriptive titles and descriptions for maintainability
Pricing Management
- Use clear, descriptive concepts (Concepto) for pricing entries
- Set isActive to false instead of deleting prices to maintain historical data
- Include user IDs for audit trails when creating or updating prices
Provider Management
- Use soft deletes (set IsActive to false) to preserve provider history
- Maintain comprehensive contact information for effective communication
- Update ratings and order history regularly for accurate provider assessment
- Document incidents and claims in PastIncidentsOrClaims for transparency
- Use the includeInactive parameter when you need to access historical provider data
Error Handling
- Always check for 404 responses when fetching resources by ID
- Handle 400 errors by validating data before submission
- Implement proper token refresh mechanisms for 401 errors

Authentication

Residents

Communities

Amenities

Documents

Payments & Charges

Tickets

Vehicles & Pets

Visits

Announcements & Surveys

Error Handling

​Communities Management

​Get All Communities

​Get Community by ID

​Create Community

​Update Community

​Delete Community

​Community Configurations

​Get All Configurations

​Get Configurations by Community ID

​Get Configuration by ID

​Create Configuration

​Update Configuration

​Delete Configuration

​Community Prices

​Get All Prices

​Get Prices by Community ID

​Get Price by ID

​Create Price

​Update Price

​Delete Price

​Community Providers

​Get All Providers

​Get Providers by Community ID

​Get Provider by ID

​Create Provider

​Update Provider

​Delete Provider

​Error Handling

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Best Practices

Build docs developers (and LLMs) love

Communities Management

Get All Communities

Get Community by ID

Create Community

Update Community

Delete Community

Community Configurations

Get All Configurations

Get Configurations by Community ID

Get Configuration by ID

Create Configuration

Update Configuration

Delete Configuration

Community Prices

Get All Prices

Get Prices by Community ID

Get Price by ID

Create Price

Update Price

Delete Price

Community Providers

Get All Providers

Get Providers by Community ID

Get Provider by ID

Create Provider

Update Provider

Delete Provider

Error Handling

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Best Practices