account/docs/api.md

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

{ "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

[
  { "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

{ "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

{ "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

[
  {
    "id": 1,
    "nom": "Livret A",
    "type": "livret",
    "devise_reference": "EUR",
    "plafond": 22950
  }
]

---

GET /accounts/{id}

Retourne le compte et ses enveloppes.

Réponse 200

{
  "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

{ "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

[
  {
    "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

{
  "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