Integración domótica Paperless-ngx, gratuita y de código abierto
Sus documentos de Paperless-ngx en Gladys: bandeja de entrada, nuevos escaneos, errores y escenas.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Siga su servidor de documentos Paperless-ngx desde Gladys, en su red local: cuántos documentos esperan en la bandeja de entrada, qué se ha escaneado hoy, si ha fallado un escaneo — e inicie una escena cuando llegue un documento nuevo, por ejemplo «acaba de llegar una factura de Iberdrola».
La integración solo lee: nunca crea, modifica ni elimina un documento, una etiqueta o una tarea en Paperless-ngx.
Probada con servidores Paperless-ngx reales, todavía no en un Gladys real: sus comentarios son bienvenidos. La integración se ha desarrollado y probado con las imágenes Docker oficiales de Paperless-ngx 3.3.1 y 2.20.6, y con el Gladys simulado del SDK de integraciones. Si algo no funciona como se describe, indíquelo en el foro de Gladys o en las issues.
Qué necesita
- Gladys Assistant 5.1.0 o posterior.
- Paperless-ngx 2.x o 3.x, accesible desde Gladys (probado: 2.20.6 y 3.3.1).
- Un token de API de un usuario de Paperless-ngx. En Paperless-ngx, haga clic en su nombre (arriba a la derecha) → Mi Perfil → Token de autenticación de la API: créelo si no existe y cópielo.
La integración ve lo que ve ese usuario: los documentos que le pertenecen o que se han compartido con él, sus tareas y las que no tienen propietario. Use el token del usuario cuyos documentos quiere seguir; el token de un administrador muestra además el almacenamiento libre, que Paperless-ngx solo muestra a los administradores.
Puesta en marcha
- Instale la integración desde el catálogo de Gladys.
- En Configuración, introduzca la Dirección de Paperless-ngx (por
ejemplo
http://192.168.1.2:8000, la dirección con la que abre Paperless-ngx) y el Token de API. - Guarde y haga clic en Probar la conexión: el mensaje bajo el botón indica la versión, el número de documentos y de tareas.
- Abra la pestaña Descubrir: allí está el dispositivo Paperless-ngx. Haga clic en Añadir, elija una habitación y guarde.
Opciones:
- Aceptar certificados autofirmados: para una dirección
https://servida con su propio certificado (un proxy inverso en su casa). Déjela desmarcada en otro caso. - Intervalo de actualización: con qué frecuencia se lee Paperless-ngx, de 30 segundos a 5 minutos (1 minuto por defecto).
- Buscar actualizaciones de Paperless-ngx: cada 6 horas, Paperless-ngx pregunta a GitHub por su última versión (activado por defecto). Desmárquelo y la pregunta no se hace nunca.
- Idioma de los nombres de las funciones: inglés, francés, alemán o español. Los nombres se asignan al añadir el dispositivo (francés por defecto).
El dispositivo Paperless-ngx
| Función | Qué es |
|---|---|
| En línea | 1 cuando Paperless-ngx responde, 0 tras dos lecturas fallidas seguidas |
| Total de documentos | Todos los documentos que el usuario puede ver |
| Documentos en la bandeja de entrada | Documentos con una etiqueta de entrada: pendientes de clasificar |
| Documentos añadidos hoy | Documentos añadidos desde la medianoche (zona horaria de Gladys) |
| Tareas en curso | Tareas en espera o en ejecución: escaneos en proceso, trabajos programados |
| Tareas con error | Tareas fallidas que no se han descartado en Paperless-ngx |
| Interlocutores | Número de interlocutores |
| Tipos de documento | Número de tipos de documento |
| Etiquetas | Número de etiquetas |
| Almacenamiento libre | Espacio libre del almacenamiento de Paperless-ngx, en GB (solo token de administrador) |
| Actualización disponible | 1 cuando ha salido una versión más reciente de Paperless-ngx (nada sin GitHub) |
| Versión | La versión de Paperless-ngx, como texto |
Cada número conserva su historial en Gladys y puede controlar una escena («cuando Documentos en la bandeja de entrada supere 10…»).
Panel
El widget Bandeja de Paperless muestra tres mosaicos — documentos por
clasificar, añadidos hoy, tareas con error — y los últimos documentos de la
bandeja de entrada con su interlocutor y su tipo (3, 5 u 8, según los ajustes
del widget). Con una dirección https://, cada documento enlaza con
Paperless-ngx, y un botón Abrir Paperless lo abre; Gladys solo muestra
enlaces https://.
Escenas
Disparadores
- Nuevo documento en Paperless-ngx: se ha añadido un documento (escaneo,
correo, subida). Filtros: Interlocutor y Tipo de documento,
escritos exactamente como en Paperless-ngx (mayúsculas incluidas); si se
dejan vacíos, cualquier documento vale. Las acciones siguientes pueden leer
{{triggerEvent.data.title}},correspondent,document_type,tags(separadas por comas),document_idyurl(el enlace al documento en Paperless-ngx). - Nuevo documento con una etiqueta: lo mismo, una vez por cada etiqueta
del documento nuevo. Filtros: la Etiqueta (obligatoria) y, si lo
desea, el Interlocutor. Las mismas variables, más
tag. Paperless-ngx da sus etiquetas de entrada a cada documento nuevo: una escena sobre la etiqueta «Inbox» se inicia con cada documento nuevo. - Error al procesar un documento: Paperless-ngx no ha podido procesar un
archivo (escaneo ilegible, duplicado…) o una de sus tareas ha fallado.
Variables:
file_nameyerror.
Los documentos nuevos se detectan comparando su número con el último visto; las tareas con error, también por su número. Como máximo 10 eventos por disparador y por lectura (una importación masiva no inicia una escena cien veces), y nada de más de 24 horas. Lo que ya existe en el primer arranque de la integración no se anuncia; tras un reinicio, sí los documentos añadidos mientras tanto.
Acciones
La integración no tiene acción de escena: solo lee. El botón Probar la conexión de la pantalla de configuración lee Paperless-ngx enseguida y muestra un informe.
Ideas de escenas
- «Factura de Iberdrola recibida»: disparador Nuevo documento en
Paperless-ngx, Interlocutor
Iberdrola, Tipo de documentoFactura→ enviar un mensaje «Nueva factura: {{triggerEvent.data.title}}». - «Correo urgente»: disparador Nuevo documento con una etiqueta,
Etiqueta
Urgente→ poner la luz de la entrada en naranja. - «El escáner se ha atascado»: disparador Error al procesar un documento → enviar un mensaje «Paperless no ha podido procesar {{triggerEvent.data.file_name}}».
- «Recordatorio de clasificación»: cada sábado a las 10:00, continuar solo si Documentos en la bandeja de entrada es mayor que 0 → enviar un mensaje.
Peticiones enviadas a Paperless-ngx
En cada lectura (cada minuto por defecto): las estadísticas, el número de documentos añadidos hoy, los documentos más recientes de las últimas 24 horas (25 como máximo, sin su contenido), las tareas en curso y las fallidas — cinco peticiones GET ligeras (seis con Paperless-ngx 2.x). Cada 10 minutos, el estado del sistema (almacenamiento), y cada 6 horas la última versión. Los nombres de interlocutores, tipos y etiquetas solo se leen para los documentos nuevos y se guardan una hora. Paperless-ngx no impone cuota de peticiones; en un NAS pequeño, elija un intervalo más largo.
Solución de problemas
- «Token de API rechazado»: copie de nuevo el token desde Mi Perfil; un token creado de nuevo sustituye al anterior. Un usuario desactivado también se rechaza.
- «Paperless-ngx no responde»: compruebe la dirección y el puerto desde
el equipo en el que se ejecuta Gladys (
curl http://192.168.1.2:8000/api/). - «La dirección redirige»: introduzca directamente la dirección
https://. Un portal de acceso (Authelia, Authentik…) delante de Paperless-ngx debe dejar pasar/api/con el token. - «Certificado rechazado»: marque Aceptar certificados autofirmados.
- «No hay ninguna API de Paperless-ngx en esta dirección»: la dirección responde, pero no con Paperless-ngx (falta una subruta, otro servicio en el puerto).
- El almacenamiento libre sigue vacío: el token no es de un administrador.
- 0 documentos aunque Paperless-ngx tiene muchos: el usuario del token no puede verlos (documentos de otro propietario): use otro token o compártalos.
- Actualización disponible sigue vacía: Paperless-ngx no ha podido consultar GitHub (sin acceso a Internet en el servidor) o la comprobación está desactivada.
- Más detalles: defina
LOG_LEVEL=debugen el contenedor; los registros muestran entonces cada lectura. El token nunca se escribe en los registros.
Límites
- Una sola instancia de Paperless-ngx por instalación de la integración.
- Solo lectura: ni subida, ni etiquetado, ni descarte de tareas fallidas desde Gladys.
- Los filtros de los disparadores comparan nombres exactos:
EDFno corresponde aedf. - Un documento se anuncia una vez, cuando se ve por primera vez; una etiqueta añadida más tarde a mano no inicia Nuevo documento con una etiqueta.
- Paperless-ngx 1.x no es compatible.
- Sin relación con el proyecto Paperless-ngx.
Parámetros de configuración
Estos son los parámetros que Paperless-ngx te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Su Paperless-ngx | section | No | En Paperless-ngx, abra Mi Perfil (arriba a la derecha) y cree o copie el token de autenticación de la API; después péguelo abajo con la dirección de Paperless-ngx. La integración solo lee: nunca modifica un documento. El token de un administrador muestra también el almacenamiento libre. |
| Dirección de Paperless-ngx | string | No | La dirección con la que abre Paperless-ngx, puerto incluido (8000 por defecto). |
| Token de API | secret | No | Mi Perfil → Token de autenticación de la API. Se ven los documentos de este usuario. |
| Aceptar certificados autofirmados | boolean | No | Para una dirección https:// servida con su propio certificado. Márquelo solo para su propio servidor. |
| Intervalo de actualización | select | No | Con qué frecuencia se lee Paperless-ngx: unas cinco peticiones ligeras cada vez. |
| Buscar actualizaciones de Paperless-ngx | boolean | No | Cada 6 horas, Paperless-ngx pregunta a GitHub por su última versión. Desmárquelo para no preguntar nunca. |
| Idioma de los nombres de las funciones | select | No | Gladys conserva los nombres dados al añadir el dispositivo. |
Cómo instalar Paperless-ngx en Gladys
- En Gladys, abre Integraciones: Paperless-ngx aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/guim31/gladys-paperless:1.0.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-paperless.
Paperless-ngx 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
Paperless-ngx 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