Personnalisation d'API : surcharges de points d'accès et hooks

Où le trouver

Module Administration, écran Import/Export, section Personnalisation d'API, bouton API.

L'écran est réservé aux comptes Premium et protégé par une authentification renforcée : Omniscol redemande le mot de passe de l'administrateur avant d'ouvrir la fenêtre. Comme toute action sur cet écran touche au contrat technique de votre intégration, sa mise en place se fait en lien avec Omniscol.

Configuration générale

Vous y définissez des en-têtes HTTP (format clé1:valeur1;clé2:valeur2) appliqués à tous les hooks. C'est l'endroit naturel pour porter un jeton d'authentification vers votre propre serveur (par exemple un Authorization: Bearer … que votre serveur attend). Pour une surcharge, l'authentification se porte au contraire dans les en-têtes propres au point d'accès (voir ci-dessous).

Surcharge d'un point d'accès

Une surcharge redéfinit un point d'accès de l'API d'Omniscol pour que l'application web appelle une autre URL à sa place. Trois usages, du plus puissant au plus simple.

Servir une donnée en direct depuis votre système d'information

C'est l'usage le plus puissant. Vous redirigez un point d'accès en lecture vers une URL externe — typiquement un ETL qui interface le système d'information interne de votre établissement. L'application web va alors chercher la donnée en direct dans ce système, au lieu de la copie locale détenue par Omniscol.

Concrètement : quand l'URL de redirection est une adresse externe absolue, l'application web l'appelle directement, sans repasser par les serveurs d'Omniscol, et consomme la réponse telle quelle — exactement comme si elle venait d'Omniscol. La seule contrainte est que votre système réponde au format attendu par Omniscol pour ce point d'accès (même structure JSON) : il n'y a aucun transcodage intermédiaire. Pour ce point d'accès, la copie locale d'Omniscol n'est plus interrogée ; la donnée affichée est celle, vivante, de votre système.

Exemple : le catalogue des matières de l'établissement servi à la volée depuis votre système d'information, de sorte que toute mise à jour côté école soit visible immédiatement dans Omniscol, sans réimport.

L'authentification vers votre système se porte ici dans les en-têtes propres au point d'accès (par exemple un Authorization: Bearer …), saisis sur la ligne de la surcharge. La méthode HTTP peut elle aussi être imposée par point d'accès.

Rebrancher un point d'accès de l'application elle-même sur une source externe vivante est une possibilité aussi puissante qu'exigeante : à manier avec votre service informatique, et en lien avec Omniscol.

Intercaler votre propre serveur ou un proxy

Vous pouvez aussi faire passer les appels par votre propre serveur ou un proxy — par exemple pour autoriser le partage de ressources entre origines (CORS), ou pour intercaler une logique maison entre l'application web et Omniscol.

Désactiver un point d'accès

Vous désactivez un point d'accès en ne lui donnant aucune URL de redirection (méthode null).

Mesurez l'effet sur l'interface. Omniscol est une application web monopage (SPA) dont les éléments d'interface sont pilotés par les points d'accès disponibles : boutons, onglets et menus ne s'affichent que si le point d'accès dont ils dépendent existe. Désactiver un point d'accès fait donc disparaître dynamiquement, au prochain affichage, les éléments d'interface qui en dépendent — et si vous désactivez tous les points d'accès d'un module, c'est le module entier qui disparaît de la navigation. Ces éléments sont retirés, pas seulement masqués, et le tout se fait sans aucune intervention sur le code : il suffit de modifier la configuration et de recharger l'application.

Le tableau liste, par point d'accès : sa clé (le code interne de l'opération), son URL d'origine, la méthode HTTP, la nouvelle URL de redirection et des en-têtes spécifiques. Un champ de recherche permet de retrouver le point d'accès à surcharger.

Hooks (appels sortants)

Un hook demande à Omniscol d'envoyer une requête HTTP à votre URL après qu'une opération a réussi. C'est le mécanisme pour tenir un système externe au courant en temps réel — un panneau d'affichage, un espace numérique de travail, un système de ressources humaines, une synchronisation maison…

Un hook se branche de deux façons :

• sur un point d'accès précis (la clé de l'opération) ;
• sur un événement groupé, qui couvre d'un coup une famille d'opérations. Trois événements groupés existent :
  • modification d'emploi du temps (création, déplacement ou suppression de séances, activation d'un emploi du temps, et absences de professeur ou de classe dès qu'une date est touchée) ;
  • modification d'un professeur (ajout, mise à jour ou suppression) ;
  • modification d'une matière (matières personnalisées).

Pour chaque hook, vous renseignez l'URL de rappel, la méthode HTTP, la case « avec données » (faut-il joindre le corps de la requête d'origine ?) et des en-têtes propres.

Ce que votre serveur reçoit

L'appel est envoyé en application/json et porte, en plus de vos en-têtes :

• le corps de la requête d'origine si l'option « avec données » est activée ;
• un bloc de métadonnées Omniscol : l'URL appelée, le code du point d'accès, la méthode, les paramètres, le jeton d'authentification de l'utilisateur et l'identifiant de l'établissement ;
• des en-têtes de traçabilité : X-OS-original-query, X-OS-original-endpoint, X-OS-auth et X-School.

Pour l'événement modification d'emploi du temps, lorsque l'option « avec données » est active, l'appel inclut en plus un différentiel des séances (séances ajoutées, modifiées, supprimées) — pratique pour ne propager que ce qui a changé.

Comportement

Les hooks partent en arrière-plan, après que l'opération de l'utilisateur a abouti : ils ne ralentissent pas l'interface et ne la bloquent pas en cas d'échec de votre serveur. Un appel sortant qui n'aboutit pas est journalisé, sans interrompre le travail dans Omniscol. Chaque appel a un délai d'expiration court (quelques secondes) : votre serveur doit accuser réception vite et traiter le reste de son côté.

Bon à savoir

• L'API d'Omniscol expose un sous-ensemble d'opérations ; une surcharge ou un hook ne s'applique qu'aux points d'accès réellement exposés. Voir API Omniscol pour la liste et l'authentification.
• Pour une intégration avec un progiciel (ERP, SIRH, espace numérique de travail), la synchronisation dédiée est souvent plus adaptée — voir Synchronisation avec des systèmes externes. En interne, le même système de hook est utilisé.
• Pour qu'un agent IA consulte vos données sans développement, voir MCP — connecter un agent IA externe.