Comptes de services & Webhooks
Connecter Neil à des systèmes externes : accès API entrant et notifications sortantes
Neil n’est pas un système isolé. Il peut recevoir des requêtes d’outils externes (CRM, BI, comptabilité) et envoyer des notifications quand un événement se produit (inscription, note publiée, absence saisie, etc.).
Deux mécanismes complémentaires rendent cela possible : le Compte de Service (accès entrant) et le Webhook (notification sortante).
Un compte de service permet à un système tiers (CRM, outil comptable, BI) d'accéder aux données de Neil de manière contrôlée. Chaque compte est isolé et dispose de ses propres droits.
Périmètre d'accès (scope)
Le compte n'accède qu'aux données autorisées : écoles, niveaux, années scolaires, matières. Le principe du moindre privilège s'applique : on ne donne accès qu'au strict nécessaire.
Authentification sécurisée
Chaque compte génère une clé API unique, affichée une seule fois à la création. La clé peut avoir une date d'expiration et une période d'autorisation définie.
Permissions granulaires
Arbre de droits détaillé par section : lecture seule, écriture, ou les deux. Chaque compte a un profil de permissions indépendant des utilisateurs humains.
Isolation des comptes
Chaque compte de service est indépendant. Révoquer un compte ne coupe que l'accès du système concerné, sans impacter les autres intégrations.
Un compte de service = un système externe. On ne partage jamais une clé entre plusieurs outils. Si un prestataire change ou si un outil est décommissionné, on révoque le compte sans impacter les autres intégrations.
Techniquement : l'authentification se fait via l'en-tête HTTP X-Lucius-Api-Key sur chaque appel à l'API REST de Neil.
GET /api/accounting/invoices/1234 X-Lucius-Api-Key: sk_live_abc123...def456
{
"id": 1234,
"number": "FA-2025-0042",
"invoice_type": "invoice",
"amount": 450000,
"student": {
"first_name": "Jean",
"last_name": "Dupont"
},
"school": { "name": "École A" },
"created_at": "2025-09-15T10:30:00Z"
}
Le système externe envoie sa clé API dans l'en-tête de chaque requête. Neil vérifie le scope et les permissions du compte, puis retourne les données autorisées. La documentation complète de l'API est accessible via le Swagger intégré.
Un compte de service est l’identité d’un système tiers (CRM, outil comptable, BI) qui vient lire ou écrire dans Neil. Chaque compte porte sa propre clé API, son périmètre (écoles, niveaux, années) et ses permissions, en suivant le principe du moindre privilège. Un compte par système, jamais de clé partagée : ainsi, révoquer un compte ne coupe que l’outil concerné sans impacter les autres intégrations.
Un webhook est une notification automatique envoyée par Neil vers un système tiers dès qu'un événement se produit. C'est du temps réel, pas de la synchronisation batch.
Temps réel
Le webhook se déclenche à l'instant où l'événement se produit dans Neil. Pas d'attente, pas de batch nocturne.
403 événements
Neil expose 403 événements couvrant 6 domaines (configuration, pédagogie, scolarité, marketing, RH, comptabilité). Chaque webhook sélectionne les événements pertinents.
Unidirectionnel
Neil notifie, le système destinataire reçoit et traite. Chaque webhook pointe vers une URL configurée avec des en-têtes personnalisés.
Authorization: Bearer eyJhbGciOiJIUzI1NiIs... X-Source: neil-erp X-School-Id: 1
Les webhooks permettent d'alimenter en temps réel un CRM, un outil BI ou un système de notification interne. Un webhook inactif (URL en erreur) échoue silencieusement — prévoir un monitoring côté système destinataire.
POST https://crm.ecole.fr/webhook/neil Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ← en-tête personnalisée X-Source: neil-erp ← en-tête personnalisée
{
"event": "student_formula.created",
"timestamp": "2025-09-15T14:22:31Z",
"data": {
"student_id": 5678,
"formula_id": 42,
"school_id": 1,
"year": 2025
}
}
Dès qu'un étudiant est inscrit à une formule dans Neil, le webhook envoie un payload JSON vers l'URL configurée. Le système destinataire (CRM, BI, etc.) reçoit l'événement et peut déclencher ses propres traitements.
Chaque Webhook écoute un ou plusieurs événements. Neil expose 403 événements répartis en 6 domaines :
Neil expose 403 événements webhook organisés en 6 domaines fonctionnels. Cette finesse permet d'écouter précisément ce qui intéresse le système destinataire, sans être noyé par les notifications inutiles.
Les domaines reflètent les grandes zones métier : Configuration (écoles, niveaux, profils), Pédagogie (formations, modules, notes), Scolarité (inscriptions, étudiants), Comptabilité (factures, paiements). Chaque événement correspond à un changement d'état précis (création, modification, suppression d'un objet).
Un webhook peut être abonné à un seul événement (notifier le CRM à chaque inscription), à plusieurs événements d'un domaine (suivre tous les changements en pédagogie), ou à un domaine entier. La granularité permet d'industrialiser des intégrations ciblées sans surcharger les systèmes externes.
Un système tiers peut avoir besoin d'afficher à un étudiant ses propres données — son planning, ses notes, ses documents — depuis sa propre interface. Plutôt que de lui donner un accès global, Neil lui permet de demander un jeton de courte durée qui l'authentifie comme cet étudiant, sans session ni cookie.
Le compte de service demande ce jeton pour un étudiant précis, puis s'en sert pour interroger l'espace étudiant. Il n'obtient que ce que cet étudiant verrait lui-même. Le jeton conserve la trace du compte de service qui l'a demandé : on sait toujours qui a agi, et pour le compte de qui.
La clé API ne s’affiche qu’une fois
À la création d’une clé, Neil l’affiche une seule fois. Si elle est perdue, il faut en générer une nouvelle et mettre à jour le système externe.
Surveiller les dates d’expiration
Chaque clé API peut avoir une date d’expiration. Une clé expirée coupe silencieusement l’accès du système externe — anticiper le renouvellement.
Un Webhook inactif échoue silencieusement
Si l’URL de destination ne répond plus, Neil continue d’envoyer sans alerte visible. Vérifier régulièrement les événements du Webhook pour détecter les échecs.
Un Compte = un système
Ne jamais partager une clé API entre plusieurs outils. Chaque système externe doit avoir son propre Compte de Service avec un scope et des permissions dédiés.
Webhook = temps réel
Un Webhook se déclenche quand l’événement se produit, pas selon un planning. Ce n’est pas un outil de synchronisation périodique ou de reprise d’historique.
Scope minimal, droits minimaux
Limiter chaque Compte de Service aux seuls écoles, niveaux et permissions strictement nécessaires. Plus le scope est large, plus le risque en cas de fuite de clé est élevé.
