# Estates API

Manage individual rental units — apartments, studios, houses, or commercial spaces. Estates are the units you create leases for.

## Quick Example

```bash
curl -X POST https://api.faireplace.com/api/places/<place_uuid>/estates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "T2 - Apt 301",
    "estate_type_id": "<estate_type_uuid>",
    "area": 45.0,
    "fiscal_identifier": "75012-B-0301",
    "number_of_room": 2,
    "floor": 3,
    "address": "24 rue du Faubourg Saint-Antoine, Apt 301, 75012 Paris"
  }'
```

## Common Workflows

### List all units in a building
1. `GET /api/places/{place_id}/estates` — Returns all apartments in the building

### Prepare a unit for leasing
1. `POST /api/places/{id}/estates` — Create the estate
2. `POST /api/places/{id}/estates/{id}/rooms` — Add rooms ([Rooms API](/properties/rooms))
3. `POST /api/leases` — Create a lease for this estate ([Leases API](/leases/leases))

### Track renovation
1. `PUT /api/places/{id}/estates/{id}` — Update `renovation_date` and `other_detail`
2. Energy diagnosis may need updating after renovation ([Energy Diagnosis API](/compliance/energy-diagnosis))

---

## Overview

Estates are individual property units that belong to places (buildings or complexes). Each estate contains:
- **Physical Attributes**: Area, rooms, orientation, floor
- **Financial Information**: Taxes, acquisition price, property values
- **Legal Details**: Lot numbers, fiscal identifiers
- **Ownership**: Current and previous owner tracking
- **Room Management**: Nested room structure for detailed space management
- **Energy Diagnostics**: Energy performance assessments

## Authentication

All endpoints require authentication with the following permissions:
- **PropertiesRead**: For GET operations
- **PropertiesWrite**: For POST and PUT operations  
- **PropertiesDelete**: For DELETE operations

## Base URL

Estate endpoints are nested under places: `/api/places/{place_id}/estates`

---

## Core Estate Operations

### List Estates
**GET** `/api/places/{place_id}/estates`

Retrieve all estates belonging to a specific place.

**Path Parameters:**
- `place_id` (UUID): The place ID

**Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "T3 - Apt 401",
    "place_id": "550e8400-e29b-41d4-a716-446655440010",
    "estate_type_id": "550e8400-e29b-41d4-a716-446655440020",
    "area": 75.5,
    "number_of_room": 3,
    "orientation": "South",
    "building": "Building A",
    "floor": 4,
    "owner_id": "550e8400-e29b-41d4-a716-446655440030",
    "previous_owner_id": null,
    "lot_number": "LOT-A-401",
    "fiscal_identifier": "13001-B-0123",
    "housing_tax": 850.00,
    "property_tax": 1200.00,
    "acquisition_price": 180000.00,
    "rent_amount": 1200.00,
    "rental_status": "RENTED",
    "construction_date": "2010-06-15T00:00:00",
    "renovation_date": "2018-03-20T00:00:00",
    "address": "123 Rue de la Paix, Apt 401",
    "other_detail": "Corner unit with balcony",
    "created_at": "2024-01-15T10:30:00",
    "updated_at": "2024-01-15T10:30:00"
  }
]
```

### Create Estate
**POST** `/api/places/{place_id}/estates`

Create a new estate within a place.

**Path Parameters:**
- `place_id` (UUID): The place ID

**Request Body:**
```json
{
  "name": "T2 - Apt 203",
  "estate_type_id": "550e8400-e29b-41d4-a716-446655440020",
  "area": 62.0,
  "fiscal_identifier": "13001-B-0124",
  "number_of_room": 2,
  "orientation": "North-West",
  "building": "Building B",
  "floor": 2,
  "lot_number": "LOT-B-203",
  "housing_tax": 650.00,
  "property_tax": 900.00,
  "acquisition_price": 145000.00,
  "construction_date": "2010-06-15T00:00:00",
  "renovation_date": "2020-01-15T00:00:00",
  "address": "123 Rue de la Paix, Apt 203",
  "other_detail": "Recently renovated with modern fixtures"
}
```

**Response:** `201 Created`
Returns the created estate object with generated ID and timestamps.

### Get Estate
**GET** `/api/places/{place_id}/estates/{estate_id}`

Retrieve a specific estate by ID within a place.

**Path Parameters:**
- `place_id` (UUID): The place ID
- `estate_id` (UUID): The estate ID

**Response:** `200 OK`
Returns the estate object.

### Update Estate
**PUT** `/api/places/{place_id}/estates/{estate_id}`

Update an existing estate. All fields are optional in update requests.

**Path Parameters:**
- `place_id` (UUID): The place ID
- `estate_id` (UUID): The estate ID

**Request Body:**
```json
{
  "area": 65.0,
  "number_of_room": 3,
  "renovation_date": "2024-02-15T00:00:00",
  "other_detail": "Updated with new kitchen and bathroom"
}
```

**Response:** `200 OK`
Returns the updated estate object.

### Delete Estate
**DELETE** `/api/places/{place_id}/estates/{estate_id}`

Delete an estate from a place.

**Path Parameters:**
- `place_id` (UUID): The place ID  
- `estate_id` (UUID): The estate ID

**Response:** `204 No Content`

---

## Nested Resources

### Rooms Management
**See [Rooms API](/properties/rooms)** for detailed room operations within estates.

Estates can contain multiple rooms accessed through:
- **GET** `/api/places/{place_id}/estates/{estate_id}/rooms`
- **POST** `/api/places/{place_id}/estates/{estate_id}/rooms`
- And other room-specific endpoints

### Energy Diagnostics
**See [Energy Diagnosis API](/compliance/energy-diagnosis)** for energy performance assessments.

Energy diagnostics for estates accessed through:
- **GET** `/api/places/{place_id}/estates/{estate_id}/energy-diagnoses`

---

## Data Types and Structures

### Estate Object

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Generated estate ID |
| `name` | string | Property name (e.g. "T3 - Apt 401") |
| `place_id` | UUID | Parent place ID |
| `estate_type_id` | UUID | Reference to estate type |
| `area` | number | Area in square meters |
| `number_of_room` | integer | Number of rooms |
| `orientation` | string | Compass orientation |
| `building` | string | Building identifier |
| `floor` | integer | Floor number |
| `owner_id` | UUID | Current owner ID |
| `previous_owner_id` | UUID | Previous owner ID |
| `lot_number` | string | Legal lot number |
| `fiscal_identifier` | string | Tax/fiscal identifier |
| `housing_tax` | number | Annual housing tax |
| `property_tax` | number | Annual property tax |
| `acquisition_price` | number | Purchase price |
| `rent_amount` | number | Reference rent amount (euros). Auto-synced with active leases. |
| `rental_status` | enum | `VACANT`, `RENTED`, `NOTICE`. Auto-synced with lease status. |
| `construction_date` | datetime | Construction date |
| `renovation_date` | datetime | Last renovation date |
| `address` | string | Full address |
| `other_detail` | string | Additional details |
| `created_at` | datetime | Creation timestamp |
| `updated_at` | datetime | Last update timestamp |

### Required Fields for Creation

`name` (1-255 chars), `estate_type_id`, `area`, `fiscal_identifier` (1-50 chars)

### Update Estate Request
All fields are optional. Absent fields are preserved, `null` removes the value. The `place_id` field can be changed via the flat route `PUT /estates/{id}` to move a property to another place.

---

## Common Orientations

Typical values for the `orientation` field:
- `North`
- `South`
- `East`
- `West`
- `North-East`
- `North-West`
- `South-East`
- `South-West`

---

## Error Responses

### Validation Errors
**400 Bad Request**
```json
{
  "error": "ValidationError",
  "message": "Invalid input data",
  "details": [
    {
      "field": "area",
      "message": "Area must be greater than 0"
    },
    {
      "field": "estate_type_id",
      "message": "Invalid estate type ID format"
    }
  ]
}
```

### Not Found
**404 Not Found**
```json
{
  "error": "NotFound",
  "message": "Estate with id {estate_id} not found under place {place_id}"
}
```

### Place Validation Error
When estate doesn't belong to the specified place:
```json
{
  "error": "NotFound", 
  "message": "Estate with id {estate_id} not found under place {place_id}"
}
```

---

## Common Use Cases

### Creating a New Apartment
1. Identify the parent place (building)
2. Choose appropriate estate type (apartment)
3. Create estate with `POST /api/places/{place_id}/estates`
4. Add rooms using the rooms API
5. Attach energy diagnostics if required

### Property Tax Management
1. Get estate with `GET /api/places/{place_id}/estates/{estate_id}`
2. Update tax values with `PUT /api/places/{place_id}/estates/{estate_id}`
3. Track historical changes through timestamps

### Renovation Tracking
1. Update `renovation_date` when work is completed
2. Use `other_detail` to describe renovation scope
3. Update area if renovations change square footage

### Ownership Transfer
1. Update `previous_owner_id` with current `owner_id`
2. Set new `owner_id`
3. Update `acquisition_price` if applicable

### Multi-Building Management
1. Use `building` field to identify specific buildings
2. Use `floor` for vertical organization
3. Use `lot_number` for legal subdivision tracking

---

## Business Rules

- **Area Validation**: Area must be greater than 0
- **Place Association**: Estates must belong to exactly one place
- **Owner Tracking**: Previous owner is automatically set during ownership transfers
- **Type Reference**: Estate type must exist in the types system
- **Nested Updates**: Updating estate also updates the `updated_at` timestamp
- **Deletion Constraints**: Cannot delete estates with active leases or rooms

---

## Integration Notes

- **Estate Types**: Reference to the [Types API](/api) for estate categorization
- **Owners**: Integration with owner management system
- **Rooms**: Estates can contain multiple rooms with detailed layouts
- **Leases**: Estates are the primary unit for lease agreements
- **Energy Diagnostics**: Required for certain property types and regulations
- **Financial Calculations**: Tax values used for lease calculations and reporting