Home Assistant & Paperless-NGX verbinden: Smarte Dokumente

Estimated reading time: 9 Minuten

Smart Home trifft auf digitale Ordnung – und das auf deinem eigenen Server.
Wenn du Home Assistant für dein Smart Home nutzt und Paperless-NGX zur digitalen Dokumentenverwaltung einsetzt, kannst du durch ihre Kombination ein echtes Automatisierungs-Kraftpaket schaffen. In diesem Artikel zeige ich dir, wie du beide Tools sinnvoll miteinander verknüpfst – einfach, effizient und sicher.

Für eine detaillierte Anleitung und Erklärung aller Konfigurationsmöglichkeiten empfehle ich das unten verlinkte YouTube-Video. In diesem Video wird ausführlich auf jede einzelne Einstellung eingegangen, sodass du eine umfassende Anleitung zur genauen Einrichtung erhältst. Eventuellen Code aus dem Video findest du in diesem Beitrag, so dass du ihn direkt nutzen kannst ohne abtippen zu müssen.

🔧 Warum diese Kombination Sinn ergibt

Home Assistant ist die Schaltzentrale deines Smart Homes – du steuerst alles von Licht bis Sicherheit. Paperless-NGX dagegen hilft dir, deine Papierflut zu bändigen und Dokumente digital zu verwalten. Gemeinsam sorgen sie für maximale Kontrolle über dein digitales Zuhause – inklusive automatisierter Workflows.

Stell dir vor: Eine neue Rechnung flattert per Mail herein oder wird gescannt. Paperless-NGX erkennt automatisch den Anbieter, das Datum und den Betrag. Gleichzeitig informiert dich Home Assistant darüber – oder triggert sogar Aktionen:

• Lichtbenachrichtigung bei neuer Rechnung
• Push-Nachricht bei Steuerdokumenten
• Erinnerung im Kalender bei Zahlungsfristen
• Automatischer Upload von Dokumenten in die Cloud oder dein NAS

Was ist Paperless-NGX?

Paperless-NGX ist ein leistungsfähiges, selbst gehostetes Dokumentenmanagement-System (DMS), das dir dabei hilft, Ordnung in dein digitales Dokumentenchaos zu bringen. Es basiert auf dem ursprünglichen Open-Source-Projekt „Paperless“ und wurde unter dem Namen „Paperless-NGX“ als modernisierte, aktiv gepflegte und stark verbesserte Variante weiterentwickelt.

Hier zur Paperless-NGX Installation.

🧾 Die Grundidee: Dokumente digital erfassen & durchsuchbar machen

Mit Paperless-NGX kannst du alle deine papierbasierten oder digitalen Dokumente zentral verwalten. Egal ob eingescannte Rechnungen, Briefe, Verträge oder PDF-Dokumente per E-Mail – alles wird strukturiert abgelegt, automatisch verschlagwortet und mithilfe von OCR (Optical Character Recognition) durchsuchbar gemacht. Dabei ist es egal, ob das Dokument aus dem Scanner kommt, als PDF hochgeladen wurde oder per E-Mail an Paperless weitergeleitet wird.

🧠 Intelligente Texterkennung mit OCR

Ein zentrales Feature ist die integrierte Texterkennung. Dank OCR werden Inhalte automatisch ausgelesen – sogar aus handschriftlichen oder schlecht gescannten Dokumenten (je nach Qualität). Das ermöglicht es dir, nicht nur nach Dateinamen, sondern auch nach Inhalten zu suchen – z. B. nach dem Namen eines Absenders, einer Rechnungsnummer oder einem bestimmten Betrag.

🏷️ Automatisches Tagging & Dokumentenklassifizierung

Paperless-NGX nutzt Konsumenten (consumers) – das sind kleine Regeln oder Skripte, die automatisch Dokumente erkennen, verschlagworten (taggen), kategorisieren und archivieren. Beispielsweise erkennt das System, dass es sich bei einem bestimmten PDF um eine Stromrechnung von deinem Versorger handelt, und weist es der Kategorie „Nebenkosten“ zu, versieht es mit dem Tag „Strom“ und legt es im passenden Jahr ab.

Du kannst die Regeln individuell anpassen – entweder durch einfache Benutzeroberflächen oder durch reguläre Ausdrücke (RegEx), wenn du tiefer einsteigen willst.

📥 Mehrere Importquellen möglich

Dokumente gelangen auf verschiedenen Wegen in Paperless-NGX:

• Direkter Upload über die Weboberfläche
• Automatischer Import aus einem lokalen Ordner (z. B. vom Scanner)
• E-Mail-Import über eine dedizierte IMAP-Schnittstelle
• API-Upload durch andere Anwendungen

Damit kannst du z. B. deinen Scanner oder Multifunktionsdrucker so konfigurieren, dass er Dokumente direkt an Paperless-NGX übergibt – vollautomatisch.

🗃️ Suchfunktion & Filter

Die intuitive Weboberfläche bietet dir eine mächtige Suchfunktion mit verschiedenen Filtern – nach Datum, Kategorie, Schlagwort, Quelle, Dokumenttyp und vielem mehr. Du findest also in Sekunden jedes Dokument – auch Jahre später. Ideal für Steuererklärungen, Garantien oder Vertragsüberprüfungen.

🔒 Datenschutz & Selbst-Hosting

Ein großer Vorteil: Paperless-NGX läuft komplett lokal bei dir – z. B. auf einem NAS, Raspberry Pi, Linux-Server oder via Docker. Du behältst die volle Kontrolle über deine Daten. Keine Cloud, kein externer Anbieter, keine Abo-Kosten. Ideal für alle, die Wert auf Datenschutz und digitale Souveränität legen.

🧩 Erweiterbar & API-freundlich

Dank einer gut dokumentierten REST-API kannst du Paperless-NGX leicht in andere Systeme integrieren – wie z. B. Home Assistant, Zapier, n8n oder individuelle Skripte. So lassen sich clevere Automationen realisieren – vom Lichtsignal bei neuer Rechnung bis zur automatischen Weiterleitung an deine Steuerberatung.

Was ist Home Assistant?

Home Assistant ist eine Open-Source-Plattform für die Heimautomatisierung, die darauf abzielt, alle Geräte im Haus miteinander zu verbinden und zentral zu steuern. Sie wurde entwickelt, um eine einheitliche Benutzeroberfläche und eine einfache, flexible Steuerung für eine Vielzahl von Smart-Home-Geräten aus unterschiedlichen Ökosystemen zu bieten. Hier sind einige Punkte, die für Home Assistant spechen:

1. Kompatibilität: Home Assistant unterstützt Tausende von Geräten und Diensten von verschiedenen Herstellern, einschließlich Beleuchtung, Klimaanlagen, Heizungen, Kameras, Wettersensoren, Sprachassistenten und mehr.
2. Lokale Steuerung: Im Gegensatz zu vielen kommerziellen Smart-Home-Plattformen, die auf Cloud-Dienste angewiesen sind, läuft Home Assistant lokal in deinem Netzwerk. Dies bedeutet erhöhte Privatsphäre und Zuverlässigkeit, da deine Smart-Home-Geräte auch ohne aktive Internetverbindung funktionieren.
3. Automatisierung und Szenen: Eines der Hauptmerkmale von Home Assistant ist die Möglichkeit, komplexe Automatisierungen und Szenarien zu erstellen. Du kannst beispielsweise Lichter automatisch einschalten lassen, wenn es dunkel wird oder die Heizung einschalten, wenn die Temperatur unter einen bestimmten Wert fällt.
4. Einfache Benutzeroberfläche: Home Assistant bietet eine nutzerfreundliche Oberfläche, die es einfach macht, Geräte zu überwachen und zu steuern. Diese Oberfläche ist vollständig anpassbar.
5. Integration mit Sprachassistenten: Home Assistant kann mit Sprachassistenten wie Amazon Alexa oder Google Assistant integriert werden, um eine sprachgesteuerte Steuerung deiner Smart-Home-Geräte zu ermöglichen.
6. Open-Source und Community-Getrieben: Da Home Assistant Open-Source ist, wird es von einer aktiven Community unterstützt, die ständig neue Integrationen entwickelt und bestehende verbessert.
7. Datenschutz und Sicherheit: Als lokal laufende Plattform hat Home Assistant den Vorteil, dass die Daten im eigenen Netzwerk bleiben. Dies schützt die Privatsphäre und erhöht die Sicherheit im Vergleich zu Cloud-basierten Lösungen.

Zusammenfassend ist Home Assistant eine leistungsstarke und flexible Lösung für diejenigen, die ihr Smart Home selbst gestalten und ihre Geräte unabhängig vom Hersteller oder Ökosystem zentral steuern möchten.

iX1600 ScanSnap Scanner (White) - A4, A5, A6, B5, B6, Visitenkarte, Postkarte, Letter, Legal und Benutzerdefiniert, Duplex, Wi-Fi, USB3.2, (40 Seiten/80 Bilder/Min) mit ADF, White, ADF, 40 ppm*

von FUJITSU

Preis: € 384,01 Jetzt auf Amazon kaufen* Preis inkl. MwSt., zzgl. Versandkosten

Amazon

Epson WorkForce DS-410 Dokumentenscanner (Scanner, DIN A4, beidseitiges Scannen in einem Durchgang, 600dpi, USB 2.0)*

von Epson

Preis: € 299,99 Jetzt auf Amazon kaufen* Preis inkl. MwSt., zzgl. Versandkosten

Amazon

Canon P-208II - imageFORMULA Mobiler Dokumentenscanner (Duplex DIN-A4 Einzug, Farbe, 600dpi, 8 Seiten/Min, 10 Blatt ADF, PDF durchsuchbar, OCR, Plug & Scan, Twain, schwarz)*

von Canon

Preis: € 137,29 Jetzt auf Amazon kaufen* Preis inkl. MwSt., zzgl. Versandkosten

Amazon

Zuletzt aktualisiert am 8. Juli 2025 um 04:40 . Wir weisen darauf hin, dass sich hier angezeigte Preise inzwischen geändert haben können. Alle Angaben ohne Gewähr.

⚙️ So integrierst du Paperless-NGX in Home Assistant

1. Paperless-NGX mit Docker aufsetzen
   Am besten installierst du Paperless-NGX via Docker-Compose auf demselben Server, auf dem Home Assistant läuft (z. B. auf einem Raspberry Pi, Intel NUC oder einem Homeserver). Dazu findest du bereits einen passenden Artikel samt Video bei mir: Paperless-NGX
2. Integration nutzen (dazu im restlichen Artikel mehr):
   Seit neuestem gibt es eine offizielle Integration von Paperless-NGX für Home Assistant.
   
3. REST-API nutzen
   Paperless-NGX bietet eine moderne REST-API, die du in Home Assistant integrieren kannst. Eine simple Möglichkeit zur Integration in Home Assistant ist der rest-Sensor oder http-Sensor. Beispiel:

sensor:
  - platform: rest
    name: "Dokumente im Posteingang"
    resource: http://192.168.178.29:8001/api/documents/?correspondent__isnull=true
    value_template: "{{ value_json.count }}"
    scan_interval: 300

Damit liest Home Assistant regelmäßig den Status deines Paperless-Posteingangs aus. Der Vorteil von eigenen REST-Sensoren ist, dass man sie noch individueller gestalten kann. Aber es ist auch komplizierter.

🚀 Alle verfügbaren Sensoren und Features

Die Integration stellt eine Vielzahl an Sensoren bereit, die dir Echtzeit-Einblicke in den Status deines Paperless‑ngx-Systems bieten:

• correspondents – Anzahl definierter Ansprechpartner (Korrespondenzpartner)
• document_types – Anzahl definierter Dokumenttypen
• documents_inbox – Anzahl aktueller Dokumente im Eingangsordner (Posteingang)
• tags – Anzahl definierter Tags
• total_characters – Gesamtzahl der via OCR extrahierten Zeichen
• total_documents – Gesamtzahl aller gespeicherten Dokumente
• total_storage – Gesamter von Paperless‑ngx belegter Speicherplatz
• available_storage – Noch verfügbarer Speicherplatz
• status_database – Status der Datenbank (erreichbar/fehlerfrei)
• status_index – Status des Dokumentenindexers
• status_classifier – Status des Klassifikators (Automatische Tagging/Classifier-Service)
• status_celery – Status des Celery-Task-Queues (Verarbeitung)**
• status_redis – Verfügbarkeit des Redis-Dienstes (für Task-Queue)
• status_sanity – Ergebnis der „Sanity Checks“ auf deine Dokumente

⚙️ Wichtige Voraussetzungen & Hinweise vor der Nutzung

1. 🔐 Mindestens Paperless‑ngx 2.15
   – Ältere Versionen werden nicht unterstützt.
2. 📚 Leserechte (Permissions)
   – Du brauchst Leserechte für Dokumente, Tags, Dokumenttypen und Korrespondenzpartner.
3. 🛠 Admin-Rechte empfohlen
   – Ohne Admin-Zugriff fehlen dir diagnostische Sensoren (z. B. Status: database, celery, redis etc.
4. 🧾 API-Token erstellen
   – Melde dich bei Paperless‑ngx an → Profil → API Auth Token generieren → für Integration in Home Assistant verwenden

🛠 So richtest du die Integration ein

1. Settings → Devices & Services → Add Integration
2. Suche nach Paperless‑ngx
3. Gib die URL deiner Instanz (z. B. http://192.168.178.29:8001) und den API‑Token ein.

💡 Nutzung & Integrationsmöglichkeiten

• Dashboard-Funktionalität:
  Baue ein Übersichtspanel z. B. in Lovelace mit den Inbox- und Status-Sensoren.
• Automatisierungen:
  Trigger basierend auf:
  • sensor.documents_inbox > 0
  • status_* (z. B. status_database == 'OFFLINE' für Ausfall-Warnungen)
• Performance-Monitoring:
  Überwache Speicherplatz, Index-Status und OCR-Classifier direkt in Home Assistant.
• Fehleralarmierung:
  Lasse dich benachrichtigen bei LDAP/DB-Ausfällen (z. B. status_database, status_celery).

🔔 Automation: Benachrichtigung bei neuen Dokumenten

Du willst sofort wissen, wenn neue Dokumente gescannt oder hochgeladen wurden? Mit dieser Automation bekommst du eine Push-Benachrichtigung, sobald im Paperless-Posteingang neue Dateien liegen – und das zeitverzögert nach 5 Minuten, um unnötige Alarme zu vermeiden.

alias: Paperless neue Dokumente
description: Benachrichtigung, wenn Paperless neue Dokumente bekommt
trigger:
  - platform: numeric_state
    entity_id: sensor.http_192_168_178_29_8001_dokumente_im_posteingang
    above: 0
    for:
      minutes: 5
action:
  - service: notify.smartphones
    data:
      title: Paperless hat Dokumente
      message: Sie haben Post.
      data:
        notification_icon: mdi:file-document-plus
        channel: Notfall
        importance: max
        priority: high
        ttl: 0
        color: orange
        timeout: 64800
mode: single

🧠 Erklärung:

• trigger: Sobald mehr als 0 Dokumente im Posteingang liegen und das länger als 5 Minuten, löst die Automation aus.
• action: Die Nachricht wird auf deine verbundenen Smartphones gepusht – inklusive hoher Priorität, Farbe und Icon.
• Du kannst natürlich auch weitere Aktionen ergänzen: z. B. LED-Benachrichtigungen, Sprachausgaben via TTS oder Anzeige auf einem Dashboard.

🔗 Weitere Möglichkeiten & Ideen

• 📅 Automatische Erinnerung bei Fristen (Versicherungen, Rechnungen, Steuer)
• 📠 Integration deines Netzwerkscanners als Trigger für die Paperless-OCR-Verarbeitung
• 💡 NFC-Tag-gestützte Scans: Dokumente einscannen durch einfaches Tippen mit dem Smartphone

Umsetzung im YouTube-Video

Fazit

Mit der Kombination aus Home Assistant und Paperless-NGX erschaffst du dir einen vollautomatisierten, datensouveränen Workflow. Du weißt jederzeit, ob wichtige Dokumente eingetroffen sind – ohne ständig die Weboberfläche öffnen zu müssen. Dank Home Assistant kannst du diesen Prozess auch vollständig an deinen Alltag anpassen – ganz nach deinen Regeln.

Wenn du bereits beide Tools nutzt, ist diese Integration ein absoluter No-Brainer. Wenn nicht – ist jetzt der perfekte Zeitpunkt, damit zu starten. 🚀

Interesse, aber Zeit oder Kenntnisse fehlen?

Kein Problem. Kontaktieren Sie mich und wir besprechen Ihre Anforderungen. Egal, ob geschäftlich oder privat.