H6N/account
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
account/docs/api.md
GnomeZworc b3fce30c36
 update doc api 
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
2026-06-13 14:09:20 +02:00

8.7 KiB
Raw Blame History

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

Transactions

Une transaction est un échange atomique entre deux participants (comptes ou enveloppes) via des instruments. Chaque côté (source, dest) est soit entièrement renseigné soit entièrement null. Au moins un côté doit exister.

Cas couverts :

Cas Source Dest
Flux entrant (salaire, dépôt) null compte + instrument + quantité
Flux sortant (dépense) compte + instrument + quantité null
Virement / allocation enveloppe compte + instrument + quantité compte + instrument + quantité
Achat de titres compte, EUR, montant compte, ETF, nb parts
Swap crypto wallet, BTC, qté wallet, ETH, qté

Le champ validated indique si la transaction est réelle (true) ou prévisionnelle (false). Les transactions non validées à date dépassée remontent dans ?pending=true (liste "à traiter").

GET /accounts/{id}/transactions

Vue centrée sur le compte : le montant est signé (positif = crédit, négatif = débit). instrument_id est celui du côté du compte concerné. contrepartie_account_id est le compte en face (null si flux externe).

Paramètres de filtre

Paramètre Type Description
validated boolean true ou false
pending boolean true → non validées avec date ≤ aujourd'hui
from string Date de début YYYY-MM-DD
to string Date de fin YYYY-MM-DD

Réponse 200 — triée par date DESC

[
  {
    "id": 1,
    "date": "2026-06-13",
    "montant": 2800.00,
    "instrument_id": 1,
    "tiers": "Employeur",
    "label": "Salaire juin",
    "categorie": "salaire",
    "validated": true
  },
  {
    "id": 2,
    "date": "2026-06-10",
    "montant": -50.00,
    "instrument_id": 1,
    "label": "Courses",
    "categorie": "alimentation",
    "validated": true
  }
]

GET /transactions/{id}

Retourne la transaction brute (tous les champs source/dest).

Réponse 200

{
  "id": 1,
  "date": "2026-06-13",
  "account_dest_id": 1,
  "instrument_dest_id": 1,
  "quantite_dest": 2800,
  "tiers": "Employeur",
  "label": "Salaire juin",
  "categorie": "salaire",
  "validated": true
}

Réponse 404 — introuvable

POST /transactions

Corps

Champ Type Requis Description
date string ✅ YYYY-MM-DD
label string ✅ Libellé
validated boolean Défaut false
account_source_id integer Compte source
instrument_source_id integer Instrument source
quantite_source number Quantité source
account_dest_id integer Compte dest
instrument_dest_id integer Instrument dest
quantite_dest number Quantité dest
tiers string Tiers externe (employeur, commerçant…)
categorie string Catégorie libre

Les trois champs de chaque côté (account, instrument, quantite) doivent être tous renseignés ou tous null.

Réponse 201 — transaction créée (format brut) Réponse 400 — body invalide, label manquant, date manquante, ou violation de la contrainte source/dest

PUT /transactions/{id}

Mise à jour complète. Même corps que POST.

Réponse 200 — transaction mise à jour (format brut) Réponse 404 — introuvable

PATCH /transactions/{id}/validate

Valide ou dé-valide une transaction.

Corps

{ "validated": true }

Réponse 200 — transaction avec le nouveau statut Réponse 404 — introuvable

DELETE /transactions/{id}

Réponse 204