API ScolarCash
Reliez ScolarCash au logiciel de gestion de votre établissement : lisez les soldes des élèves, enregistrez les paiements reçus ailleurs, récupérez les rapports de recouvrement.
Démarrer
- L’API fait partie de l’offre Enterprise. Parlez-en à un conseiller.
- Le propriétaire ou un administrateur de l’école crée une clé dans Paramètres → Accès API, avec les droits « lecture seule » ou « lecture et écriture ». La clé ne s’affiche qu’une fois : copiez-la tout de suite.
- Une clé donne accès aux données de son école seulement. Gardez-la côté serveur, jamais dans une page web ou une application mobile.
- Toutes les réponses sont en JSON (UTF-8). Les montants sont des nombres entiers en francs guinéens (GNF, sans décimales), les dates au format
AAAA-MM-JJou ISO 8601.
Adresse de base :
https://scolarcash.app/api/v1Authentification
Envoyez la clé dans l’en-tête Authorization de chaque requête. Pour vérifier une clé :
curl https://scolarcash.app/api/v1/me \
-H "Authorization: Bearer sc_live_VOTRE_CLE"{
"data": {
"school": { "id": "cm…", "name": "Collège Sainte-Marie" },
"scope": "READ",
"version": "v1"
}
}Une clé révoquée ne fonctionne plus immédiatement. 10 clés actives au maximum par école : créez une clé par logiciel.
Élèves
Les élèves de l’école, triés par classe puis par nom, avec leur situation financière calculée à l’instant.
classe: nom exact de la classe (ex.3ème A).statut:TOUS(défaut),DEBITEURS(montant échu impayé),REGLE,PARTIEL,IMPAYE,CRITIQUE(retard de 30 jours ou plus).pageSize: 50 par défaut, 200 au maximum.pagecommence à 1.
curl "https://scolarcash.app/api/v1/students?statut=DEBITEURS&pageSize=100" \
-H "Authorization: Bearer sc_live_VOTRE_CLE"{
"data": [
{
"id": "cm…",
"externalId": "ELEVE-0042",
"lastName": "Diallo",
"firstName": "Fatoumata",
"className": "3ème A",
"matricule": "2026-042",
"parentName": "M. Diallo",
"parentPhone": "+224620000000",
"totalCharged": 700000,
"totalPaid": 100000,
"dueNow": 350000,
"overdue": 250000,
"balance": 600000,
"daysOverdue": 20,
"paidPercent": 14,
"status": "PARTIEL",
"lastPaymentAt": "2026-11-11T00:00:00.000Z",
"lastReminderAt": "2026-11-13T09:12:00.000Z",
"reminderCount": 1
}
],
"page": 1,
"pageSize": 100,
"total": 1
}totalCharged: tous les frais, échus ou non ·dueNow: frais déjà échus ·overdue: partie échue non payée ·balance: reste à payer (négatif = avance).
Un élève avec ses frais (charges), ses paiements (payments, annulés compris, avec cancelledAt) et ses relances (reminders).
Ajoute un élève. Seuls le nom et la classe sont obligatoires.
curl -X POST https://scolarcash.app/api/v1/students \
-H "Authorization: Bearer sc_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"lastName": "Diallo",
"firstName": "Fatoumata",
"className": "3ème A",
"matricule": "2026-042",
"parentName": "M. Diallo",
"parentPhone": "+224620000000",
"externalId": "ELEVE-0042"
}'201 → { "data": { "id": "cm…", "externalId": "ELEVE-0042" }, "created": true }Frais et paiements
Ajoute un frais à un élève : libellé, montant et date d’échéance.
curl -X POST https://scolarcash.app/api/v1/students/cm…/charges \
-H "Authorization: Bearer sc_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{ "label": "Mensualité décembre", "amount": 350000,
"dueDate": "2026-12-05", "externalId": "FACT-2026-12-0042" }'Enregistre un paiement reçu par l’école. method : CASH, ORANGE_MONEY, MTN_MOMO, AFRICELL_MONEY, BANK, OTHER. Une date de paiement dans le futur est refusée.
curl -X POST https://scolarcash.app/api/v1/students/cm…/payments \
-H "Authorization: Bearer sc_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{ "amount": 100000, "paidAt": "2026-11-11", "method": "ORANGE_MONEY",
"reference": "OM-88213", "externalId": "RECU-2026-0915" }'Un paiement enregistré ne peut pas être supprimé par l’API : en cas d’erreur, l’école l’annule dans ScolarCash (il reste visible, barré).
Rapports
Les chiffres de la page Rapports : encaissé sur la période, nombre de paiements et de relances, situation par classe à ce jour, répartition par mode de paiement, encaissements des 12 derniers mois et liste des paiements de la période. Sans dates : le mois en cours. Deux ans au maximum.
curl "https://scolarcash.app/api/v1/reports?from=2026-08-01&to=2026-11-13" \
-H "Authorization: Bearer sc_live_VOTRE_CLE"Éviter les doublons
Chaque création accepte un externalId : l’identifiant de la même chose dans votre logiciel (100 caractères au maximum). Si vous renvoyez une requête avec un externalId déjà connu — après une coupure réseau, ou en relançant une synchronisation — ScolarCash ne crée rien de nouveau et répond 200 avec "created": false et l’enregistrement existant.
Envoyez toujours un externalId pour les paiements : sans lui, une requête répétée enregistrerait deux fois le même argent. Un même externalId déjà utilisé pour un autre élève répond 409.
Erreurs et limites
Une erreur répond avec un code HTTP et un corps { "error": "CODE", "message": "…" }. Basez votre programme sur error, pas sur le message (qui peut changer).
| HTTP | error | Signification |
|---|---|---|
| 400 | VALIDATION_FAILED | Donnée manquante ou invalide (détail dans issues). |
| 400 | INVALID_PERIOD | Période de rapport invalide. |
| 400 | PAYMENT_DATE_IN_FUTURE | Date de paiement dans le futur. |
| 401 | API_KEY_MISSING | En-tête Authorization absent. |
| 401 | API_KEY_INVALID | Clé inconnue ou révoquée. |
| 403 | ENTERPRISE_REQUIRED | Le contrat Enterprise de l’école n’est pas actif. |
| 403 | API_KEY_READ_ONLY | Écriture demandée avec une clé en lecture seule. |
| 404 | STUDENT_NOT_FOUND | Élève inconnu, retiré ou d’une autre école. |
| 409 | EXTERNAL_ID_CONFLICT | externalId déjà utilisé pour un autre élève. |
| 429 | RATE_LIMITED | Plus de 120 requêtes par minute avec la même clé. |
Limite : 120 requêtes par minute et par clé. Pour synchroniser beaucoup d’élèves, utilisez pageSize=200 plutôt qu’une requête par élève.