Offre Enterprise

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-JJ ou ISO 8601.

Adresse de base :

https://scolarcash.app/api/v1

Authentification

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

GET/students?classe=&statut=&page=&pageSize=

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. page commence à 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).
GET/students/{id}

Un élève avec ses frais (charges), ses paiements (payments, annulés compris, avec cancelledAt) et ses relances (reminders).

POST/studentsclé « écriture »

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

POST/students/{id}/chargesclé « écriture »

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" }'
POST/students/{id}/paymentsclé « écriture »

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

GET/reports?from=AAAA-MM-JJ&to=AAAA-MM-JJ

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

HTTPerrorSignification
400VALIDATION_FAILEDDonnée manquante ou invalide (détail dans issues).
400INVALID_PERIODPériode de rapport invalide.
400PAYMENT_DATE_IN_FUTUREDate de paiement dans le futur.
401API_KEY_MISSINGEn-tête Authorization absent.
401API_KEY_INVALIDClé inconnue ou révoquée.
403ENTERPRISE_REQUIREDLe contrat Enterprise de l’école n’est pas actif.
403API_KEY_READ_ONLYÉcriture demandée avec une clé en lecture seule.
404STUDENT_NOT_FOUNDÉlève inconnu, retiré ou d’une autre école.
409EXTERNAL_ID_CONFLICTexternalId déjà utilisé pour un autre élève.
429RATE_LIMITEDPlus 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.