# Security Deposit (Dépôt de garantie)

Manage security deposits for leases in compliance with **Art. 22 of Loi 89-462**. The system handles collection, restitution with automatic deadline calculation, retention validation (max 20% for charges), and late penalty computation (10% monthly rent per month of delay).

## Quick Example

```bash
# Record a security deposit
curl -X POST https://api.faireplace.com/api/leases/<lease_id>/deposit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 750.00,
    "paid_date": "2026-01-15"
  }'
```

```json
{
  "id": "a1b2c3d4-...",
  "lease_id": "...",
  "amount": 750.00,
  "paid_date": "2026-01-15",
  "status": "COLLECTED",
  "exit_inspection_conformity": true,
  "restitution_due_date": null,
  "restitution_date": null,
  "amount_returned": null,
  "retained_for_charges": null,
  "retained_for_damages": null,
  "retained_for_unpaid_rent": null,
  "penalty_amount": null
}
```

## Common Workflows

### Collect a deposit at lease start
1. Create the [lease](/leases/leases) with `deposit_amount` set
2. `POST /api/leases/{id}/deposit` — record the collection with amount and date

### Return the deposit at lease end
1. `POST /api/leases/{id}/deposit/return` — provide exit inspection result, retentions, and return date
2. The system automatically calculates:
   - Restitution deadline (1 or 2 months)
   - Amount to return (deposit minus retentions)
   - Late penalty if applicable

### Return with co-ownership charge retention
When the property is in a co-ownership (copropriété), up to 20% of the deposit can be retained pending syndic account approval:

```bash
curl -X POST https://api.faireplace.com/api/leases/<lease_id>/deposit/return \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exit_inspection_conformity": true,
    "lease_end_date": "2026-03-31",
    "restitution_date": "2026-04-15",
    "retained_for_charges": 150.00,
    "copro_accounts_approval_date": null,
    "notes": "Retenue provision charges copropriété en attente approbation syndic"
  }'
```

The deposit status becomes `PARTIALLY_RETURNED`. The retained amount must be released after syndic account approval.

---

## Authentication

All endpoints require authentication:
- **LeasesRead**: GET operations
- **LeasesWrite**: POST operations (record, return)
- **LeasesDelete**: DELETE operations

---

## Key Concepts

### Deposit Lifecycle

```
COLLECTED → PENDING_RETURN → FULLY_RETURNED
                           → PARTIALLY_RETURNED (charge retention)
                           → DISPUTED
```

### Restitution Deadline (Art. 22)

| Exit inspection | Deadline |
|----------------|----------|
| Conformity (no issues) | **1 month** after lease end |
| Non-conformity (damages found) | **2 months** after lease end |

### Retention Limits

| Type | Limit | Legal basis |
|------|-------|-------------|
| Co-ownership charges | **Max 20%** of deposit | Art. 22 Loi 89-462 |
| Damages | Justified amount | Supported by exit inspection |
| Unpaid rent | Justified amount | Outstanding balance |
| **Total retentions** | **Cannot exceed deposit** | — |

### Late Return Penalty

If the deposit is returned after the restitution deadline:
- **10% of monthly rent (HC) per full month of delay**
- Partial months are not counted
- Automatically calculated by the system

**Example:** Monthly rent = 750 €, 3 months late → penalty = 3 × 75 € = **225 €**

### Deposit Amount Limits by Lease Type

| Lease type | Maximum deposit |
|-----------|----------------|
| Residential empty (bail nu) | 1 month rent |
| Furnished / Student | 2 months rent |
| Commercial | 3 months rent |
| Mobility lease (bail mobilité) | **Forbidden** (Art. 25-13 ALUR) |

These limits are enforced at the lease level when setting `deposit_amount`.

---

## Endpoints

### Record a deposit

```
POST /api/leases/{lease_id}/deposit
```

Records the collection of a security deposit. Only one deposit per lease is allowed.

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | decimal | Yes | Deposit amount (must be positive) |
| `paid_date` | date | No | Date the deposit was collected |

**Response:** `201 Created` — `SecurityDeposit` object

---

### Get deposit details

```
GET /api/leases/{lease_id}/deposit
```

**Response:** `200 OK` — `SecurityDeposit` object

---

### Return a deposit

```
POST /api/leases/{lease_id}/deposit/return
```

Records the restitution. The system validates retentions and computes penalties automatically.

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exit_inspection_conformity` | boolean | Yes | Conformity → 1-month deadline, non-conformity → 2-month |
| `lease_end_date` | date | Yes | End date of the lease |
| `restitution_date` | date | Yes | Actual return date |
| `retained_for_charges` | decimal | No | Max 20% of deposit (co-ownership) |
| `retained_for_damages` | decimal | No | Justified by exit inspection |
| `retained_for_unpaid_rent` | decimal | No | Outstanding rent balance |
| `copro_accounts_approval_date` | date | No | Syndic account approval date |
| `notes` | string | No | Additional notes |

**Response:** `200 OK` — Updated `SecurityDeposit` with computed fields

---

### Delete a deposit

```
DELETE /api/leases/{lease_id}/deposit
```

**Response:** `204 No Content`

---

## Deposit Model

| Field | Type | Description |
|-------|------|-------------|
| `id` | uuid | Deposit unique ID |
| `lease_id` | uuid | Associated lease |
| `amount` | decimal | Deposit amount collected |
| `paid_date` | date | Collection date |
| `status` | string | COLLECTED, PENDING_RETURN, PARTIALLY_RETURNED, FULLY_RETURNED, DISPUTED |
| `restitution_due_date` | date | Calculated deadline (1 or 2 months after lease end) |
| `restitution_date` | date | Actual return date |
| `amount_returned` | decimal | Amount returned to tenant |
| `retained_for_charges` | decimal | Retained for co-ownership charges (max 20%) |
| `retained_for_damages` | decimal | Retained for damages |
| `retained_for_unpaid_rent` | decimal | Retained for unpaid rent |
| `penalty_amount` | decimal | Late return penalty (10%/month) |
| `exit_inspection_conformity` | boolean | Exit inspection result |
| `copro_accounts_approval_date` | date | Syndic approval date |
| `notes` | string | Additional notes |

---

## Legal Reference

> **Art. 22, Loi n°89-462 du 6 juillet 1989** : Le dépôt de garantie est restitué dans un délai maximal de **un mois** à compter de la remise en main propre des clés, ou de **deux mois** si l'état des lieux de sortie est non conforme. Le bailleur peut retenir sur le dépôt les sommes restant dues au titre des charges, dans la limite de **20%** du montant du dépôt. À défaut de restitution dans les délais, le dépôt restant dû au locataire produit intérêts au taux légal majoré de **10%** du loyer mensuel hors charges pour chaque mois de retard.

---

## Error Responses

| Status | When |
|--------|------|
| `400` | Invalid amount (negative or zero) |
| `401` | Missing or invalid authentication |
| `403` | Insufficient permissions |
| `404` | Lease or deposit not found |
| `422` | Business rule violation (duplicate deposit, exceeds 20%, already returned) |
| `500` | Server error |