Documentation des Endpoints API Backend

Documentation succinte des endpoints du backend pour les nouveaux développeurs

Base URL : http://localhost:${API_DOCKER_EXPOSED_PORT:-3017}
Swagger : http://localhost:${API_DOCKER_EXPOSED_PORT:-3017}/swagger-api-dema1n

Authentification

Tous les endpoints (sauf ceux explicitement marqués comme publics) nécessitent un token JWT dans le header :

Authorization: Bearer <token>

Rôles disponibles

• admin : Administrateur standard
• superadmin : Super administrateur
• observer : Observateur (lecture seule)
• jeune : Jeune (utilisateur jeune)
• benevole : Bénévole (utilisateur bénévole)

Légende

• ✅ Utilisé par le frontend : Endpoint appelé depuis le frontend Nuxt.js
• ⚠️ Backend uniquement : Endpoint utilisé uniquement en interne ou par des services externes

🔐 Authentification (/auth)

👤 Utilisateurs (/user)

👨‍🎓 Jeunes (/jeunes)

Filtres disponibles (query params séparés par ;) :

• filterRegion, filterDepartment, filterAcademy
• filterStatut, filterState
• filterFiliere, filterFiliereBac, filterNiveau, filterCursus
• filterBesoin, filterBadge, filterSecteur
• filterBoursier, filterQpv, filterProgramme
• querySearch, queryName, queryOrganisation

👨‍🏫 Bénévoles (/benevoles)

Filtres disponibles :

• filterRegion, filterStatut, filterState
• filterSecteur, filterCursus, filterFiliere, filterNiveau
• filterBesoin, filterBadge, filterCible, filterPosture
• filterSuiviAdmin, filterMulti, filterExcluInstantMatching
• querySearch, queryName, queryOrganisation

👥 Binômes (/binomes)

Filtres disponibles :

• filterStatut, filterRegion, filterCp, filterAdmin, filterState
• filterSuivi, filterProgramme, filterAve, filterAveDispo, filterAveYear
• filterBadge, filterStem, filterStemAppel, filterFiliereBac
• querySearch, queryName, queryOrganisation

🛠️ Administration (/admin)

Équipes (/equipe)

💬 Messages (/messages)

📝 Commentaires (/comments)

📝 Commentaires Individuels (/comments-indiv)

⚡ Flash (/flash)

📊 Rating (/rating)

📈 Impact (/impact)

📋 Todo Lists (/todo-lists, /todo-tasks)

🔔 Notifications (/notifs)

📚 Ressources (/ressources)

🎓 Étapes (/steps)

🎯 Tutoriels (/tutorials)

📧 Contact (/contact)

📬 Email Subscription (/email-subscription)

🤝 Partenaires (/partner)

📅 Année (/annee)

🎓 AVE Dispositif (/avedispositif)

🐛 Erreurs (/errors)

📨 Réponses (/reponse)

🔌 API Externe (/api)

🏠 Root (/)

Notes importantes

Filtres multiples

La plupart des endpoints de liste acceptent des filtres multiples via query params séparés par ; :

GET /jeunes?filterRegion=IDF;PACA&filterStatut=APTE;EN_ATTENTE

Sandbox

Certains endpoints vérifient la sandbox de l'utilisateur. Les sandboxes disponibles sont définies dans src/common/json/SandboxList.json.

Pagination

Les endpoints de liste peuvent accepter :

• page : numéro de page
• itemsPerPage : nombre d'éléments par page

Exports Salesforce (POST /api/salesforce/mentors, POST /api/salesforce/jeunes)

Ces routes renvoient du JSON (pas de CSV). L’authentification repose sur les variables d’environnement API_CLIENT et API_KEY côté serveur : le body doit contenir les mêmes valeurs dans apiClient et apiKey, ainsi qu’un objet query optionnel pour la pagination.

Référence code : back/src/binomes/controllers/dto/export-mentors.dto.ts — SalesforceExportRequestDto, SalesforceExportQueryDto, ExportMentorDto, ExportJeuneDto, PaginateExportMentors, PaginateExportJeunes.

En cas de problème avec l'export : un problème courant est l'enregistrement buggé de certains jeunes / bénévoles qui ont un champ JSON rempli d'une valeur qui n'est pas du JSON valide (ex. une string brute au lieu d'un tableau), ce qui provoque une erreur Unexpected token ... in JSON at position 0 dans MysqlDriver.prepareHydratedValue. Pour les trouver, exécuter la requête SQL suivante puis corriger les valeurs (ex. remplacer par []) :

SELECT id, 'sectors' AS col, sectors AS val FROM jeune WHERE sectors IS NOT NULL AND sectors NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'filieres', filieres FROM jeune WHERE filieres IS NOT NULL AND filieres NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'reasons_score_engagement', reasons_score_engagement FROM jeune WHERE reasons_score_engagement IS NOT NULL AND reasons_score_engagement NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'besoins', besoins FROM jeune WHERE besoins IS NOT NULL AND besoins NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'temp_besoins', temp_besoins FROM jeune WHERE temp_besoins IS NOT NULL AND temp_besoins NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'passions', passions FROM jeune WHERE passions IS NOT NULL AND passions NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'keywords', keywords FROM jeune WHERE keywords IS NOT NULL AND keywords NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'tutors', tutors FROM jeune WHERE tutors IS NOT NULL AND tutors NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'situations', situations FROM jeune WHERE situations IS NOT NULL AND situations NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'badges', badges FROM jeune WHERE badges IS NOT NULL AND badges NOT REGEXP '^[\\[\\{]'
UNION ALL
SELECT id, 'external_infos', external_infos FROM jeune WHERE external_infos IS NOT NULL AND external_infos NOT REGEXP '^[\\[\\{]';

Pour corriger les données (ex. remplacer une string brute par un tableau JSON valide) :

-- Vérifier d'abord les lignes concernées
SELECT id, filieres FROM jeune WHERE filieres IS NOT NULL AND filieres NOT REGEXP '^\\[';

-- Corriger en wrappant la valeur dans un tableau JSON
UPDATE jeune
SET filieres = CONCAT('["', TRIM(BOTH '"' FROM filieres), '"]')
WHERE filieres IS NOT NULL AND filieres NOT REGEXP '^\\[';

Adapter le nom de colonne (filieres, sectors, etc.) selon les résultats de la requête de détection ci-dessus.

Body attendu (SalesforceExportRequestDto)

Réponse (PaginateExportMentors ou PaginateExportJeunes)

Objets dans data — mentors (ExportMentorDto)

Objets dans data — jeunes (ExportJeuneDto)

Guards spéciaux

• SandboxGuard : Vérifie que l'utilisateur a accès à la sandbox de la ressource
• SandboxGuardMultiple : Vérifie l'accès pour plusieurs ressources
• ExternalGuard : Pour les API externes avec authentification spécifique

Exemples d'utilisation

Récupérer un jeune avec filtres

curl -X GET "http://localhost:3017/jeunes?filterRegion=IDF&filterStatut=APTE" \
  -H "Authorization: Bearer <token>"

Créer un binôme

curl -X POST "http://localhost:3017/binomes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jeuneId": "123", "benevoleId": "456", "adminId": "789"}'

Récupérer le profil utilisateur

curl -X GET "http://localhost:3017/user" \
  -H "Authorization: Bearer <token>"

Export jeunes Salesforce (paginé)

curl -X POST "http://localhost:3017/api/salesforce/jeunes" \
  -H "Content-Type: application/json" \
  -d '{"apiClient":"<API_CLIENT>","apiKey":"<API_KEY>","query":{"page":1,"take":100}}'

📊 Statistiques

• Total d'endpoints documentés : ~150+
• Endpoints utilisés par le frontend : ~120+ (✅)
• Endpoints backend uniquement : ~30+ (⚠️)