Integración domótica Actual Budget, gratuita y de código abierto

Saldos de las cuentas y sobres del mes de su Actual Budget en Gladys.

• Publicado por guim31
• Dispositivos
• Versión 1.0.0
• Requiere Gladys >=5.1.0
• ★ 0

Ver en GitHubTodas las integraciones

Su presupuesto por sobres en Gladys: los saldos de sus cuentas, el dinero que queda por presupuestar y el estado de cada sobre del mes, leídos desde su propio Actual Budget, la aplicación de presupuesto libre y autoalojada.

La integración solo lee: nunca escribe en su presupuesto, no crea ninguna transacción. Habla directamente con su servidor Actual en su red, con el paquete oficial @actual-app/api. Sin afiliación con Actual Budget.

Qué obtiene

• Un dispositivo por cuenta abierta (corriente, ahorro, tarjeta de crédito, inversión fuera del presupuesto…): su saldo, con su historial.
• Un dispositivo por categoría del presupuesto (un sobre): presupuestado, gastado y restante este mes, y la parte del sobre consumida.
• Un dispositivo «mes»: dinero por presupuestar, gastado este mes e ingresos del mes.
• Un widget del panel: el dinero por presupuestar, los saldos de sus cuentas y los sobres del mes.
• Un disparador de escena: un sobre que alcanza el 50, 75, 90 o 100 % de su dinero, o que está sobrepasado.
• Dos acciones de escena: leer los saldos o los sobres, en una frase para enviar por mensaje o hacer leer en voz alta.

Requisitos

• Gladys Assistant 5.1 o posterior.
• Un servidor Actual (actual-server, probado con la 26.10.0), accesible desde el equipo de Gladys (misma red, VPN o dirección pública), con inicio de sesión por contraseña.
• La contraseña del servidor, y la contraseña de cifrado si su presupuesto usa cifrado de extremo a extremo.

Configuración

Encontrar el ID de sincronización

Si su servidor solo tiene un presupuesto, deje vacío el ID de sincronización: la integración toma ese. Si no, en Actual, abra el presupuesto y luego Ajustes → Mostrar ajustes avanzados: ahí aparece el ID de sincronización. Cópielo entero.

Ajustes

Ajuste	Función
Dirección del servidor Actual	La dirección con la que abre Actual, p. ej. http://192.168.1.20:5006 o https://budget.home
Contraseña del servidor	La contraseña con la que inicia sesión en Actual
ID de sincronización del presupuesto	Vacío para el único presupuesto del servidor; si no, el ID encontrado arriba
Contraseña de cifrado	Solo para un presupuesto con cifrado de extremo a extremo
Divisa	Automática (la divisa predeterminada de Actual, el euro si no hay), o euro, dólar, libra, CHF…
Intervalo de actualización	5, 10, 15 (por defecto), 30 o 60 minutos
Idioma de los textos	Nombres de las funciones (al crearlas) y frases de las escenas

Guarde y pulse Probar la conexión: la respuesta indica cuántas cuentas abiertas y categorías tiene el presupuesto o, con varios presupuestos y sin ID, sus nombres e ID de sincronización. Después abra la pestaña Descubrir y añada los dispositivos que desee a Gladys. Solo se siguen los dispositivos añadidos: sus estados, el widget, el disparador y las acciones solo los incluyen a ellos.

Dispositivos

Dispositivo	Funciones
Cuenta	Saldo (negativo para una tarjeta de crédito en descubierto)
Categoría	Presupuestado, Gastado, Restante (negativo si se sobrepasa), Sobre consumido (%)
Mes	Por presupuestar, Gastado este mes, Ingresos del mes (todos los ingresos, saldos iniciales incluidos)

Los importes en euros, dólares o libras muestran su unidad; otra divisa se añade al nombre del dispositivo (Ahorro (CHF)). Se omiten las cuentas cerradas, las categorías ocultas (o en un grupo oculto) y las categorías de ingresos. Los valores son los del mes en curso, en la zona horaria de Gladys.

Sobre consumido es lo gastado este mes respecto al dinero que tenía el sobre: lo presupuestado más lo arrastrado del mes anterior. Un sobre del que se gastó estando vacío muestra 1000 %, el tope.

Para recibir un aviso cuando un saldo baja de un umbral, use el disparador estándar de Gladys «Cambio de estado del dispositivo» sobre el Saldo de la cuenta, con la condición «menor»: no hace falta un disparador de la integración. Lo mismo para el dinero por presupuestar.

Widget del panel

Resumen de Actual Budget muestra el dinero por presupuestar (si el dispositivo «mes» está añadido) y las cuentas añadidas a Gladys con su saldo (en rojo si es negativo), luego las categorías añadidas (8 como máximo) con lo gastado y lo restante, y la parte del sobre consumida: verde por debajo del 75 %, naranja hasta el 100 %, rojo si se sobrepasa. Toque una categoría para ver lo presupuestado. El pie indica la hora de la última lectura.

Disparadores de escena

• Actual Budget: umbral de sobre: el gasto de una categoría añadida a Gladys alcanza el 50, 75, 90 o 100 % de su dinero del mes, o la categoría está sobrepasada (elija uno). Se dispara una vez por umbral y por mes. Los umbrales ya alcanzados en la primera lectura de la categoría son el punto de partida y no disparan nada. Variables: nombre, presupuestado, gastado, restante, parte consumida (%), divisa y una frase lista.

Lo disparado se guarda en los datos de la integración: un reinicio no dispara nada dos veces.

Acciones de escena

• Actual Budget: leer los saldos: el saldo de cada cuenta añadida, en una frase. Salidas: text, count, total (suma de los saldos).
• Actual Budget: leer los sobres: el dinero por presupuestar (dispositivo «mes» añadido), y luego lo que cada categoría añadida ha gastado y le queda. Salidas: text, count, over_count (categorías sobrepasadas), to_budget.

Una acción vuelve a leer el presupuesto cuando la última lectura es más antigua que el intervalo de actualización.

Ejemplos de escenas

• Compras casi agotadas: disparador «umbral de sobre», 90 %, sobre la categoría de compras; acción: avisar a la familia por Telegram con {{triggerEvent.data.text}}.
• Sobrepasado: disparador «umbral de sobre», «Sobrepasado», sobre una categoría; acción: enviar un mensaje para cubrirlo.
• Resumen del lunes: cada lunes a las 8, acción «leer los sobres», y luego hacer leer {{output.text}} por el altavoz de la cocina.

Privacidad y datos

• La integración lee su presupuesto y nunca escribe en él.
• Gladys guarda las contraseñas como cualquier ajuste secreto, y nunca se escriben en los registros.
• Los registros nunca contienen un importe, un nombre de cuenta o de categoría, un ID de sincronización ni la dirección del servidor, ni siquiera en modo debug: solo cantidades, códigos de error y umbrales.
• Ningún número de cuenta llega a Gladys. Los nombres de cuentas y categorías pasan a ser nombres de dispositivos, que puede renombrar.
• El volumen de datos de la integración guarda una copia local del presupuesto (como hace la aplicación Actual), para que una lectura solo descargue lo que cambió. Esta copia no está cifrada, ni siquiera para un presupuesto con cifrado de extremo a extremo: proteja el equipo de Gladys en consecuencia. Se borra cuando se configura otro servidor u otro presupuesto, y en cada reinicio de la integración. El volumen guarda también los umbrales ya disparados (identificadores, meses y umbrales).

Solución de problemas

Mensaje	Qué hacer
El servidor Actual rechaza la contraseña	Compruebe la contraseña; un servidor con inicio de sesión OpenID no es compatible
El servidor Actual no responde	Compruebe la dirección desde el equipo de Gladys (puerto 5006, http/https) y que Actual funciona
Ningún presupuesto con este ID	Vuelva a copiar el ID desde Ajustes → Mostrar ajustes avanzados
El servidor tiene varios presupuestos	Indique el ID: «Probar la conexión» lista los presupuestos con el suyo
Este presupuesto está cifrado de extremo a extremo	Indique su contraseña de cifrado
Este presupuesto requiere una versión más reciente	Actual se actualizó: actualice también la integración
Un dispositivo no tiene valor	Añádalo en la pestaña Descubrir: solo se siguen los dispositivos añadidos

Los registros de la integración (Integraciones → Actual Budget → registros) dicen qué ocurrió; LOG_LEVEL=debug da más detalle. Una dirección https necesita un certificado en el que la integración confíe: con uno autofirmado, use la dirección http del servidor en su red.

Límites

• Solo lectura: no se puede crear ninguna transacción desde Gladys.
• Un servidor, un presupuesto; solo inicio de sesión por contraseña (sin OpenID).
• Sin conversión entre divisas: Actual tiene una divisa por presupuesto.
• Un presupuesto de seguimiento («tracking») no tiene «por presupuestar»: esa función queda vacía.
• Los valores siguen el intervalo de actualización: una transacción aparece en Gladys en la siguiente lectura. La sincronización bancaria no la lanza la integración.
• Cada lectura carga el paquete de Actual unos segundos (unos 100 MB de memoria) y luego lo libera.
• Probada contra un actual-server 26.10.0 real en Docker, con y sin cifrado de extremo a extremo, aún no en una instalación de Gladys con cuentas reales: sus comentarios son bienvenidos.

Parámetros de configuración

Estos son los parámetros que Actual Budget te pide en su pantalla de configuración en Gladys.

Parámetro	Tipo	Obligatorio	Descripción
Conexión con Actual Budget	section	No	Indique la dirección de su servidor Actual y su contraseña. Si el servidor tiene varios presupuestos, añada el ID de sincronización del que desea leer (Ajustes → Mostrar ajustes avanzados). Después añada las cuentas y categorías que desee en la pestaña Descubrir.
Dirección del servidor Actual	string	Sí	La dirección con la que abre Actual, accesible desde Gladys.
Contraseña del servidor	secret	Sí	La contraseña con la que inicia sesión en Actual. Solo lectura: la integración nunca escribe en su presupuesto. Guardada por Gladys, nunca escrita en los registros.
ID de sincronización del presupuesto	string	No	Vacío: el único presupuesto del servidor. En Actual: Ajustes → Mostrar ajustes avanzados → ID de sincronización.
Contraseña de cifrado	secret	No	Solo para un presupuesto con cifrado de extremo a extremo.
Divisa	select	No	Divisa de los importes. Automática: la divisa predeterminada de Actual, el euro si no hay.
Intervalo de actualización	select	No	Frecuencia de lectura de Actual Budget. Su dinero no se mueve cada segundo: 15 minutos bastan.
Idioma de los textos	select	No	Nombres de las funciones (al crearlas) y textos enviados a las escenas.

Cómo instalar Actual Budget en Gladys

1. En Gladys, abre Integraciones: Actual Budget aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/guim31/gladys-actual:1.0.0), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-actual.

Actual Budget requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas

Actual Budget es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene guim31, no el equipo principal de Gladys.

• Explorar todas las integraciones, nativas y de la comunidad
• Crear y publicar tu propia integración externa
• Código fuente en GitHub — fuente de esta documentación

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂