API Scoliom Scolarité — v1

API REST en lecture seule · JSON · une clé par logiciel branché · mise à jour du 28 octobre 2026

En bref. L'API permet à un autre logiciel de l'école (comptabilité, statistiques, tableau de bord…) de lire ses élèves, classes, niveaux, échéances, paiements et absences. Il ne peut rien modifier. Elle est fermée par défaut : elle ne s'ouvre que lorsque la direction de l'école crée une clé, et la direction peut révoquer cette clé à tout moment.
Présentation sans jargon, pour la direction : l'API sur scoliom.com.

1. Obtenir une clé

La direction de l'école (compte directeur ou administrateur) ouvre Paramètres › API dans Scoliom Scolarité, nomme la clé d'après le logiciel qu'elle va brancher (par exemple « Comptabilité ») et clique sur Créer une clé.

La clé commence par sco_, suivi de 40 caractères. Elle n'est affichée qu'une seule fois : Scoliom n'en garde qu'une empreinte et ne peut plus la montrer. Perdue, elle se révoque et se remplace.
Une clé ne voit que son école.
Une école a au plus 5 clés actives : une par logiciel branché, pour pouvoir en débrancher un sans toucher aux autres.
Le même écran donne l'adresse de l'API de l'école, la date du dernier usage de chaque clé et son nombre d'appels.

2. Appeler l'API

Adresse (écoles hébergées sur app.scoliom.com — l'adresse exacte figure dans Paramètres › API) :

https://app.scoliom.com/api/v1.php?resource=<ressource>

La clé passe dans l'en-tête Authorization :

curl -H "Authorization: Bearer sco_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     "https://app.scoliom.com/api/v1.php?resource=students&status=inscrit&per_page=100"

Si un relais retire Authorization, envoyez plutôt X-Api-Key: sco_….
Jamais de clé dans l'adresse : la requête est refusée (400 key_in_url), car les adresses finissent dans les journaux des serveurs.
HTTPS seulement. GET (et HEAD) seulement : toute autre méthode reçoit 405.
La ressource peut aussi se donner en chemin : /api/v1.php/students.
L'API s'appelle depuis un serveur. Elle n'envoie aucune en-tête CORS : ne mettez jamais une clé dans une page web.

3. Conventions

Listes et pagination

{
  "data": [ { … }, { … } ],
  "meta": { "page": 1, "per_page": 100, "total": 412, "pages": 5 }
}

page (à partir de 1) et per_page (de 1 à 200, 100 par défaut). Les éléments sont triés par id : une page ne glisse pas quand de nouveaux éléments s'ajoutent à la fin.

Formats

Dates : AAAA-MM-JJ. Dates et heures : ISO 8601 avec décalage (2026-10-28T12:00:00+01:00).
Montants : nombres à deux décimales, dans la monnaie de l'école (dirhams pour une école marocaine).
Les statuts sont des codes stables, en français comme dans le produit ; leur sens est donné plus bas.
Une valeur inconnue ou vide vaut null.

Débit

60 requêtes par minute et par clé. Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining. Au-delà : 429 rate_limited et Retry-After: 60. Des clés invalides en série depuis une même adresse (20 en 10 minutes) sont refusées pendant 10 minutes (429 too_many_failures).

Erreurs

{ "error": { "code": "invalid_parameter", "message": "Parameter 'per_page' must be between 1 and 200." } }

Le code est stable ; le message, en anglais, s'adresse au développeur.

HTTP	code	Sens
400	`invalid_parameter`, `missing_resource`, `key_in_url`	Requête mal formée.
401	`missing_key`, `invalid_key`	Pas de clé, ou une clé inconnue ou révoquée.
403	`https_required`	La requête n'est pas passée en HTTPS.
404	`unknown_resource`, `not_found`	Ressource inconnue, ou année scolaire d'une autre école.
405	`method_not_allowed`	L'API est en lecture seule.
429	`rate_limited`, `too_many_failures`	Ralentir (voir plus haut).
500	`server_error`	Réessayer plus tard.

4. Les ressources

`school` — l'école de la clé

Champs : id, name, name_ar, city, country, language, current_school_year (id, label, start_date, end_date). Un seul objet, sans pagination. Pratique pour vérifier une clé.

`levels` — les niveaux

Champs : id, cycle, label, label_ar, order, next_level_id (le niveau de passage), active.

`classes` — les classes d'une année scolaire

Paramètres : school_year_id (par défaut : l'année courante), level_id.
Champs : id, school_year_id, level_id, label, label_ar, code, capacity, students_count (élèves inscrits), active.

`students` — les élèves

Paramètres : class_id, level_id, status, updated_since (date, ou date et heure ISO 8601 : pour une synchronisation incrémentale).
Champs : id, number (numéro d'élève de l'école), national_student_number (code Massar au Maroc), last_name, first_name, last_name_ar, first_name_ar, sex (M/F), birth_date, status, level_id, class_id, family_id (commun aux frères et sœurs), entry_date, exit_date, updated_at.
status : en_attente, inscrit, reinscrit, sorti.

`installments` — les échéances

Paramètres : school_year_id (par défaut : l'année courante), student_id, status, due_from, due_to.
Champs : id, student_id, school_year_id, fee_id, label, amount, amount_paid, balance (reste dû), due_date, status.
status : a_payer, partielle, payee, annulee.

`payments` — les paiements encaissés

Paramètres : student_id, date_from, date_to, include_cancelled (true/false, false par défaut).
Champs : id, student_id, installment_id, amount, payment_date, method, reference, bank, receipt_number, cheque_status, cancelled, cancelled_at, created_at.
method : especes, cheque, virement, carte, autre. cheque_status : recu, remis, encaisse, impaye.

`absences` — absences et retards

Paramètres : student_id, class_id, type, status, date_from, date_to.
Champs : id, student_id, school_year_id, date, type (absence, retard), minutes_late, status, slot (code, label, start_time, end_time).
status : a_justifier, justifiee, injustifiee.

5. Données personnelles

L'API applique le principe de minimisation de la loi 09-08 et du RGPD. Elle ne rend pas : les adresses, les photos, les lieux de naissance, les notes internes, le motif d'une absence ni son justificatif (souvent une donnée de santé), les commentaires libres sur les paiements, ni les coordonnées des parents. L'école reste responsable du traitement : elle décide quel logiciel reçoit une clé, et peut la révoquer à tout moment. Chaque appel est journalisé (date, ressource, nombre d'éléments, adresse IP) et conservé 90 jours ; la direction voit, pour chaque clé, son dernier usage et son nombre d'appels.

6. Versions et contact

Ceci est la version 1. Des champs peuvent s'ajouter à la v1 ; aucun ne sera renommé ni retiré sans une nouvelle version (/api/v2.php), annoncée à l'avance. Besoin d'une autre ressource, ou d'un accès en écriture ? Écrivez à contact@scoliom.com.