API publique et synchronisation
Authentifier une intégration, consulter les ressources et fiabiliser la synchronisation.
L’API d’intégration v1 est en lecture seule sous /api/public/v1. Consultez la référence générée et le document OpenAPI sur l’hôte configuré pour les schémas déployés. L’API du tableau de bord /api/v1 a un autre rôle et une autre stabilité.
Créer et utiliser une clé
Un utilisateur autorisé crée la clé dans Paramètres → Développeurs. Conservez le secret à son affichage : il n’est pas récupérable ensuite. Accordez uniquement les droits nécessaires. Envoyez Authorization: Bearer <clé> ou X-API-Key: <clé>. La clé détermine son établissement ; elle ne permet pas d’en choisir librement un autre.
export TAKADAR_API_URL='https://api.takadar.com/api/public/v1'
# Fournir TAKADAR_API_KEY par la configuration sécurisée du serveur.
curl --get "$TAKADAR_API_URL/students" --header "Authorization: Bearer $TAKADAR_API_KEY" --data-urlencode 'page=1' --data-urlencode 'page_size=100' --data-urlencode 'updated_since=2026-10-01T00:00:00Z'
Gardez la clé côté serveur, jamais dans un paquet public du navigateur. Révoquez-la et remplacez-la en cas d’exposition. Aucune clé n’a de droits administrateur globaux ni ne peut créer des identifiants plus puissants. L’accès facultatif à l’API interne ne fournit pas l’identité humaine requise par certaines actions.
Ressources et droits
| Chemin GET | Droit | Filtres utiles |
|---|---|---|
/me | Clé valide | Identité, droits et plafond de requêtes |
/events | Clé valide | Catalogue et vérification de signature |
/students et /students/{id} | enrollment.read | Collection : status, admission_number |
/enrollments | enrollment.read | session_id, class_id, student_id |
/staff | staff.read | is_active |
/academic-sessions | academic.read | Paramètres communs |
/terms | academic.read | session_id |
/classes | academic.read | programme_id |
/sections | academic.read | class_id |
/subjects | academic.read | Paramètres communs |
/invoices | fees.read | student_id, status |
/payments | payments.read | student_id, status |
Les collections acceptent page, page_size (maximum 200) et updated_since, borne incluse. La réponse contient items, total, page, page_size et pages. Une matière peut être un cours universitaire : examinez ses crédits et sa structure sans renommer les identifiants.
Fiabiliser la synchronisation
Conservez l’heure de début, parcourez toutes les pages et mettez à jour par identifiant. N’avancez le repère qu’après réussite complète. Relisez un intervalle de chevauchement pour couvrir les changements pendant la pagination et éliminez les doublons. Les pages ne constituent pas un instantané figé ; l’ordre varie selon la ressource.
Combinez événements et interrogation. Les imports groupés d’étudiants n’émettent pas un webhook par ligne. Les lignes supprimées sont exclues ; ce flux ne fournit pas de marqueurs de suppression. Prévoyez un rapprochement périodique si la copie locale doit refléter les retraits.
Montants, erreurs et limites
Les montants utilisent les unités mineures entières et la devise ISO de la ligne : 10000 en NGN représente 100 NGN. Ne réétiquetez pas un ancien montant avec la devise actuelle de l’école.
Une clé invalide échoue à l’authentification ; un droit manquant donne 403 et insufficient_scope. Le dépassement du plafond par clé renvoie 429 avec Retry-After. Respectez ce délai et espacez les nouvelles tentatives après erreur temporaire. Consultez /me pour le plafond réel.