n8n Nodes für Community API DOC Server

Dieses Paket stellt n8n-Nodes für die Integration mit dem Community API DOC Server bereit.

Wichtig: Zur Nutzung der Nodes ist ein Account in der AI Community (https://ki-communities.de) zwingend notwendig, da dadurch der Zugang auf dem DOC Server erstellt wird.

Installation

In n8n Settings → Community Nodes:

@marcmeese/n8n-nodes-communityapi-doc-client

Konfiguration

Authentifizierung einrichten

1. Gehe zu n8n → Credentials → New
2. Wähle "CommunityAPI - DOC Server"
3. Gib deinen API-Key ein
4. Teste die Verbindung

Verfügbare Nodes

📋 Basis-Funktionen

Get User Info

Ruft Benutzerinformationen vom DOC Server ab.

Parameter: Keine
Output: Benutzerinformationen als JSON

Get Job

Ruft Details zu einem spezifischen Job ab.

Parameter:

• Job ID (string): Die ID des abzufragenden Jobs

Output: Job-Details als JSON

Download Job

Lädt die Ergebnisdateien eines abgeschlossenen Jobs herunter.

Parameter:

• Job ID (string): ID des herunterzuladenden Jobs
• Output Folder (string): Zielordner für Downloads
• Basename (string, optional): Basis-Dateiname
• Keep Filenames (boolean): Original-Dateinamen beibehalten

Output: Liste der heruntergeladenen Dateipfade

📤 Datei-Upload

Upload File

Lädt eine einzelne lokale Datei auf den DOC Server hoch.

Parameter:

• Local File Path (string): Pfad zur lokalen Datei

Funktionsweise:

1. Fordert eine Presigned URL vom Server an
2. Lädt die Datei direkt auf den Storage hoch
3. Gibt die File-ID zurück

Output:

{
	"file_id": "uuid-der-datei",
	"filename": "original-dateiname.pdf"
}

Beispiel:

/home/user/documents/report.pdf → file_id: "abc-123-def"

Upload Files (Batch)

Lädt mehrere lokale Dateien parallel auf den DOC Server hoch.

Parameter:

• Local File Paths (string[]): Pfade zu den lokalen Dateien

Funktionsweise:

1. Fordert Batch Presigned URLs für alle Dateien an
2. Lädt alle Dateien parallel hoch (schneller als einzeln)
3. Gibt alle File-IDs zurück

Output:

{
	"presigned": [
		{
			"file_id": "uuid-1",
			"filename": "file1.pdf"
		},
		{
			"file_id": "uuid-2",
			"filename": "file2.docx"
		}
	]
}

Beispiel:

["/path/to/file1.pdf", "/path/to/file2.docx"] →
{presigned: [{file_id: "abc-123"}, {file_id: "def-456"}]}

📄 Dokument-Verarbeitung

Document Converter

Konvertiert Dokumente zwischen verschiedenen Formaten.

Parameter:

• Input Document Paths (string[]): Pfade zu Dokumenten (UUID, URL oder lokaler Pfad)
• Target Format (dropdown): Zielformat
• Callback URL (string, optional): URL für Callback
• Callback Payload (JSON, optional): Zusätzliche Daten

Unterstützte Eingabe-Formate:

• Office-Dokumente: doc, docx, ppt, pptx, xls, xlsx, odt, rtf
• Text/Markup: txt, md, html, htm
• Daten: json, xml, yaml, yml, csv
• Config/Logs: log, ini, cfg, properties
• PDF: pdf

Unterstützte Ausgabe-Formate:

Office:

• PDF
• Word: DOCX, DOC
• PowerPoint: PPTX, PPT
• Excel: XLSX, XLS, CSV
• OpenDocument: ODT
• Rich Text: RTF

Text/Markup:

• Plain Text: TXT
• Markdown: MD
• Web: HTML, HTM

Daten:

• JSON
• XML
• YAML, YML

Config:

• LOG
• INI
• CFG
• Properties

Bilder (aus PDF):

• PNG
• JPG, JPEG

Intelligente Eingabe-Verarbeitung:

Der Document Converter akzeptiert verschiedene Input-Formate:

1. File-ID (UUID): Von vorherigem Upload-Node

   "abc-123-def-456"

2. HTTP(S) URL: Direkter Download

   "https://example.com/document.pdf"

3. Lokaler Pfad: Automatischer Upload

   "/home/user/documents/report.docx"

Workflow-Beispiele:

Beispiel 1: Lokale Datei konvertieren
[Local File] → DocumentConverter → DownloadJob

Beispiel 2: Mit Upload-Node
UploadFile → DocumentConverter(file_id) → DownloadJob

Beispiel 3: URL direkt konvertieren
DocumentConverter(https://...) → DownloadJob

Beispiel 4: Batch-Verarbeitung
UploadFiles → DocumentConverter(multiple file_ids) → DownloadJob

Output:

{
	"job_id": "job-uuid",
	"status": "pending",
	"created_at": "2026-01-22T12:00:00Z"
}

Workflow-Beispiele

Beispiel 1: Einfache Konvertierung

1. Upload File (/path/to/document.docx)
   ↓ {file_id: "abc-123"}
2. Document Converter (file_id: "abc-123", target: "pdf")
   ↓ {job_id: "job-456"}
3. Download Job (job_id: "job-456", output: "/downloads/")
   ↓ ["/downloads/document.pdf"]

Beispiel 2: Batch-Konvertierung

1. Upload Files ([file1.doc, file2.docx, file3.txt])
   ↓ {presigned: [{file_id: "a"}, {file_id: "b"}, {file_id: "c"}]}
2. Document Converter (file_ids: ["a", "b", "c"], target: "pdf")
   ↓ {job_id: "job-789"}
3. Download Job (job_id: "job-789")
   ↓ [file1.pdf, file2.pdf, file3.pdf]

Beispiel 3: URL-basierte Konvertierung

1. Document Converter (input: "https://example.com/report.xlsx", target: "csv")
   ↓ {job_id: "job-xyz"}
2. Download Job (job_id: "job-xyz")
   ↓ [report.csv]

Beispiel 4: Mit Callback

1. Upload File + Document Converter (mit callback_url)
   ↓ {job_id: "job-abc"}
2. [Job läuft im Hintergrund]
3. Webhook empfängt Callback mit Ergebnis

Entwicklung

Build-Prozess

# Dependencies installieren
npm install

# TypeScript kompilieren + Icons kopieren
npm run build

# Development Mode (Watch)
npm run dev

Projektstruktur

src/
├── config/
│   └── endpoints.ts
├── credentials/
│   └── CommunityAPIDOCServer.credentials.ts
├── nodes/
│   └── CommunityAPIDOCServer/
│       ├── GetUserInfo/
│       ├── GetJob/
│       ├── DownloadJob/
│       ├── UploadFile/
│       ├── UploadFiles/
│       └── DocumentConverter/
├── utils/
│   ├── apiRequests.ts
│   ├── fileUploads.ts
│   └── inputProcessing.ts
└── index.ts

API-Endpunkte

• Auth: https://auth.marcmeese.de
• DOC Server: https://doc.marcmeese.de (Note: In der aktuellen Implementierung wird ai.marcmeese.de verwendet)

Fehlerbehebung

Häufige Probleme

1. Authentication Failed

   • API-Key im Account überprüfen
   • Credentials in n8n neu erstellen

2. File Not Found (Upload)

   • Absolute Pfade verwenden
   • Datei-Berechtigungen prüfen
   • Bei Windows: Pfade mit / statt \

3. Unsupported File Format

   • Liste der unterstützten Formate prüfen
   • Dateiendung muss korrekt sein

4. Upload Failed

   • Datei-Größe prüfen (Max. Limit beachten)
   • Internet-Verbindung prüfen
   • Presigned URL könnte abgelaufen sein (läuft automatisch ab)

5. Conversion Failed

   • Eingabe-Format wird unterstützt?
   • Ziel-Format für diese Eingabe möglich?
   • Bei PDF → Bild: Nur erste Seite wird konvertiert

Debug-Modus

Setze n8n in den Debug-Modus für detaillierte Logs:

export N8N_LOG_LEVEL=debug
n8n start

Callback-System

Document Converter unterstützt Callbacks für asynchrone Verarbeitung:

Callback URL: Webhook-URL, die nach Job-Abschluss aufgerufen wird
Callback Payload: Benutzerdefinierte Daten, die mit dem Callback zurückgegeben werden

Beispiel-Payload:

{
	"parameters": [
		{ "key": "workflow_id", "value": "12345" },
		{ "key": "user_email", "value": "[email protected]" }
	]
}

Callback-Response:

{
	"job_id": "job-uuid",
	"status": "completed",
	"result_files": ["file1.pdf", "file2.pdf"],
	"callback_payload": {
		"workflow_id": "12345",
		"user_email": "[email protected]"
	}
}

Best Practices

1. Batch-Upload nutzen: Für mehrere Dateien immer Upload Files statt mehrfach Upload File
2. File-IDs wiederverwenden: Upload einmal, konvertiere mehrfach
3. Callbacks verwenden: Bei großen Dateien/langen Jobs
4. Error Handling: Immer prüfen, ob Upload/Conversion erfolgreich war
5. Temp-Dateien löschen: Nach Download die lokalen Temp-Dateien aufräumen

Support

Bei Problemen oder Fragen:

1. Überprüfe die Logs in n8n
2. Teste die API-Endpoints manuell mit curl/Postman
3. Kontaktiere den Support über https://ki-communities.de

Lizenz

MIT - Siehe LICENSE.md für Details.