API_DOCUMENTATION.md

# API Documentation - Admission Rush School

## 📋 Vue d'ensemble

Cette API permet de gérer les informations des candidats et leurs documents d'admission pour Rush School. Elle est construite avec FastAPI et s'intègre avec Airtable pour le stockage des données.

**URL de base:** `http://localhost:8000/api/v1`

**Documentation interactive:** `http://localhost:8000/docs`

---

## 🚀 Démarrage rapide

### Prérequis
- Python 3.10+
- Variables d'environnement configurées dans `.env`

### Lancer le serveur
```bash
cd /home/liantsoa/Desktop/Work/process-IQ-rush-school-main/backend/admission-api
/home/liantsoa/Desktop/Work/process-IQ-rush-school-main/.venv/bin/python main.py
```

Le serveur démarre sur `http://0.0.0.0:8000`

---

## 📌 Endpoints disponibles

### 1. Santé de l'API

**GET** `/api/v1/admission/health`

Vérifie que l'API fonctionne correctement.

**Réponse:**
```json
{
  "status": "healthy",
  "message": "API Admission is running"
}
```

---

### 2. Créer un candidat

**POST** `/api/v1/admission/candidates`

Crée un nouveau candidat avec ses informations personnelles dans Airtable.

**Corps de la requête:**
```json
{
  "prenom": "Marie",
  "nom_naissance": "Dupont",
  "nom_usage": "Martin",
  "sexe": "Féminin",
  "date_naissance": "1998-06-20",
  "nationalite": "Française",
  "commune_naissance": "Lyon",
  "departement": "69 - Rhône",
  "adresse_residence": "789 Rue Victor Hugo",
  "code_postal": "69001",
  "ville": "Lyon",
  "email": "marie.martin@rushschool.fr",
  "telephone": "0678901234",
  "nir": "2 98 06 69 123 456 78",
  "dernier_diplome_prepare": "Master Marketing",
  "derniere_classe": "Master 2",
  "bac": "BAC +2"
}
```

**Champs obligatoires:**
- `prenom`
- `nom_naissance`
- `sexe` (valeurs: "Féminin" ou "Masculin")
- `date_naissance` (format: YYYY-MM-DD)
- `nationalite`
- `commune_naissance`
- `departement`
- `adresse_residence`
- `code_postal` (5 chiffres)
- `ville`
- `email`
- `telephone`
- `bac` (valeur existante dans Airtable, ex: "BAC +2")

**Champs optionnels:**
- `nom_usage`
- `nir` (format: "X XX XX XX XXX XXX XX")
- `dernier_diplome_prepare`
- `derniere_classe`

**Réponse (201 Created):**
```json
{
  "success": true,
  "message": "Candidat créé avec succès",
  "record_id": "recXXXXXXXXXXXXXX",
  "candidate_info": {
    // Toutes les informations du candidat
  }
}
```

**Exemple avec curl:**
```bash
curl -X POST "http://localhost:8000/api/v1/admission/candidates" \
  -H "Content-Type: application/json" \
  -d '{
    "prenom": "Pierre",
    "nom_naissance": "Laurent",
    "nom_usage": "Laurent",
    "sexe": "Masculin",
    "date_naissance": "1996-04-12",
    "nationalite": "Française",
    "commune_naissance": "Nice",
    "departement": "06",
    "adresse_residence": "789 Boulevard Victor Hugo",
    "code_postal": "06000",
    "ville": "Nice",
    "email": "pierre.laurent@rushschool.fr",
    "telephone": "0687654321",
    "bac": "BAC +2"
  }'
```

---

### 3. Récupérer le profil d'un candidat

**GET** `/api/v1/admission/candidates/{record_id}`

Récupère le profil complet d'un candidat (informations personnelles + statut des documents).

**Paramètres:**
- `record_id`: L'ID Airtable du candidat (commence par "rec")

**Réponse (200 OK):**
```json
{
  "record_id": "recXXXXXXXXXXXXXX",
  "informations_personnelles": {
    "prenom": "Pierre",
    "nom_naissance": "Laurent",
    // ... autres informations
  },
  "documents": {
    "record_id": "recXXXXXXXXXXXXXX",
    "cv": {
      "document_type": "CV",
      "uploaded": false,
      "file_name": null,
      "upload_date": null
    },
    "cin": { /* ... */ },
    "lettre_motivation": { /* ... */ },
    "carte_vitale": { /* ... */ },
    "dernier_diplome": { /* ... */ }
  },
  "created_at": "2026-01-14T11:42:50.000Z",
  "updated_at": null
}
```

---

### 4. Mettre à jour les informations d'un candidat

**PUT** `/api/v1/admission/candidates/{record_id}`

Met à jour les informations personnelles d'un candidat existant.

**Paramètres:**
- `record_id`: L'ID Airtable du candidat

**Corps de la requête:** Même structure que la création

**Réponse (200 OK):**
```json
{
  "success": true,
  "message": "Informations mises à jour avec succès",
  "record_id": "recXXXXXXXXXXXXXX",
  "candidate_info": {
    // Informations mises à jour
  }
}
```

---

### 5. Upload de documents

#### a) Upload CV
**POST** `/api/v1/admission/candidates/{record_id}/documents/cv`

#### b) Upload CIN (Carte d'identité)
**POST** `/api/v1/admission/candidates/{record_id}/documents/cin`

#### c) Upload Lettre de motivation
**POST** `/api/v1/admission/candidates/{record_id}/documents/lettre-motivation`

#### d) Upload Carte vitale
**POST** `/api/v1/admission/candidates/{record_id}/documents/carte-vitale`

#### e) Upload Dernier diplôme
**POST** `/api/v1/admission/candidates/{record_id}/documents/dernier-diplome`

**Paramètres:**
- `record_id`: L'ID Airtable du candidat
- `file`: Le fichier à uploader (multipart/form-data)

**Types de fichiers autorisés:** pdf, doc, docx, jpg, jpeg, png

**Taille maximale:** 10 MB

**Réponse (200 OK):**
```json
{
  "success": true,
  "message": "CV uploadé avec succès",
  "file_name": "document.pdf",
  "file_size": 123456,
  "airtable_record_id": "recXXXXXXXXXXXXXX"
}
```

**Exemple avec curl:**
```bash
curl -X POST "http://localhost:8000/api/v1/admission/candidates/recXXXXXXXXXXXXXX/documents/cv" \
  -F "file=@/chemin/vers/cv.pdf"
```

---

### 6. Statut des documents d'un candidat

**GET** `/api/v1/admission/candidates/{record_id}/documents`

Récupère le statut de tous les documents d'un candidat.

**Paramètres:**
- `record_id`: L'ID Airtable du candidat

**Réponse (200 OK):**
```json
{
  "record_id": "recXXXXXXXXXXXXXX",
  "cv": {
    "document_type": "CV",
    "uploaded": true,
    "file_name": "cv.pdf",
    "upload_date": null
  },
  "cin": { /* ... */ },
  "lettre_motivation": { /* ... */ },
  "carte_vitale": { /* ... */ },
  "dernier_diplome": { /* ... */ }
}
```

---

### 7. Liste de tous les candidats

**GET** `/api/v1/admission/candidates`

Récupère tous les candidats depuis Airtable.

**Réponse (200 OK):**
```json
[
  {
    "id": "recXXXXXXXXXXXXXX",
    "fields": {
      "Prénom": "Pierre",
      "NOM de naissance": "Laurent",
      // ... tous les champs Airtable
    },
    "createdTime": "2026-01-14T11:42:50.000Z"
  }
  // ... autres candidats
]
```

---

## 🗺️ Mapping des colonnes Airtable

| Champ API | Colonne Airtable |
|-----------|------------------|
| `prenom` | Prénom |
| `nom_naissance` | NOM de naissance |
| `nom_usage` | NOM dusage |
| `sexe` | Sexe |
| `date_naissance` | Date de naissance |
| `nationalite` | Nationalité |
| `commune_naissance` | Commune de naissance |
| `departement` | Département |
| `adresse_residence` | Adresse lieu dexécution du contrat |
| `email` | E-mail |
| `telephone` | Téléphone |
| `nir` | NIR |
| `dernier_diplome_prepare` | Dernier diplôme ou titre préparé |
| `derniere_classe` | Dernière classe / année suivie |
| `bac` | BAC |

**Note:** Les champs `code_postal` et `ville` sont acceptés par l'API mais ne sont pas sauvegardés dans Airtable car les colonnes correspondantes n'existent pas.

---

## ⚠️ Erreurs courantes

### 404 - Candidat non trouvé
```json
{
  "detail": "Candidat non trouvé"
}
```

### 413 - Fichier trop volumineux
```json
{
  "detail": "Le fichier est trop volumineux. Taille maximale: 10.0MB"
}
```

### 422 - Données invalides
```json
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "Format d'email invalide",
      "type": "value_error"
    }
  ]
}
```

### 422 - Valeur BAC non autorisée
```json
{
  "detail": "INVALID_MULTIPLE_CHOICE_OPTIONS: Insufficient permissions to create new select option"
}
```
**Solution:** Utiliser une valeur existante dans Airtable (actuellement: "BAC +2")

### 500 - Erreur serveur
```json
{
  "detail": "Erreur inattendue lors de la création du candidat"
}
```

---

## 🔧 Configuration

### Variables d'environnement (.env)

```env
AIRTABLE_API_TOKEN=your_token_here
AIRTABLE_BASE_ID=your_base_id_here
AIRTABLE_TABLE_NAME=Liste des candidats
DEBUG=True
HOST=0.0.0.0
PORT=8000
MAX_FILE_SIZE=10485760
ALLOWED_EXTENSIONS=pdf,doc,docx,jpg,jpeg,png
UPLOAD_DIR=uploads
```

---

## 📚 Ressources

- **Documentation Swagger:** http://localhost:8000/docs
- **Documentation ReDoc:** http://localhost:8000/redoc
- **Schéma OpenAPI:** http://localhost:8000/openapi.json

---

## ✅ Tests

Pour tester l'API, utilisez le script de test fourni :

```bash
cd /home/liantsoa/Desktop/Work/process-IQ-rush-school-main/backend/admission-api
./test_api.sh
```

Ou testez avec Python :

```bash
/home/liantsoa/Desktop/Work/process-IQ-rush-school-main/.venv/bin/python test_personal_info.py
```

---

## 📝 Notes importantes

1. **Apostrophes dans les noms de colonnes:** Les colonnes Airtable "NOM dusage" et "Adresse lieu dexécution du contrat" ne contiennent **pas d'apostrophes** pour éviter les problèmes d'encodage.

2. **Validation du téléphone:** Les numéros sont automatiquement normalisés au format international (+33).

3. **Âge minimum:** Le système vérifie que le candidat a au moins 16 ans.

4. **Champ BAC:** Seules les valeurs pré-configurées dans Airtable sont acceptées. Il faut ajouter les nouvelles valeurs manuellement dans Airtable.

---

*Dernière mise à jour: 14 janvier 2026*