# Rooms API

Define the interior layout of rental units — bedrooms, living rooms, kitchens, bathrooms. Room details appear on the lease document and are required for habitable surface area calculations under French law.

## Quick Example

```bash
curl -X POST https://api.faireplace.com/api/places/<place_uuid>/estates/<estate_uuid>/rooms \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type_room_id": "<room_type_uuid>",
    "designation": "Sejour",
    "carrez_surface": 18.5,
    "habitable_surface": 18.5
  }'
```

## Common Workflows

### Define a T2 apartment layout
1. `POST rooms` — Sejour (18.5 m2)
2. `POST rooms` — Chambre (12.0 m2)
3. `POST rooms` — Cuisine (8.0 m2)
4. `POST rooms` — Salle de bain (4.5 m2)

> **Tip:** Get room types with `GET /api/types/rooms` to find the `type_room_id` for each room function.

---

## Overview

Rooms are the most granular level in the property hierarchy (Places > Estates > Rooms) and provide:
- **Space Management**: Detailed room-by-room property layouts
- **Room Types**: Categorization by function via `type_room_id` (references `/api/types/rooms`)
- **Surface Tracking**: Carrez and habitable surface areas for each room
- **Equipment Integration**: Room-level equipment and fixtures (via the Equipment API)

## Authentication

All endpoints require authentication with **PropertiesRead**, **PropertiesWrite**, or **PropertiesDelete** permissions.

## Base URL

Room endpoints are nested: `/api/places/{place_id}/estates/{estate_id}/rooms`

---

## Core Operations

### List Rooms
**GET** `/api/places/{place_id}/estates/{estate_id}/rooms`

**Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "estate_id": "550e8400-e29b-41d4-a716-446655440001",
    "type_room_id": "550e8400-e29b-41d4-a716-446655440002",
    "designation": "Chambre parentale",
    "carrez_surface": 15.5,
    "habitable_surface": 15.5,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]
```

### Create Room
**POST** `/api/places/{place_id}/estates/{estate_id}/rooms`

**Request:**
```json
{
  "type_room_id": "550e8400-e29b-41d4-a716-446655440002",
  "designation": "Cuisine",
  "carrez_surface": 12.0,
  "habitable_surface": 12.0
}
```

### Get Room
**GET** `/api/places/{place_id}/estates/{estate_id}/rooms/{room_id}`

### Update Room
**PUT** `/api/places/{place_id}/estates/{estate_id}/rooms/{room_id}`

### Delete Room
**DELETE** `/api/places/{place_id}/estates/{estate_id}/rooms/{room_id}`

---

## Room Types

Room types are managed via the Types API (`GET /api/types/rooms`). Each room references a `type_room_id` which determines its function (bedroom, kitchen, bathroom, etc.).

---

## Room Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | uuid | Room identifier |
| `estate_id` | uuid | Parent estate |
| `type_room_id` | uuid | Room type reference |
| `designation` | string | Room label/name |
| `carrez_surface` | number | Carrez surface area (m2) |
| `habitable_surface` | number | Habitable surface area (m2) |
| `created_at` | datetime | Creation timestamp |
| `updated_at` | datetime | Last update timestamp |

---

## Error Responses

**400 Bad Request**
```json
{
  "error": "ValidationError",
  "message": "type_room_id is required"
}
```

**404 Not Found**
```json
{
  "error": "NotFound",
  "message": "Room not found in specified estate"
}
```

---

## Common Use Cases

- **Property Layout**: Create detailed floor plans with room-by-room breakdown
- **Surface Calculations**: Track Carrez and habitable surfaces for each room
- **Equipment Assignment**: Associate equipment with specific rooms

## Integration Notes

- **Equipment**: Rooms can contain equipment and fixtures (via `/rooms/{room_id}/equipment`)
- **Surface Calculations**: Room surfaces contribute to estate total area
- **Property Hierarchy**: Rooms must belong to valid estates within places