Mein Paperless-ngx-Archiv ist auf 694 Dokumente angewachsen – Rechnungen, Verträge, Krankenkassen-Belege, Steuerformulare. Bislang lebte das Ganze in einer separaten Welt. Mit der offiziellen Paperless-ngx-Integration in Home Assistant 2025.6 ändert sich das: Paperless wird zu einer normalen Datenquelle in HA, mit Sensoren, Events und Auslösern. Das öffnet die Tür für Automationen, die das Papier-Chaos in den Griff bekommen – und die mit anderen Smart-Home-Bausteinen vernetzen.
Worum es geht: Sensoren statt Suchen
Die Paperless-ngx-Integration legt nach der Einrichtung mehrere Sensoren an. Der wichtigste ist sensor.paperless_gesamt, der die Gesamtanzahl der Dokumente zeigt. Bei mir steht der auf 694. Dazu kommen Sensoren für offene Aufgaben (Inbox-Tag), Speicherauslastung, Letztes-Dokument-Datum sowie ein Update-Sensor, der meldet, wenn eine neue Paperless-Version verfügbar ist. Wer Admin-Rechte im Paperless vergibt, bekommt zusätzlich diagnostische Sensoren für Worker-Status und Queue-Länge.
Voraussetzungen sind Paperless-ngx ab Version 2.15 und ein API-Token mit Leserechten auf Dokumente, Tags, Dokumenttypen und Korrespondenten. Das Token erstellt man im Paperless-Frontend unter «Mein Profil → API-Token».
Schritt für Schritt: Integration einrichten
In Home Assistant unter Einstellungen → Geräte & Dienste → Integration hinzufügen «Paperless-ngx» auswählen. Im Setup-Dialog werden URL der Paperless-Instanz und der API-Token abgefragt. Mehr braucht es nicht – die Sensoren erscheinen automatisch.
# configuration.yaml – optionaler manueller Sensor als Backup
# (nur falls die Integration einmal hakt)
sensor:
- platform: rest
name: paperless_inbox
resource: https://paperless.local/api/documents/?tags__id=2
headers:
Authorization: "Token DEIN_TOKEN_HIER"
Accept: "application/json"
value_template: "{{ value_json.count }}"
scan_interval: 600
Das obige Snippet ist nützlich, wenn die offizielle Integration die «Inbox»-Tag-Logik nicht so abbildet, wie man sich das wünscht. Tag-ID 2 muss durch die eigene ID des Inbox-Tags ersetzt werden.
Automation 1: Hue-Lampe als Inbox-Lichtsignal
Sobald ein neues Dokument im Paperless-Posteingang landet, soll die Tolomeo-Leselampe orange aufblinken – als unaufdringlicher Hinweis, dass etwas zu sichten ist.
# automations.yaml
- alias: Paperless Inbox – Lichtsignal
trigger:
- platform: state
entity_id: sensor.paperless_inbox
condition:
- condition: template
value_template: >
{{ trigger.from_state.state | int(0) < trigger.to_state.state | int(0) }}
- condition: time
after: "08:00:00"
before: "21:00:00"
action:
- service: light.turn_on
target:
entity_id: light.tolomeo
data:
color_name: orange
brightness_pct: 60
- delay: "00:00:05"
- service: light.turn_off
target:
entity_id: light.tolomeo
Die Template-Bedingung prüft, ob der Wert wirklich gestiegen ist – damit das Lichtsignal nicht auch beim Verschieben aus dem Inbox auslöst. Die Zeitbedingung verhindert nächtliches Blinken.
Automation 2: Push-Benachrichtigung für Rechnungen
Spannender wird es, wenn man neue Dokumente nach Korrespondent filtert. Beispiel: Sobald ein Dokument vom Korrespondent «Krankenkasse» auftaucht, kommt eine Push-Nachricht aufs iPhone mit Link direkt zur Paperless-Vorschau.
- alias: Paperless – neue Krankenkassen-Rechnung
trigger:
- platform: event
event_type: paperless_document_added
event_data:
correspondent: Krankenkasse
action:
- service: notify.mobile_app_iphone_17_pro
data:
title: "Neue Krankenkassen-Rechnung"
message: "{{ trigger.event.data.title }}"
data:
url: "https://paperless.local/documents/{{ trigger.event.data.id }}/"
Das paperless_document_added-Event wird von der HA-Integration ausgelöst, sobald ein neues Dokument indexiert wurde. Damit fällt das aufwändige Polling weg.
Automation 3: Wöchentlicher Backup-Reminder
Ein letzter Klassiker: Wer Paperless-ngx selbst hostet, sollte regelmässig backupen. Der Update-Sensor und ein einfaches Cron-Trigger zusammen ergeben einen wöchentlichen Hinweis im Mobile-App-Banner – inklusive der Information, wie viele neue Dokumente seit dem letzten Backup dazugekommen sind. Das spart Diskussionen mit dem inneren Schweinehund.
Fazit
Mit der nativen Paperless-ngx-Integration wird das Dokumenten-Archiv endlich Teil des Smart Homes. Drei Automationen reichen, um den Workflow spürbar zu beschleunigen: Lichtsignal bei neuem Posteingang, gezielte Push-Nachrichten pro Korrespondent und ein Backup-Reminder. Wer schon ein bestehendes Setup mit Sensoren für andere Bereiche hat – etwa mein Setup mit Shelly Plus 1 PM zum Energie-Monitoring – kann Paperless mit derselben Logik in Dashboards einbauen. Die Mushroom-Card auf dem Wohnzimmer-Tablet zeigt jetzt zwei Zahlen nebeneinander: Stromverbrauch heute und Inbox-Dokumente. Das fühlt sich an wie eine Mini-Mission-Control – nur ohne Mission.