budget-tracker/.specify/memory/contracts/api.md

Contrats API REST — Budget Tracker

Version : 1.0.0 | Base URL : /api/v1 | Format : JSON

Conventions

• Tous les montants sont en centimes (integer)
• Authentification : Authorization: Bearer <access_token>
• Dates : ISO 8601 (YYYY-MM-DD)
• Mois : YYYY-MM
• Soft-delete : les ressources supprimées retournent 404
• Erreurs : {"detail": "message d'erreur"}

---

Authentification

POST /auth/register

Créer un compte utilisateur.

Body :

{"email": "user@example.com", "password": "...", "full_name": "Jean Dupont"}

Réponse 201 :

{"id": "uuid", "email": "user@example.com", "full_name": "Jean Dupont"}

POST /auth/login

Obtenir les tokens JWT.

Body : application/x-www-form-urlencoded : username=email&password=...

Réponse 200 :

{"access_token": "...", "refresh_token": "...", "token_type": "bearer"}

POST /auth/refresh

Renouveler l'access token.

Body : {"refresh_token": "..."} Réponse 200 : {"access_token": "...", "token_type": "bearer"}

POST /auth/logout

Invalider le refresh token. Réponse 204 : no content

---

Transactions

GET /transactions

Lister les transactions (paginées, filtrables).

Query params : ?month=2026-03&category_id=uuid&type=expense&page=1&per_page=20

Réponse 200 :

{
  "items": [
    {
      "id": "uuid",
      "amount_cents": 4500,
      "type": "expense",
      "description": "Courses Leclerc",
      "category": {"id": "uuid", "name": "Alimentation", "color": "#4CAF50"},
      "transaction_date": "2026-03-15",
      "created_at": "2026-03-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

POST /transactions

Créer une transaction.

Body :

{
  "amount_cents": 4500,
  "type": "expense",
  "category_id": "uuid",
  "description": "Courses Leclerc",
  "transaction_date": "2026-03-15"
}

Réponse 201 : transaction complète

GET /transactions/{id}

Détail d'une transaction. Réponse 200 : transaction complète

PUT /transactions/{id}

Modifier une transaction. Body : mêmes champs que POST. Réponse 200 : transaction mise à jour

DELETE /transactions/{id}

Soft-delete. Réponse 204 : no content

---

Catégories

GET /categories

Lister les catégories de l'utilisateur (y compris les défauts système).

Query : ?type=expense

Réponse 200 :

[
  {"id": "uuid", "name": "Alimentation", "type": "expense", "color": "#4CAF50", "icon": "shopping-cart", "is_default": true}
]

POST /categories

Créer une catégorie personnalisée.

Body : {"name": "Loisirs", "type": "expense", "color": "#9C27B0", "icon": "gamepad"} Réponse 201 : catégorie créée

PUT /categories/{id}

Modifier une catégorie. Réponse 200 : catégorie mise à jour

DELETE /categories/{id}

Soft-delete. Erreur 409 si des transactions y sont liées.

---

Budgets (Enveloppes)

GET /budgets

Lister les budgets du mois courant ou d'un mois donné.

Query : ?month=2026-03

Réponse 200 :

[
  {
    "id": "uuid",
    "category": {"id": "uuid", "name": "Alimentation"},
    "month": "2026-03",
    "limit_cents": 30000,
    "spent_cents": 12500,
    "remaining_cents": 17500,
    "percentage_used": 41.7
  }
]

POST /budgets

Définir un budget pour une catégorie/mois.

Body : {"category_id": "uuid", "month": "2026-03", "limit_cents": 30000} Réponse 201 : budget créé

PUT /budgets/{id}

Modifier la limite d'un budget. Réponse 200 : budget mis à jour

DELETE /budgets/{id}

Supprimer un budget. Réponse 204

---

Dashboard

GET /dashboard

KPIs du mois courant ou d'un mois donné.

Query : ?month=2026-03

Réponse 200 :

{
  "month": "2026-03",
  "balance_cents": 150000,
  "total_income_cents": 250000,
  "total_expense_cents": 100000,
  "by_category": [
    {"category_id": "uuid", "name": "Alimentation", "total_cents": 45000, "percentage": 45.0}
  ],
  "monthly_trend": [
    {"month": "2026-01", "income_cents": 240000, "expense_cents": 110000},
    {"month": "2026-02", "income_cents": 245000, "expense_cents": 95000},
    {"month": "2026-03", "income_cents": 250000, "expense_cents": 100000}
  ],
  "budget_alerts": [
    {"category_id": "uuid", "name": "Loisirs", "percentage_used": 92.0, "status": "warning"}
  ]
}

---

Historique

GET /history

Résumé mensuel navigable.

Query : ?year=2026

Réponse 200 :

[
  {
    "month": "2026-03",
    "income_cents": 250000,
    "expense_cents": 100000,
    "balance_cents": 150000,
    "transaction_count": 42
  }
]

---

Export

GET /export/csv

Exporter les transactions en CSV.

Query : ?month=2026-03 (optionnel — tout exporter si absent) Réponse 200 : Content-Type: text/csv, fichier transactions_2026-03.csv

GET /export/pdf

Exporter le rapport mensuel en PDF.

Query : ?month=2026-03 Réponse 200 : Content-Type: application/pdf, fichier rapport_2026-03.pdf

---

Codes d'erreur

Code	Signification
400	Données invalides (validation Pydantic)
401	Token manquant ou expiré
403	Ressource appartenant à un autre utilisateur
404	Ressource introuvable (ou soft-deleted)
409	Conflit (doublon, contrainte métier)
422	Erreur de validation (détail par champ)
500	Erreur serveur