Paperless-ngx
Verbindet Uella direkt mit deinem Paperless-ngx-Server. Dokumente durchsuchen, hochladen, mit Tags und Korrespondenten organisieren, als PDF herunterladen, in der Vorschau anzeigen und mehrere Dokumente in einem Rutsch bearbeiten — alles per natürlicher Sprache oder JSON-Input.
Kategorie: Integrationen & Business | Quelldatei: paperlessNgxBlock.js | Auth: Ja (API-Token)
Was kann dieser Block?
- Dokumente: Auflisten, Volltext-Suche, Detailansicht, Upload, Download, Bearbeiten und Löschen
- PDF-Vorschau im Chat: Treffer werden mit eingebettetem PDF (Data-URL) und OCR-Auszug ausgegeben
- Stammdaten: Korrespondenten, Tags, Dokument-Typen und Custom Fields anzeigen
- Batch-Operationen: Mehreren Dokumenten gleichzeitig Tags zuweisen oder einen Korrespondenten setzen
- Smart-Filter: Erkennt Korrespondenten, Typen und Tags automatisch im Freitext (z. B. "Rechnungen von Swisscom aus 2025") und setzt die passenden Paperless-Filter
- Hybrid-Input: Funktioniert mit Freitext-Fragen, dem reinen Operations-Namen (
list_tags) oder einem strukturierten JSON-Objekt
Was brauche ich dafür?
- Eine erreichbare Paperless-ngx-Instanz (Self-Hosted oder gehostet, z. B.
https://paperless.deine-firma.ch) - Einen API-Token aus deinem Paperless-Profil
So findest du den Token:
- Melde dich in deinem Paperless-ngx an
- Klick oben rechts auf dein Profil → Einstellungen
- Wechsle zu API-Token und klick auf Token erstellen (bzw. den bestehenden kopieren)
- Trage Base-URL und API-Token in der Block-Konfiguration ein
Wichtig: Der Token entspricht den Rechten des erzeugenden Benutzers. Wer keine Dokumente löschen darf, kann sie auch über Uella nicht löschen.
So benutzt du den Block
Dokumente per Volltext suchen
Prompt: "Suche in Paperless nach Rechnungen von Swisscom"
Ergebnis: Trefferliste als Tabelle mit klickbarem Titel (öffnet Paperless direkt), Korrespondent, Datum und einem kurzen OCR-Auszug rund um die Trefferstelle.
Einzelnes Dokument öffnen
Prompt: "Zeige mir Dokument 160"
Ergebnis: Detailansicht mit Metadaten (Titel, Korrespondent, Typ, Tags, Datum), eingebetteter PDF-Vorschau und ausklappbarem OCR-Volltext.
Natürlichsprachliche Frage zum Archiv
Prompt: "Wann wurde mein Fahrrad gestohlen?"
Ergebnis: Der Block bereinigt die Frage, baut daraus einen sinnvollen Such-Query und liefert die passenden Dokumente inkl. Auszug — perfekt für RAG-ähnliche Fragen ans eigene Archiv.
Neues Dokument hochladen
Prompt (JSON): {"operation":"upload_document","fileUrl":"https://example.com/rechnung.pdf","title":"Rechnung Swisscom April 2026","correspondentId":4,"tagIds":"3,7"}
Ergebnis: Datei wird vom Block heruntergeladen, an Paperless gepostet (OCR und Klassifizierung laufen asynchron im Hintergrund) und du bekommst die Task-ID zurück.
Tags zu mehreren Dokumenten hinzufügen
Prompt (JSON): {"operation":"bulk_add_tag","bulkIds":"42,43,44","tagIds":"12"}
Ergebnis: Tag 12 wird auf alle drei Dokumente angewendet.
Korrespondent für eine Gruppe von Dokumenten setzen
Prompt (JSON): {"operation":"bulk_set_correspondent","bulkIds":"42,43,44","correspondentId":7}
Ergebnis: Alle drei Dokumente sind dem Korrespondenten 7 zugeordnet.
Alle Operationen im Überblick
Dokumente (7 Operationen)
| Operation | Was passiert | Beispiel-Prompt |
|---|---|---|
list_documents | Dokumente auflisten (mit optionalen Filtern) | "Zeige die neuesten 10 Dokumente" |
search_documents | Volltext-Suche über das gesamte Archiv | "Suche nach Mietvertrag Zürich" |
get_document | Einzelnes Dokument per ID anzeigen | "Zeige Dokument 42" |
download_document | Dokument als Base64 (≤ 10 MB) oder Download-URL zurückgeben | {"operation":"download_document","documentId":42} |
upload_document | Datei per URL oder Base64 hochladen, optional mit Metadaten | siehe Beispiel oben |
update_document | Titel, Korrespondent, Typ oder Tags ändern | {"operation":"update_document","documentId":42,"title":"Neuer Titel"} |
delete_document | Dokument löschen | "Lösche Dokument 42" |
Stammdaten (4 Operationen)
| Operation | Was passiert | Beispiel-Prompt |
|---|---|---|
list_correspondents | Alle Korrespondenten anzeigen | "Welche Korrespondenten gibt es in Paperless?" |
list_tags | Alle Tags inkl. Farben anzeigen | "Liste alle Tags" |
list_document_types | Alle Dokument-Typen anzeigen | "Welche Dokument-Typen sind hinterlegt?" |
list_custom_fields | Alle Custom Fields anzeigen | list_custom_fields |
Batch (2 Operationen)
| Operation | Was passiert | Beispiel-Prompt |
|---|---|---|
bulk_add_tag | Tag(s) zu mehreren Dokumenten hinzufügen | {"operation":"bulk_add_tag","bulkIds":"42,43","tagIds":"12"} |
bulk_set_correspondent | Korrespondent für mehrere Dokumente setzen | {"operation":"bulk_set_correspondent","bulkIds":"42,43","correspondentId":7} |
Smart-Features
- Auto-Operation: Wenn du keine Operation setzt, erkennt der Block aus dem Freitext, ob es um Suche, Liste, Upload, Update oder Stammdaten geht.
- Auto-ID: Formulierungen wie "Dokument 160", "id 160", "#160" oder "öffne 42" werden erkannt — der Block springt direkt auf
get_document. - Auto-Filter: Korrespondenten-, Typ- und Tag-Namen aus deiner Anfrage werden automatisch in passende Paperless-Filter übersetzt; Filter werden bei 0 Treffern schrittweise gelockert.
- Titel-Lookup: Sieht der Input wie ein Dokumenten-Titel aus (lang, mit Zahlen/Eigennamen), sucht der Block zuerst per
title__icontains— robust gegen kleine Abweichungen. - OCR-Auszug: Bei mehreren Treffern wird pro Dokument ein Auszug rund um die Treffer-Stelle gebaut, damit du sofort siehst, warum ein Dokument relevant ist.
Häufige Probleme und Lösungen
| Problem | Lösung |
|---|---|
| 401 Unauthorized | API-Token ungültig oder abgelaufen — neuen Token im Paperless-Profil erstellen |
| "Base-URL fehlt" | baseUrl im Block-Config setzen, inkl. https:// und ohne Trailing-Slash |
| Keine Treffer trotz vorhandenem Dokument | Filter werden ggf. zu eng erkannt — Frage spezifischer formulieren oder Filter-Felder im Block leeren |
| Upload schlägt fehl (HTTP 400) | Dateigrösse und MIME-Type prüfen; Paperless akzeptiert v. a. PDF, JPG, PNG, TIFF |
| "Datei zu gross für Vorschau" | Dokumente > 5 MB werden nicht als Inline-PDF eingebettet — der Block zeigt dann Thumbnail + Direkt-Link |
| Download liefert keinen Base64 | Dateien > 10 MB liefern nur Metadaten + download_url; nutze die URL mit Authorization-Header Token <apiToken> |
| Bulk-Tagging fügt nur einen Tag hinzu | Paperless erwartet einen Tag pro Bulk-Request — der Block macht das automatisch in mehreren Calls, gib einfach mehrere Tag-IDs an |
Weiterführende Links
- Paperless-ngx Projekt: https://docs.paperless-ngx.com/
- API-Dokumentation: https://docs.paperless-ngx.com/api/
- Token-Verwaltung: Paperless → Profil (oben rechts) → API-Token
Technische Details
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
operation | Select | Nein* | 13 Operationen; bei Freitext-Input wird automatisch erkannt |
baseUrl | URL | Ja | Paperless-Basis-URL (z. B. https://paperless.firma.ch) |
apiToken | Password | Ja | API-Token aus dem Paperless-Profil |
query | Text | Bedingt | Volltext-Suchbegriff für list_documents / search_documents |
limit | Number | Nein | Max. Treffer bei Listen-Operationen (Standard: 25) |
ordering | Text | Nein | Sortierung, z. B. -created oder title |
documentId | Text | Bedingt | ID für get, download, update, delete |
title, correspondentId, documentTypeId, tagIds | Text/Number | Bedingt | Metadaten beim Upload / Update |
fileUrl, fileBase64, fileName | URL / Text | Bedingt | Datei-Quelle und Dateiname beim Upload |
tagIdsFilter, correspondentIdFilter | Text / Number | Nein | Server-seitige Filter bei list_documents |
bulkIds | Text | Bedingt | Komma-separierte Dokument-IDs für Batch-Operationen |
*Wenn keine Operation gesetzt ist, zeigt der Block eine Hilfe-Tabelle mit allen verfügbaren Operationen oder versucht aus dem Freitext-Input die passende Operation abzuleiten.