Spaces:

Liantsoaxx08
/

apiRushscholl

Sleeping

App Files Files Community

apiRushscholl / API_DOCUMENTATION.md

Liantsoaxx08

Initial deployment

a03ac57 6 months ago

preview code

Raw

History Blame Contribute Delete

9.42 kB

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

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:

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

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

{
  "success": true,
  "message": "Candidat créé avec succès",
  "record_id": "recXXXXXXXXXXXXXX",
  "candidate_info": {
    // Toutes les informations du candidat
  }
}

Exemple avec curl:

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

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

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

{
  "success": true,
  "message": "CV uploadé avec succès",
  "file_name": "document.pdf",
  "file_size": 123456,
  "airtable_record_id": "recXXXXXXXXXXXXXX"
}

Exemple avec curl:

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

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

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

{
  "detail": "Candidat non trouvé"
}

413 - Fichier trop volumineux

{
  "detail": "Le fichier est trop volumineux. Taille maximale: 10.0MB"
}

422 - Données invalides

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "Format d'email invalide",
      "type": "value_error"
    }
  ]
}

422 - Valeur BAC non autorisée

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

{
  "detail": "Erreur inattendue lors de la création du candidat"
}

🔧 Configuration

Variables d'environnement (.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 :

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

Ou testez avec Python :

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

📝 Notes importantes

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.
Validation du téléphone: Les numéros sont automatiquement normalisés au format international (+33).
Âge minimum: Le système vérifie que le candidat a au moins 16 ans.
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