petitspas/docs/11_API.md

# 🌐 Documentation API

## Vue d'ensemble

L'API PtitsPas est une API REST construite avec **NestJS**.

**URL de base** : `https://app.ptits-pas.fr/api/v1`  
**Format** : JSON  
**Authentication** : JWT Bearer Token

---

## Authentication

Toutes les routes (sauf `/auth/login`, `/auth/register`, `/auth/refresh`) nécessitent un token JWT dans le header :

```http
Authorization: Bearer <access_token>
```

### Tokens

L'API utilise deux types de tokens :
- **Access Token** : Durée de vie courte, utilisé pour les requêtes API
- **Refresh Token** : Durée de vie longue, utilisé pour renouveler l'access token

---

## Endpoints

### 🔐 Authentification (`/auth`)

#### POST `/auth/login`

Connexion d'un utilisateur.

**Public** : ✅ Oui

**Request Body** :
```json
{
  "email": "admin@ptits-pas.fr",
  "password": "4dm1n1strateur"
}
```

**Response** (200) :
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "email": "admin@ptits-pas.fr",
    "role": "super_admin",
    "prenom": "Admin",
    "nom": "Système"
  }
}
```

**Errors** :
- `401` : Email ou mot de passe incorrect
- `403` : Compte suspendu ou en attente de validation

---

#### POST `/auth/register`

Inscription d'un nouvel utilisateur (parent ou assistante maternelle).

**Public** : ✅ Oui

**Request Body** :
```json
{
  "email": "parent@example.com",
  "password": "motdepasse123",
  "prenom": "Jean",
  "nom": "Dupont",
  "role": "parent",
  "telephone": "0601020304"
}
```

**Response** (201) :
```json
{
  "message": "Inscription réussie. Votre compte est en attente de validation.",
  "userId": "uuid"
}
```

**Errors** :
- `409` : Email déjà utilisé
- `400` : Données invalides

---

#### POST `/auth/refresh`

Rafraîchir l'access token à l'aide du refresh token.

**Public** : ✅ Oui

**Request Body** :
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Response** (200) :
```json
{
  "access_token": "nouveau_token...",
  "refresh_token": "nouveau_refresh_token..."
}
```

**Errors** :
- `401` : Token de rafraîchissement invalide ou expiré

---

#### GET `/auth/me`

Récupérer le profil de l'utilisateur connecté.

**Auth** : 🔒 Requis

**Response** (200) :
```json
{
  "id": "uuid",
  "email": "admin@ptits-pas.fr",
  "role": "super_admin",
  "prenom": "Admin",
  "nom": "Système",
  "statut": "actif"
}
```

---

#### POST `/auth/logout`

Déconnexion (invalide le refresh token).

**Auth** : 🔒 Requis

**Response** (200) :
```json
{
  "message": "Déconnexion réussie"
}
```

---

### 👥 Utilisateurs (`/users`)

**Auth** : 🔒 Requis pour toutes les routes

#### GET `/users`

Liste tous les utilisateurs.

**Rôles autorisés** : `super_admin`

**Response** (200) :
```json
[
  {
    "id": "uuid",
    "email": "user@example.com",
    "role": "parent",
    "prenom": "Jean",
    "nom": "Dupont",
    "statut": "actif",
    "cree_le": "2025-01-15T10:30:00Z"
  }
]
```

---

#### GET `/users/:id`

Récupérer un utilisateur par son ID.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Response** (200) :
```json
{
  "id": "uuid",
  "email": "user@example.com",
  "role": "parent",
  "prenom": "Jean",
  "nom": "Dupont",
  "telephone": "0601020304",
  "statut": "actif"
}
```

**Errors** :
- `404` : Utilisateur non trouvé
- `403` : Accès refusé

---

#### POST `/users`

Créer un nouvel utilisateur.

**Rôles autorisés** : `super_admin`

**Request Body** :
```json
{
  "email": "newuser@example.com",
  "password": "password123",
  "role": "gestionnaire",
  "prenom": "Marie",
  "nom": "Martin"
}
```

**Response** (201) :
```json
{
  "id": "uuid",
  "email": "newuser@example.com",
  "role": "gestionnaire"
}
```

---

#### PATCH `/users/:id`

Mettre à jour un utilisateur.

**Rôles autorisés** : `super_admin`

**Request Body** (tous les champs sont optionnels) :
```json
{
  "prenom": "Jean-Claude",
  "telephone": "0612345678",
  "adresse": "1 rue de la Paix, 75001 Paris"
}
```

**Response** (200) :
```json
{
  "id": "uuid",
  "email": "user@example.com",
  "prenom": "Jean-Claude",
  "telephone": "0612345678"
}
```

---

#### PATCH `/users/:id/valider`

Valider un compte utilisateur en attente.

**Rôles autorisés** : `super_admin`, `gestionnaire`, `administrateur`

**Request Body** :
```json
{
  "comment": "Compte validé après vérification des documents"
}
```

**Response** (200) :
```json
{
  "message": "Compte validé avec succès",
  "userId": "uuid"
}
```

---

#### PATCH `/users/:id/suspendre`

Suspendre un compte utilisateur.

**Rôles autorisés** : `super_admin`, `gestionnaire`, `administrateur`

**Request Body** :
```json
{
  "comment": "Compte suspendu pour non-respect des conditions"
}
```

**Response** (200) :
```json
{
  "message": "Compte suspendu",
  "userId": "uuid"
}
```

---

#### DELETE `/users/:id`

Supprimer un utilisateur.

**Rôles autorisés** : `super_admin`

**Response** (200) :
```json
{
  "message": "Utilisateur supprimé"
}
```

---

### 🏢 Gestionnaires (`/gestionnaires`)

**Auth** : 🔒 Requis pour toutes les routes

#### GET `/gestionnaires`

Liste tous les gestionnaires.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Response** (200) :
```json
[
  {
    "id": "uuid",
    "email": "gestionnaire@ptits-pas.fr",
    "role": "gestionnaire",
    "prenom": "Sophie",
    "nom": "Leroy"
  }
]
```

---

#### GET `/gestionnaires/:id`

Récupérer un gestionnaire par son ID.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Response** (200) : Identique à `/users/:id`

---

#### POST `/gestionnaires`

Créer un nouveau gestionnaire.

**Rôles autorisés** : `super_admin`

**Request Body** :
```json
{
  "email": "nouveau.gestionnaire@ptits-pas.fr",
  "password": "password123",
  "prenom": "Laurent",
  "nom": "Bernard"
}
```

**Response** (201) :
```json
{
  "id": "uuid",
  "email": "nouveau.gestionnaire@ptits-pas.fr",
  "role": "gestionnaire"
}
```

---

#### PATCH `/gestionnaires/:id`

Mettre à jour un gestionnaire.

**Rôles autorisés** : `super_admin`

**Request Body** : Identique à `/users/:id` (PATCH)

---

### 👶 Parents (`/parents`)

**Auth** : 🔒 Requis pour toutes les routes

#### GET `/parents`

Liste tous les parents.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Response** (200) :
```json
[
  {
    "id_utilisateur": "uuid",
    "id_co_parent": "uuid",
    "utilisateur": {
      "email": "parent@example.com",
      "prenom": "Jean",
      "nom": "Dupont"
    }
  }
]
```

---

#### GET `/parents/:id`

Récupérer un parent par son ID utilisateur.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Response** (200) :
```json
{
  "id_utilisateur": "uuid",
  "id_co_parent": "uuid",
  "utilisateur": {
    "email": "parent@example.com",
    "prenom": "Jean",
    "nom": "Dupont",
    "telephone": "0601020304"
  }
}
```

---

#### POST `/parents`

Créer un nouveau parent.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Request Body** :
```json
{
  "email": "parent@example.com",
  "password": "password123",
  "prenom": "Jean",
  "nom": "Dupont",
  "telephone": "0601020304",
  "id_co_parent": "uuid" // optionnel
}
```

**Response** (201) : Identique à GET

---

#### PATCH `/parents/:id`

Mettre à jour un parent.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Request Body** :
```json
{
  "id_co_parent": "uuid",
  "telephone": "0612345678"
}
```

---

### 👧 Enfants (`/enfants`)

**Auth** : 🔒 Requis pour toutes les routes

#### GET `/enfants`

Liste tous les enfants.

**Rôles autorisés** : `super_admin`, `gestionnaire`, `administrateur`

**Response** (200) :
```json
[
  {
    "id": "uuid",
    "prenom": "Alice",
    "nom": "Dupont",
    "genre": "F",
    "date_naissance": "2020-05-15",
    "statut": "actif"
  }
]
```

---

#### GET `/enfants/:id`

Récupérer un enfant par son ID.

**Rôles autorisés** : `super_admin`, `gestionnaire`, `administrateur`, `parent` (si c'est son enfant)

**Response** (200) :
```json
{
  "id": "uuid",
  "prenom": "Alice",
  "nom": "Dupont",
  "genre": "F",
  "date_naissance": "2020-05-15",
  "statut": "actif",
  "consentement_photo": false
}
```

---

#### POST `/enfants`

Créer un nouvel enfant.

**Rôles autorisés** : `parent`

**Request Body** :
```json
{
  "prenom": "Alice",
  "nom": "Dupont",
  "genre": "F",
  "date_naissance": "2020-05-15",
  "statut": "actif"
}
```

**Response** (201) : Identique à GET

---

#### PATCH `/enfants/:id`

Mettre à jour un enfant.

**Rôles autorisés** : `super_admin`, `administrateur`, `parent` (si c'est son enfant)

**Request Body** :
```json
{
  "statut": "scolarise",
  "consentement_photo": true
}
```

---

#### DELETE `/enfants/:id`

Supprimer un enfant.

**Rôles autorisés** : `super_admin`

**Response** (200) :
```json
{
  "message": "Enfant supprimé"
}
```

---

### 👩‍🍼 Assistantes Maternelles (`/assistantes-maternelles`)

**Auth** : 🔒 Requis pour toutes les routes

#### GET `/assistantes-maternelles`

Liste toutes les assistantes maternelles.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Response** (200) :
```json
[
  {
    "id_utilisateur": "uuid",
    "numero_agrement": "AM123456",
    "nb_max_enfants": 4,
    "place_disponible": 2,
    "disponible": true,
    "utilisateur": {
      "email": "am@example.com",
      "prenom": "Marie",
      "nom": "Martin"
    }
  }
]
```

---

#### GET `/assistantes-maternelles/:id`

Récupérer une assistante maternelle par son ID utilisateur.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Response** (200) :
```json
{
  "id_utilisateur": "uuid",
  "numero_agrement": "AM123456",
  "nir_chiffre": "123456789012345",
  "nb_max_enfants": 4,
  "place_disponible": 2,
  "biographie": "Assistante maternelle depuis 10 ans...",
  "disponible": true,
  "ville_residence": "Paris",
  "date_agrement": "2015-06-01",
  "annee_experience": 10,
  "specialite": "Pédagogie Montessori"
}
```

---

#### POST `/assistantes-maternelles`

Créer une nouvelle assistante maternelle.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Request Body** :
```json
{
  "email": "am@example.com",
  "password": "password123",
  "prenom": "Marie",
  "nom": "Martin",
  "numero_agrement": "AM123456",
  "nb_max_enfants": 4,
  "ville_residence": "Paris"
}
```

**Response** (201) : Identique à GET

---

#### PATCH `/assistantes-maternelles/:id`

Mettre à jour une assistante maternelle.

**Rôles autorisés** : `super_admin`, `gestionnaire`

**Request Body** :
```json
{
  "place_disponible": 1,
  "disponible": true,
  "biographie": "Nouvelle bio..."
}
```

---

#### DELETE `/assistantes-maternelles/:id`

Supprimer une assistante maternelle.

**Rôles autorisés** : `super_admin`, `gestionnaire`, `administrateur`

**Response** (200) :
```json
{
  "message": "Assistante maternelle supprimée"
}
```

---

### 🏠 Root (`/`)

#### GET `/`

Aperçu de l'API.

**Public** : ✅ Oui

**Response** (200) :
```json
{
  "message": "Bienvenue sur l'API PtitsPas",
  "version": "1.0.0",
  "endpoints": {
    "auth": "/api/v1/auth",
    "users": "/api/v1/users",
    "parents": "/api/v1/parents",
    "enfants": "/api/v1/enfants",
    "assistantes-maternelles": "/api/v1/assistantes-maternelles",
    "gestionnaires": "/api/v1/gestionnaires"
  }
}
```

---

#### GET `/hello`

Endpoint de test.

**Public** : ✅ Oui

**Response** (200) :
```text
Hello World!
```

---

## Codes d'erreur HTTP

| Code | Signification | Explication |
|------|---------------|-------------|
| `200` | OK | Requête réussie |
| `201` | Created | Ressource créée |
| `400` | Bad Request | Données invalides |
| `401` | Unauthorized | Non authentifié ou token invalide |
| `403` | Forbidden | Accès refusé (rôle insuffisant) |
| `404` | Not Found | Ressource non trouvée |
| `409` | Conflict | Conflit (ex: email déjà existant) |
| `500` | Internal Server Error | Erreur serveur |

---

## Format des réponses d'erreur

```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
```

Ou avec détails :

```json
{
  "statusCode": 403,
  "message": "Accès refusé : rôle insuffisant",
  "error": "Forbidden"
}
```

---

## Authentification et Rôles

### Hiérarchie des rôles

1. **super_admin** : Accès total
2. **administrateur** : Gestion des utilisateurs
3. **gestionnaire** : Gestion des dossiers et validation
4. **assistante_maternelle** : Accès à ses propres données
5. **parent** : Accès à ses propres données et enfants

### Guards

L'API utilise deux guards :
- **AuthGuard** : Vérifie la validité du token JWT
- **RolesGuard** : Vérifie que l'utilisateur a le bon rôle

### Décorateurs

- `@Public()` : Route accessible sans authentification
- `@Roles(...roles)` : Restreint l'accès aux rôles spécifiés
- `@User()` : Injecte l'utilisateur connecté dans le contrôleur

---

## Swagger / OpenAPI

L'API expose automatiquement sa documentation Swagger :

**URL** : `https://app.ptits-pas.fr/api/docs`

Cette documentation interactive permet de :
- Visualiser tous les endpoints
- Tester les requêtes directement
- Voir les schémas de données

---

## Exemples d'utilisation

### Connexion et récupération du profil

```bash
# 1. Login
curl -X POST https://app.ptits-pas.fr/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@ptits-pas.fr","password":"4dm1n1strateur"}'

# Response
{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc..."
}

# 2. Récupérer son profil
curl https://app.ptits-pas.fr/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGc..."
```

### Créer un parent

```bash
curl -X POST https://app.ptits-pas.fr/api/v1/parents \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "parent@example.com",
    "password": "password123",
    "prenom": "Jean",
    "nom": "Dupont",
    "telephone": "0601020304"
  }'
```

---

## Limitations et Rate Limiting

**Actuellement** : Aucune limitation n'est active.

**À implémenter** :
- Rate limiting (ex: 100 requêtes/minute)
- Pagination pour les listes longues
- Filtrage et tri sur les endpoints de liste

---

## Évolutions prévues

- [ ] Endpoints pour les dossiers (`/dossiers`)
- [ ] Endpoints pour les contrats (`/contrats`)
- [ ] Endpoints pour les événements (`/evenements`)
- [ ] Endpoints pour les messages (`/messages`)
- [ ] Endpoints pour les notifications (`/notifications`)
- [ ] WebSocket pour les notifications en temps réel
- [ ] Upload de fichiers (`/uploads`)
- [ ] Génération de PDF (contrats)

---

**Dernière mise à jour** : Novembre 2025