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 :

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 :

{
  "email": "admin@ptits-pas.fr",
  "password": "4dm1n1strateur"
}

Response (200) :

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

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

Response (201) :

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

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200) :

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

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

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

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

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

{
  "email": "newuser@example.com",
  "password": "password123",
  "role": "gestionnaire",
  "prenom": "Marie",
  "nom": "Martin"
}

Response (201) :

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

{
  "prenom": "Jean-Claude",
  "telephone": "0612345678",
  "adresse": "1 rue de la Paix, 75001 Paris"
}

Response (200) :

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

{
  "comment": "Compte validé après vérification des documents"
}

Response (200) :

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

{
  "comment": "Compte suspendu pour non-respect des conditions"
}

Response (200) :

{
  "message": "Compte suspendu",
  "userId": "uuid"
}

---

DELETE /users/:id

Supprimer un utilisateur.

Rôles autorisés : super_admin

Response (200) :

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

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

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

Response (201) :

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

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

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

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

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

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

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

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

{
  "statut": "scolarise",
  "consentement_photo": true
}

---

DELETE /enfants/:id

Supprimer un enfant.

Rôles autorisés : super_admin

Response (200) :

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

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

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

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

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

{
  "message": "Assistante maternelle supprimée"
}

---

🏠 Root (/)

GET /

Aperçu de l'API.

Public : ✅ Oui

Response (200) :

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

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

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

Ou avec détails :

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

# 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

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