Skip to main content

​
Introduction

The Amenities API provides comprehensive management capabilities for community amenities in the Happy Habitat platform. This includes creating and managing amenities such as pools, gyms, clubhouses, tennis courts, and other shared facilities within residential communities.

​
Key Features

​
Amenity Management

  • Create and manage community amenities with detailed information
  • Define rules and usage guidelines for each amenity
  • Support for amenity images and visual identification
  • Track amenity registration dates and creation timestamps
  • Soft delete functionality to maintain historical data

​
Capacity & Availability Management

  • Set maximum capacity limits for each amenity
  • Configure number of simultaneous reservations allowed
  • Enable booking management and availability tracking
  • Support for high-traffic amenities with concurrent usage

​
Cost Configuration

  • Define optional usage costs for amenities
  • Support for paid and free amenity models
  • Flexible pricing structure per amenity
  • Integration with payment and billing systems

​
Community Association

  • Link amenities to specific communities
  • Filter and retrieve amenities by community
  • Support for multi-community platforms
  • Community-specific amenity configurations

​
Core Entities

​
Amenity

Represents a community amenity with the following key attributes:
  • Id (Guid): Unique identifier for the amenity
  • Nombre (string): Amenity name (e.g., “Swimming Pool”, “Tennis Court”)
  • Descripcion (string): Detailed description of the amenity
  • Reglas (string): Rules and guidelines for amenity usage
  • Costo (decimal?): Optional cost associated with using the amenity
  • FechaAlta (DateTime): Date when the amenity was registered
  • Imagen (string?): URL or path to the amenity image
  • CommunityId (Guid?): Associated community identifier
  • CommunityName (string?): Name of the associated community
  • CapacidadMaxima (int?): Maximum capacity of people allowed
  • NumeroReservacionesSimultaneas (int?): Number of simultaneous reservations allowed
  • CreatedAt (string): ISO 8601 timestamp of creation
  • IsActive (boolean): Active status (used for soft deletion)

​
Authentication & Authorization

All Amenities endpoints require authentication with one of the following roles:
  • ADMIN_COMPANY: Company administrators
  • SYSTEM_ADMIN: System-level administrators
Include a valid JWT token in the Authorization header: 
Authorization: Bearer <your_token>

​
Base URL

All endpoints are prefixed with the API base URL: 
/api/amenities

​
Common Response Codes

  • 200 OK: Successful request
  • 201 Created: Amenity successfully created
  • 204 No Content: Successful deletion
  • 400 Bad Request: Invalid request data or business logic violation
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions (requires ADMIN_COMPANY or SYSTEM_ADMIN role)
  • 404 Not Found: Amenity not found

​
Common Use Cases

​
Creating Community Amenities

Administrators can create amenities for their communities with detailed configurations including capacity limits, costs, and usage rules. Each amenity can have custom settings tailored to the specific needs of the facility.

​
Filtering by Community

Retrieve all amenities for a specific community to display available facilities to residents. The optional communityId parameter allows flexible querying across single or multiple communities.

​
Managing Availability

Configure maximum capacity and simultaneous reservation limits to effectively manage amenity usage. This ensures fair access and prevents overbooking of popular facilities.

​
Booking Integration

Amenities with capacity and reservation limits can integrate with booking systems. The NumeroReservacionesSimultaneas property controls concurrent booking allowances. Amenities are connected to other resources in the Happy Habitat platform:
  • Communities (parent entity)
  • Reservations/Bookings (usage tracking)
  • Residents (users of amenities)
  • Payment Records (for paid amenities)

​
Best Practices

  1. Amenity Creation
    • Provide clear, descriptive names for easy identification
    • Include comprehensive rules to set user expectations
    • Use high-quality images for visual recognition
    • Set appropriate capacity limits based on facility size
  2. Capacity Management
    • Configure CapacidadMaxima based on safety and comfort considerations
    • Set NumeroReservacionesSimultaneas to prevent overbooking
    • Consider peak usage times when setting limits
    • Regularly review and adjust capacity settings
  3. Cost Configuration
    • Leave Costo as null for free amenities
    • Set clear, transparent pricing for paid facilities
    • Consider maintenance costs when determining pricing
    • Communicate cost changes to residents in advance
  4. Data Maintenance
    • Use soft delete (DELETE endpoint) instead of hard deletion
    • Keep amenity information up-to-date
    • Archive inactive amenities rather than removing them
    • Maintain historical records for reporting and analytics

Build docs developers (and LLMs) love

Get started for freeTalk to us