Connectez le site de votre école aux réservations MindScolar

1. Pré-requis et création de la clé

Un administrateur autorisé à gérer l’abonnement ouvre Inscriptions, Réservations, puis Connexion du site. Il crée la clé avec les scopes options:read et reservations:create.

La clé complète n’est affichée qu’une seule fois. Si elle est perdue ou révoquée, une rotation crée un nouveau secret et invalide immédiatement l’ancien.

2. Configurer le serveur du site

L’intégration est strictement serveur-à-serveur. La clé ne doit jamais être placée dans React, Vite, un navigateur, une URL, Git, des outils d’analytics ou des journaux.

MINDSCOLAR_API_BASE_URL=https://mindscolar.org
MINDSCOLAR_ADMISSION_API_KEY=msk_site_votre_prefix.votre_secret

L’école est dérivée de la clé. N’envoyez jamais school_id, school_year_id ou un en-tête de locataire ; MindScolar associe l’unique année scolaire active configurée.

3. Charger l’année scolaire et les classes

GET /api/v3/integrations/admission-reservations/options/
Authorization: Bearer <MINDSCOLAR_ADMISSION_API_KEY>

Utilisez uniquement classes[].id comme enrollment.class_id. N’envoyez jamais school_id ou school_year_id.

4. Envoyer une réservation d’inscription

POST /api/v3/integrations/admission-reservations/
Authorization: Bearer <MINDSCOLAR_ADMISSION_API_KEY>
Idempotency-Key: <clé unique persistée avec la demande>
Content-Type: application/json

Chaque nouvelle réservation logique reçoit une nouvelle clé d’idempotence. En cas d’incertitude réseau, rejouez exactement le même JSON avec la même clé afin d’éviter un doublon.

{
  "student": {
    "nom": "Ilunga",
    "postnom": "Kabeya",
    "prenom": "Sarah",
    "sexe": "F",
    "lieu_naissance": "Lubumbashi"
  },
  "enrollment": {
    "class_id": 48,
    "is_new": true,
    "adresse": "12, avenue des Écoles, Lubumbashi"
  },
  "father": {
    "nom": "Ilunga",
    "prenom": "Patrick",
    "telephone": "+243990000002"
  },
  "mother": null
}

5. Appeler l’API depuis Node.js

Le service Node.js s’exécute uniquement sur le serveur. Il lit les deux variables d’environnement, persiste la clé d’idempotence et les données avant l’appel, puis réutilise les deux si l’issue réseau est inconnue.

6. Réponses, sécurité, erreurs et limites

• 201 : réservation créée ; 200 avec Idempotent-Replay: true : même référence et statut courant.
• 400 : données ou année active invalides ; 401 : clé absente ou invalide ; 403 : abonnement, scope ou intégration refusé.
• 409 : conflit d’idempotence ; 429 : limite de requêtes dépassée.
• Limites par défaut : 120 lectures des options et 30 créations par heure, par intégration et IP.

7. Contre-vérification et validation

La réservation reste en attente. Un agent ouvre l’interface interne, vérifie et corrige les informations, enregistre sa révision puis valide. L’élève devient officiellement inscrit et la réservation validée quitte la liste opérationnelle.