247 lines
5.1 KiB
Markdown
247 lines
5.1 KiB
Markdown
# 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`**
|