update doc api

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>

docs/api.md

@@ -245,3 +245,139 @@ Met à jour le nom et/ou l'objectif d'une enveloppe.
 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
+```json
+[
+  {
+    "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`**
+```json
+{
+  "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**
+```json
+{ "validated": true }
+```
+
+**Réponse `200`** — transaction avec le nouveau statut
+**Réponse `404`** — introuvable
+
+---
+
+### `DELETE /transactions/{id}`
+
+**Réponse `204`**