Intégration domotique Agora Famille, gratuite et open source
Cantine, périscolaire, factures et messages du portail famille Agora Famille.
Publiée par prohand
- Appareils
- Version 2.0.1
- Nécessite Gladys >=5.3.0
- ★ 0
Cette intégration relie Gladys au portail famille Agora Famille (édité par Agora Plus) de votre commune : cantine, périscolaire, accueil de loisirs, factures et messages de la mairie.
Elle lit le portail comme le ferait votre navigateur, avec votre compte, et vous donne dans Gladys :
- un appareil par enfant : ce qui est réservé aujourd'hui et demain, et s'il mange à la cantine ;
- un appareil compte famille : le reste à payer, la prochaine facture, le dernier message ;
- des déclencheurs de scène (nouvelle facture, facture bientôt à échéance, nouveau message, réservation acceptée ou refusée) ;
- des actions de scène de lecture (vérifier une journée, relire le portail) ;
- un widget de tableau de bord.
Avant de commencer
- Il faut Gladys 5.3 ou plus récent.
- Il vous faut un compte actif sur le portail Agora Famille de votre commune : l'adresse e-mail et le mot de passe avec lesquels vous vous y connectez.
- L'intégration est de type cloud : elle a besoin d'internet pour joindre le portail.
Configuration
Dans Gladys : Intégrations → Agora Famille → Configuration.
| Champ | Ce qu'il faut y mettre |
|---|---|
| Adresse du portail | L'adresse de votre portail telle que l'affiche votre navigateur, par ex. https://portalssl.agoraplus.fr/maville/pck_home.home_view#/. Le seul nom de la commune (maville) suffit aussi. |
| Identifiant (e-mail) | L'e-mail de votre compte famille. |
| Mot de passe | Le mot de passe du portail. Il est stocké comme un secret par Gladys et n'apparaît jamais dans les logs. |
| Intervalle de lecture (min) | Fréquence de lecture du portail (60 min par défaut, 15 min minimum). Inutile d'aller plus vite : le portail change peu dans la journée. |
| Jours de planning suivis | Combien de jours à venir sont lus et surveillés (14 par défaut). |
| Rappel de facture (jours) | Le déclencheur « facture bientôt à échéance » part ce nombre de jours avant l'échéance (3 par défaut, 0 pour le couper). |
| Factures transmises au Trésor public | Numéros des factures que la commune a transmises au Trésor public, séparés par des virgules (ex. 164513). Voir plus bas. |
| Logs détaillés | Journalise chaque requête au portail, pour le dépannage. Jamais le mot de passe. |
Cliquez ensuite sur Tester la connexion : la réponse liste vos enfants, le nombre de jours de planning lus, les factures à payer et les messages non lus. En cas d'échec, elle dit quelle étape a échoué (connexion, enfants, planning, factures, messages).
Puis allez dans l'onglet Découverte pour créer les appareils.
Les appareils
Agora Famille (le compte)
| Fonctionnalité | Contenu |
|---|---|
| Balance due | Le reste à payer, en euros (toutes factures impayées). |
| Next invoice | La prochaine facture à payer : montant, échéance, libellé. |
| Last message | L'objet du dernier message de la commune. |
Un appareil par enfant
| Fonctionnalité | Contenu |
|---|---|
| Today | Les activités réservées aujourd'hui (« Cantine, Garderie du soir »). |
| Tomorrow | Les activités réservées demain. |
| Canteen today | 1 si l'enfant mange à la cantine aujourd'hui, 0 sinon. |
| Canteen tomorrow | 1 si l'enfant mange à la cantine demain, 0 sinon. |
Une journée demandée et pas encore validée par la commune compte comme réservée. Les textes sont en français, comme les activités du portail.
Le repas est reconnu par son nom : « cantine », « repas », « restauration », « déjeuner », « pause méridienne »… Chaque commune nomme ses activités à sa façon.
Le badge cloud de chaque appareil passe à injoignable quand le portail ne peut pas être lu.
Scènes (Gladys 5.1+)
Déclencheurs
| Déclencheur | Quand | Variables |
|---|---|---|
| Une nouvelle facture est émise | Une facture impayée apparaît. | label, amount, due_date, invoice_id |
| Une facture arrive à échéance | Une facture impayée arrive à échéance dans le délai réglé. Une seule fois. | label, amount, due_date, days_left, invoice_id |
| Un message est reçu | La commune a envoyé un message. | subject, sender, date |
| Une réservation change | Un jour réservé ou demandé change d'état (accepté, refusé, annulé…). Filtrable par enfant et par état. | child_name, activity, date, status, previous_status, meal |
Les variables s'utilisent dans les actions suivantes, par ex.
{{triggerEvent.data.amount}}.
La toute première lecture du portail ne déclenche rien : tout y paraîtrait
nouveau. Les changements sont comptés à partir de là, même après un
redémarrage (l'intégration garde la dernière lecture dans /data).
Actions
| Action | Ce qu'elle fait | Sorties |
|---|---|---|
| Lire le portail famille | Relit le portail tout de suite. | success, balance, unpaid_invoices, unread_messages |
| Vérifier la journée d'un enfant | Dit si l'enfant est réservé ce jour-là (0 = aujourd'hui, 1 = demain…) et pour quoi. | has_meal, booked_count, activities, date |
L'intégration ne fait que lire le portail : elle ne réserve ni n'annule jamais rien. Les réservations et les absences se font sur le portail.
Exemples
- Tous les soirs à 19 h : Vérifier la journée de chaque enfant pour
demain, puis, si
has_mealvaut faux, envoyer « Pas de cantine demain pour Léa ». - Une facture arrive à échéance → envoyer « Facture de {{triggerEvent.data.amount}} € à payer avant le {{triggerEvent.data.due_date}} ».
- Une réservation change, filtré sur l'état Refusé → notification.
Le widget
Le widget Agora Famille du tableau de bord montre :
- le reste à payer (en direct) ;
- pour chaque enfant (5 au plus), ce qui est réservé aujourd'hui et demain (vert : réservé, orange : demande en attente, rouge : refusé) ;
- les factures à payer et les 3 derniers messages non lus ;
- l'heure de la dernière lecture, ou l'erreur en cours.
Et deux boutons : Actualiser et Ouvrir le portail. Les absences et les réservations se font sur le portail.
Factures transmises au Trésor public
Quand une facture n'est pas payée à temps, la commune la transmet au Trésor public (« mise en impayé »). Le portail ne suit alors plus son paiement : il la montre impayée pour toujours, même une fois payée au Trésor.
L'intégration met ces factures à part :
- elles ne comptent pas dans le reste à payer ni dans la prochaine facture ;
- elles ne déclenchent ni « nouvelle facture » ni « facture bientôt à échéance » ;
- le widget les montre en gris, avec le badge Trésor public.
Elles sont reconnues de deux façons :
- toute seules, quand le portail les marque (facture en contentieux, ou un état qui parle du Trésor) ;
- par leur numéro, dans le champ Factures transmises au Trésor public
(le numéro affiché sur le portail, ex.
164513).
Dépannage
- « Le portail a refusé l'identifiant ou le mot de passe » : vérifiez-les en vous connectant au portail dans un navigateur. Un compte en attente de validation par la mairie ne peut pas encore se connecter.
- « Le portail ne répond pas » : le portail est peut-être en maintenance ; l'intégration réessaie à chaque intervalle.
- « Le portail a répondu quelque chose d'inattendu » : cochez Logs détaillés, cliquez sur Tester la connexion et consultez les logs de l'intégration (Intégrations → Agora Famille → Supervision).
Important : pas d'API officielle
Agora Plus ne publie pas d'API pour son portail famille. L'intégration
utilise les mêmes requêtes que les pages du portail ; elles sont regroupées
dans un seul fichier,
src/agora/endpoints.js. Une mise à jour du
portail, ou une commune configurée différemment, peut demander de les
ajuster : ouvrez alors une
issue en indiquant
l'étape qui échoue et le code HTTP renvoyé (jamais votre mot de passe).
Confidentialité
- Les identifiants servent uniquement à se connecter au portail de votre commune, en HTTPS.
- Le mot de passe et les cookies de session ne sont jamais écrits dans les logs.
- La dernière lecture du portail (planning, factures, messages) est gardée
dans le volume privé
/datade l'intégration, pour détecter les changements après un redémarrage. Rien n'est envoyé ailleurs.
Paramètres de configuration
Voici les paramètres demandés par Agora Famille dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Votre portail famille | section | Non | Utilisez l'adresse et le compte avec lesquels vous vous connectez au portail Agora Famille de votre commune. L'intégration lit le portail comme le ferait un navigateur : rien n'est transmis à personne d'autre. |
| Adresse du portail | string | Oui | L'adresse de votre portail, telle que votre navigateur l'affiche, ou seulement le nom de votre commune qui y figure. |
| Identifiant (e-mail) | string | Oui | |
| Mot de passe | secret | Oui | |
| Intervalle de lecture (min) | number | Non | Fréquence de lecture du portail, en minutes (15 minimum). |
| Jours de planning suivis | number | Non | Nombre de jours à venir dont les réservations sont lues et surveillées. |
| Rappel de facture (jours) | number | Non | Le déclencheur « facture bientôt à échéance » se déclenche ce nombre de jours avant l'échéance. 0 le désactive. |
| Factures transmises au Trésor public | string | Non | Numéros des factures que la commune a transmises au Trésor public (« mise en impayé »), séparés par des virgules. Le portail les montre toujours impayées : elles sont affichées à part et pas comptées dans le reste à payer. Celles que le portail marque lui-même sont trouvées sans cela. |
| Logs détaillés | boolean | Non | Journalise chaque requête au portail (jamais le mot de passe). Pour le dépannage. |
Comment installer Agora Famille dans Gladys
- Dans Gladys, ouvrez Intégrations : Agora Famille apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/prohand/gladys-agorafamille:2.0.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/prohand/gladys-agorafamille.
Agora Famille nécessite Gladys >=5.3.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.
Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.
À propos des intégrations externes
Agora Famille est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par prohand, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation