Aller au contenu principal

Intégration domotique Actual Budget, gratuite et open source

Intégration Actual Budget pour Gladys Assistant

Soldes des comptes et enveloppes du mois de votre Actual Budget dans Gladys.

Voir sur GitHubToutes les intégrations

Votre budget par enveloppes dans Gladys : le solde de vos comptes, l'argent restant à budgéter et l'état de chaque enveloppe du mois, lus depuis votre propre Actual Budget, l'application de budget libre et auto-hébergée.

L'intégration ne fait que lire : elle n'écrit jamais dans votre budget, ne crée aucune opération. Elle parle directement à votre serveur Actual sur votre réseau, avec le paquet officiel @actual-app/api. Non affiliée à Actual Budget.

Ce que vous obtenez​

  • Un appareil par compte ouvert (compte courant, épargne, carte de crédit, placement hors budget…) : son solde, avec son historique.
  • Un appareil par catégorie du budget (une enveloppe) : budgété, dépensé et restant ce mois-ci, et la part de l'enveloppe consommée.
  • Un appareil « mois » : argent à budgéter, dépensé ce mois-ci et revenus du mois.
  • Un widget de tableau de bord : l'argent à budgéter, le solde de vos comptes et les enveloppes du mois.
  • Un déclencheur de scène : une enveloppe qui atteint 50, 75, 90 ou 100 % de son argent, ou qui est dépassée.
  • Deux actions de scène : lire les soldes ou les enveloppes, en une phrase à envoyer par message ou à faire lire à voix haute.

Prérequis​

  • Gladys Assistant 5.1 ou plus récent.
  • Un serveur Actual (actual-server, testé avec la 26.10.0), joignable depuis la machine de Gladys (même réseau, VPN ou adresse publique), avec une connexion par mot de passe.
  • Le mot de passe du serveur, et le mot de passe de chiffrement si votre budget est chiffré de bout en bout.

Configuration​

Trouver l'ID de synchronisation​

Si votre serveur n'a qu'un budget, laissez l'ID de synchronisation vide : l'intégration prend celui-là. Sinon, dans Actual, ouvrez le budget, puis Paramètres → Afficher les paramètres avancés : l'ID de synchronisation y figure. Copiez-le en entier.

Réglages​

RéglageRôle
Adresse du serveur ActualL'adresse à laquelle vous ouvrez Actual, ex. http://192.168.1.20:5006 ou https://budget.maison
Mot de passe du serveurLe mot de passe avec lequel vous vous connectez à Actual
ID de synchronisation du budgetVide pour le seul budget du serveur, sinon l'ID trouvé ci-dessus
Mot de passe de chiffrementSeulement pour un budget chiffré de bout en bout
DeviseAutomatique (la devise par défaut réglée dans Actual, l'euro sinon), ou euro, dollar, livre, CHF…
Fréquence de mise à jour5, 10, 15 (par défaut), 30 ou 60 minutes
Langue des textesNoms des fonctionnalités (à leur création) et phrases des scènes

Enregistrez, puis cliquez sur Tester la connexion : la réponse donne le nombre de comptes ouverts et de catégories du budget, ou, s'il y a plusieurs budgets et pas d'ID, leurs noms et ID de synchronisation. Ouvrez ensuite l'onglet Découverte et ajoutez les appareils voulus dans Gladys. Seuls les appareils ajoutés sont suivis : leurs états, le widget, le déclencheur et les actions ne portent que sur eux.

Appareils​

AppareilFonctionnalités
CompteSolde (négatif pour une carte de crédit à découvert)
CatégorieBudgété, Dépensé, Restant (négatif si dépassée), Enveloppe consommée (%)
MoisÀ budgéter, Dépensé ce mois-ci, Revenus du mois (tous les revenus, soldes initiaux compris)

Les montants en euros, dollars ou livres affichent leur unité ; une autre devise est ajoutée au nom de l'appareil (Épargne (CHF)). Les comptes clos, les catégories masquées (ou dans un groupe masqué) et les catégories de revenus sont écartés. Les valeurs sont celles du mois en cours, dans le fuseau horaire de Gladys.

Enveloppe consommée est ce qui a été dépensé ce mois-ci sur l'argent dont disposait l'enveloppe : le budgété plus le report du mois précédent. Une enveloppe dépensée alors qu'elle était vide affiche 1000 %, le plafond.

Pour être prévenu quand un solde passe sous un seuil, utilisez le déclencheur standard de Gladys « Changement d'état de l'appareil » sur le Solde du compte, avec la condition « inférieur » : pas besoin d'un déclencheur de l'intégration. De même pour l'argent à budgéter.

Widget de tableau de bord​

Aperçu Actual Budget affiche l'argent à budgéter (si l'appareil « mois » est ajouté) et les comptes ajoutés dans Gladys avec leur solde (en rouge s'il est négatif), puis les catégories ajoutées (8 au plus) avec le dépensé et le restant, et la part de l'enveloppe consommée : vert sous 75 %, orange jusqu'à 100 %, rouge si dépassée. Touchez une catégorie pour voir le budgété. Le pied donne l'heure de la dernière lecture.

Déclencheurs de scène​

  • Actual Budget : seuil d'enveloppe : les dépenses d'une catégorie ajoutée dans Gladys atteignent 50, 75, 90 ou 100 % de son argent du mois, ou la catégorie est dépassée (au choix). Il se déclenche une fois par seuil et par mois. Les seuils déjà atteints à la première lecture de la catégorie servent de point de départ et ne déclenchent rien. Variables : nom, budgété, dépensé, restant, part consommée (%), devise et une phrase toute prête.

Ce qui a été déclenché est gardé dans les données de l'intégration : un redémarrage ne déclenche rien deux fois.

Actions de scène​

  • Actual Budget : lire les soldes : le solde de chaque compte ajouté, en une phrase. Sorties : text, count, total (somme des soldes).
  • Actual Budget : lire les enveloppes : l'argent à budgéter (appareil « mois » ajouté), puis ce que chaque catégorie ajoutée a dépensé et garde. Sorties : text, count, over_count (catégories dépassées), to_budget.

Une action relit le budget quand la dernière lecture date de plus d'un intervalle de mise à jour.

Exemples de scènes​

  • Courses presque épuisées : déclencheur « seuil d'enveloppe », 90 %, sur la catégorie des courses ; action : prévenir la famille sur Telegram avec {{triggerEvent.data.text}}.
  • Dépassement : déclencheur « seuil d'enveloppe », « Dépassée », sur une catégorie ; action : envoyer un message pour la renflouer.
  • Point du lundi matin : chaque lundi à 8 h, action « lire les enveloppes », puis faire lire {{output.text}} par l'enceinte de la cuisine.

Confidentialité et données​

  • L'intégration lit votre budget et n'y écrit jamais.
  • Les mots de passe sont gardés par Gladys comme tout réglage secret, et jamais écrits dans les journaux.
  • Les journaux ne contiennent jamais de montant, de nom de compte ou de catégorie, d'ID de synchronisation ni l'adresse du serveur, même en debug : seulement des nombres, des codes d'erreur et des seuils.
  • Aucun numéro de compte n'est mis dans Gladys. Les noms des comptes et catégories deviennent des noms d'appareils, que vous pouvez renommer.
  • Le volume de données de l'intégration garde une copie locale du budget (comme le fait l'application Actual), pour qu'une lecture ne télécharge que ce qui a changé. Cette copie n'est pas chiffrée, même pour un budget chiffré de bout en bout : protégez la machine de Gladys en conséquence. Elle est supprimée quand un autre serveur ou budget est configuré, et à chaque redémarrage de l'intégration. Le volume garde aussi les seuils déjà déclenchés (identifiants, mois et seuils).

Dépannage​

MessageQue faire
Le serveur Actual refuse le mot de passeVérifiez le mot de passe ; un serveur en connexion OpenID n'est pas pris en charge
Le serveur Actual ne répond pasVérifiez l'adresse depuis la machine de Gladys (port 5006, http/https) et qu'Actual tourne
Aucun budget avec cet IDRecopiez l'ID depuis Paramètres → Afficher les paramètres avancés
Le serveur a plusieurs budgetsIndiquez l'ID : « Tester la connexion » liste les budgets avec le leur
Ce budget est chiffré de bout en boutIndiquez son mot de passe de chiffrement
Ce budget demande une version plus récenteActual a été mis à jour : mettez aussi l'intégration à jour
Un appareil n'a pas de valeurAjoutez-le dans l'onglet Découverte : seuls les appareils ajoutés sont suivis

Les journaux de l'intégration (Intégrations → Actual Budget → journaux) disent ce qui s'est passé ; LOG_LEVEL=debug donne plus de détails. Une adresse https demande un certificat que l'intégration reconnaît : avec un certificat auto-signé, utilisez l'adresse http du serveur sur votre réseau.

Limites​

  • Lecture seule : aucune opération ne peut être créée depuis Gladys.
  • Un serveur, un budget ; connexion par mot de passe seulement (pas d'OpenID).
  • Pas de conversion entre devises : Actual a une devise par budget.
  • Un budget en mode suivi (« tracking ») n'a pas d'« à budgéter » : cette fonctionnalité reste vide.
  • Les valeurs suivent l'intervalle de mise à jour : une opération apparaît dans Gladys à la lecture suivante. La synchronisation bancaire n'est pas lancée par l'intégration.
  • Chaque lecture charge le paquet d'Actual quelques secondes (environ 100 Mo de mémoire), puis le libère.
  • Testée contre un vrai actual-server 26.10.0 en Docker, avec et sans chiffrement de bout en bout, pas encore sur une installation de Gladys avec de vrais comptes : vos retours sont les bienvenus.

Paramètres de configuration​

Voici les paramètres demandés par Actual Budget dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Connexion à Actual BudgetsectionNonIndiquez l'adresse de votre serveur Actual et son mot de passe. Si le serveur a plusieurs budgets, ajoutez l'ID de synchronisation de celui à lire (Paramètres → Afficher les paramètres avancés). Ajoutez ensuite les comptes et catégories voulus dans l'onglet Découverte.
Adresse du serveur ActualstringOuiL'adresse à laquelle vous ouvrez Actual, joignable depuis Gladys.
Mot de passe du serveursecretOuiLe mot de passe avec lequel vous vous connectez à Actual. Lecture seule : l'intégration n'écrit jamais dans votre budget. Gardé par Gladys, jamais écrit dans les journaux.
ID de synchronisation du budgetstringNonVide : le seul budget du serveur. Dans Actual : Paramètres → Afficher les paramètres avancés → ID de synchronisation.
Mot de passe de chiffrementsecretNonSeulement pour un budget chiffré de bout en bout.
DeviseselectNonDevise des montants. Automatique : la devise par défaut réglée dans Actual, l'euro sinon.
Fréquence de mise à jourselectNonFréquence de lecture d’Actual Budget. Votre argent ne bouge pas à la seconde : 15 minutes suffisent.
Langue des textesselectNonNoms des fonctionnalités (à leur création) et textes envoyés aux scènes.

Comment installer Actual Budget dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Actual Budget apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
  2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/guim31/gladys-actual:1.0.0), 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).
  3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
  4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/guim31/gladys-actual.

Actual Budget nécessite Gladys >=5.1.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​

Actual Budget 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 guim31, et non par l'équipe cœur de Gladys.

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂
Dernière mise à jour le