# API Reference

Base URL : `http://localhost:8080`

Toutes les réponses sont en `application/json`. Les erreurs retournent `{"error": "message"}`.

---

## Health

### `GET /health`

Vérifie la disponibilité du serveur et de la base de données.

**Réponse `200`**
```json
{ "status": "ok" }
```

**Réponse `503`** — base indisponible

---

## Instruments

Un instrument représente tout actif coté : devise (EUR), action, ETF, crypto.
Le prix EUR vaut toujours 1 et est inséré automatiquement au démarrage.

### `GET /instruments`

Liste tous les instruments.

**Réponse `200`**
```json
[
  { "id": 1, "type": "devise", "code": "EUR", "name": "Euro", "devise_cotation": "EUR" },
  { "id": 2, "type": "etf",    "code": "LU1681043599", "name": "Amundi MSCI World", "devise_cotation": "EUR" }
]
```

---

### `GET /instruments/{id}`

**Réponse `200`**
```json
{ "id": 2, "type": "etf", "code": "LU1681043599", "name": "Amundi MSCI World", "devise_cotation": "EUR" }
```

**Réponse `404`** — instrument introuvable

---

### `POST /instruments`

**Corps**
| Champ | Type | Requis | Description |
|---|---|---|---|
| `type` | string | ✅ | `devise`, `action`, `etf`, `crypto` |
| `code` | string | ✅ | ISIN (actions/ETF), ticker (crypto), code devise |
| `name` | string | ✅ | Nom lisible |
| `devise_cotation` | string | | Devise de cotation (défaut : `EUR`) |

**Réponse `201`**
```json
{ "id": 3, "type": "crypto", "code": "BTC", "name": "Bitcoin", "devise_cotation": "EUR" }
```

> **Pipeline de prix** : le ticker Yahoo Finance (actions/ETF) est résolu automatiquement via OpenFIGI au prochain cycle. L'ID CoinGecko (crypto) est résolu via l'API search CoinGecko. Les résolutions sont mises en cache dans `instrument_ticker_cache`.

---

### `PUT /instruments/{id}`

Même corps que `POST`. Retourne l'instrument mis à jour.

---

### `DELETE /instruments/{id}`

**Réponse `204`** — supprimé

---

## Comptes

Un compte est un conteneur de positions. Son solde est entièrement dérivé des transactions (aucun solde stocké).

Les enveloppes sont des sous-comptes monétaires liés à un compte maître (voir section Enveloppes).
`GET /accounts/{id}` retourne toujours le compte avec sa liste d'enveloppes.

### `GET /accounts`

Liste les comptes maîtres (sans les enveloppes).

**Réponse `200`**
```json
[
  {
    "id": 1,
    "nom": "Livret A",
    "type": "livret",
    "devise_reference": "EUR",
    "plafond": 22950
  }
]
```

---

### `GET /accounts/{id}`

Retourne le compte et ses enveloppes.

**Réponse `200`**
```json
{
  "id": 1,
  "nom": "Livret A",
  "type": "livret",
  "devise_reference": "EUR",
  "plafond": 22950,
  "envelopes": [
    {
      "id": 3,
      "nom": "Vacances",
      "type": "livret",
      "devise_reference": "EUR",
      "master_account_id": 1,
      "objectif": "Road trip USA"
    }
  ]
}
```

**Réponse `404`** — compte introuvable

---

### `POST /accounts`

Crée un compte maître.

**Corps**
| Champ | Type | Requis | Description |
|---|---|---|---|
| `nom` | string | ✅ | Nom du compte |
| `type` | string | ✅ | `courant`, `livret`, `pea`, `cto`, `crypto`, ... |
| `devise_reference` | string | | Devise de référence (défaut : `EUR`) |
| `plafond` | number | | Plafond réglementaire (indicatif) |

**Réponse `201`**
```json
{ "id": 1, "nom": "Livret A", "type": "livret", "devise_reference": "EUR", "plafond": 22950 }
```

---

### `PUT /accounts/{id}`

Met à jour un compte maître. Même corps que `POST`.

---

### `DELETE /accounts/{id}`

Supprime le compte **et toutes ses enveloppes** (CASCADE).

**Réponse `204`**

---

## Enveloppes

Une enveloppe est un sous-compte monétaire rattaché à un compte maître. Elle hérite automatiquement du `type` et de la `devise_reference` de son maître. Le solde est dérivé des transactions, comme pour tout compte.

Règles :
- Un compte maître ne peut pas lui-même être une enveloppe (pas de chaînage)
- Supprimée automatiquement avec son compte maître

### `GET /accounts/{id}/envelopes`

Liste les enveloppes d'un compte.

**Réponse `200`**
```json
[
  {
    "id": 3,
    "nom": "Vacances",
    "type": "livret",
    "devise_reference": "EUR",
    "master_account_id": 1,
    "objectif": "Road trip USA"
  }
]
```

---

### `POST /accounts/{id}/envelopes`

Crée une enveloppe sous le compte `{id}`.

**Corps**
| Champ | Type | Requis | Description |
|---|---|---|---|
| `nom` | string | ✅ | Nom de l'enveloppe |
| `objectif` | string | | Description libre de l'objectif |

**Réponse `201`**
```json
{
  "id": 3,
  "nom": "Vacances",
  "type": "livret",
  "devise_reference": "EUR",
  "master_account_id": 1,
  "objectif": "Road trip USA"
}
```

**Réponse `400`** — le compte est lui-même une enveloppe (chaînage interdit)
**Réponse `404`** — compte introuvable

---

### `PUT /envelopes/{id}`

Met à jour le nom et/ou l'objectif d'une enveloppe.

**Corps**
| Champ | Type | Requis | Description |
|---|---|---|---|
| `nom` | string | ✅ | Nouveau nom |
| `objectif` | string | | Nouvel objectif |

**Réponse `200`** — enveloppe mise à jour
**Réponse `404`** — enveloppe introuvable

---

### `DELETE /envelopes/{id}`

Supprime l'enveloppe.

**Réponse `204`**