n8n-nodes-mh-api

n8n Community Node für die MeinHandwerker API Integration. Automatisieren Sie Ihre Handwerker-Workflows mit n8n!

📋 Inhaltsverzeichnis

• Installation
• Schnellstart
• Verfügbare Operationen
• Beispiel-Workflows
• Support

🚀 Installation

Variante A: Installation über n8n UI (empfohlen)

Die einfachste Methode für Ihre Kunden:

1. Öffnen Sie n8n
2. Gehen Sie zu Settings → Community Nodes
3. Klicken Sie auf Install
4. Geben Sie ein: n8n-nodes-mh-api
5. Klicken Sie auf Install
6. Fertig! 🎉

Variante B: Manuelle Installation

# In Ihrem n8n-Verzeichnis
npm install n8n-nodes-mh-api

Variante C: Plug & Play Installation

Noch einfacher - mit vorkonfiguriertem Workflow:

1. Laden Sie das MeinHandwerker Startpaket herunter
2. In n8n: Workflows → Import from File
3. Wählen Sie die heruntergeladene .json Datei
4. Tragen Sie Ihre API-Zugangsdaten ein (siehe unten)
5. Klicken Sie auf Activate ✅

Fertig! Der Workflow ist sofort einsatzbereit.

⚙️ Konfiguration

API-Zugangsdaten einrichten

Nach der Installation müssen Sie Ihre MeinH andwerker API-Zugangsdaten hinterlegen:

1. Klicken Sie auf einen MH API Node in Ihrem Workflow

2. Bei Credentials auf Create New

3. Füllen Sie die Felder aus:

   • API URL: Ihre MeinHandwerker-URL (z.B. https://ihre-firma.mein-handwerker-app.de)
   • Client ID: Ihre Client-ID (finden Sie in MeinHandwerker unter Einstellungen → API)
   • Client Password: Ihr API-Passwort

4. Klicken Sie auf Save

💡 Tipp: Die Zugangsdaten werden sicher verschlüsselt gespeichert und können in allen Workflows wiederverwendet werden.

🎯 Schnellstart

Erster Workflow in 2 Minuten

1. Neuen Workflow erstellen

   • In n8n auf New Workflow klicken

2. MH API Node hinzufügen

   • Suchen Sie nach "MH API"
   • Ziehen Sie den Node in Ihren Workflow

3. Operation auswählen

   • Resource: Employee
   • Operation: Get All
   • Credentials auswählen

4. Workflow testen

   • Auf Execute Node klicken
   • Sie sehen nun alle Ihre Mitarbeiter! 🎉

📚 Verfügbare Operationen

🔔 Trigger (Automatische Auslösung)

NEU in v1.1.0: Der MeinHandwerker-API Trigger Node ermöglicht automatische Workflow-Auslösungen!

• Zeiterfassung geprüft - Wenn eine Zeiterfassung geprüft wurde
• Zeiterfassung erstellt - Wenn eine neue Zeiterfassung erstellt wurde
• Sondertag eingetragen - Wenn ein Sondertag (Krankheit, etc.) eingetragen wurde
• Urlaub beantragt - Wenn ein Urlaub beantragt wurde
• Mitarbeiter eingeplant - Wenn ein Mitarbeiter eingeplant wurde
• Projekt eingeplant - Wenn ein Projekt eingeplant wurde
• Rapport erstellt - Wenn ein Rapport erstellt wurde
• Bestellung erstellt - Wenn eine Bestellung erstellt wurde
• Produkt geändert - Wenn ein Produkt geändert wurde
• Projektstatus geändert - Wenn der Status eines Projekts geändert wurde
• Dokument hochgeladen - Wenn ein Dokument zu einem Projekt hochgeladen wurde

💡 Tipp: Trigger verwenden Polling (alle 60 Sekunden). Events der letzten 7 Tage werden abgerufen.

👥 Mitarbeiter (Employee)

• Get All - Alle Mitarbeiter abrufen
• Create - Neuen Mitarbeiter anlegen
• Archive - Mitarbeiter archivieren

👤 Kunden (Customer)

• Get All - Alle Kunden abrufen
• Create - Neuen Kunden anlegen
• Update - Kundendaten aktualisieren

🏗️ Projekte (Construction)

• Get All - Alle Projekte abrufen
• Create - Neues Projekt anlegen
• Update - Projekt aktualisieren
• Update Status - Projektstatus ändern

⏰ Zeiterfassung (Time Entry)

• Get - Zeiteinträge für einen Monat abrufen
• Create - Neue Zeitperiode erstellen

📄 Dokumente (Document)

• Upload - Dokument zu Projekt hochladen

✅ Aufgaben (Task)

• Create - Neue Aufgabe erstellen

📅 Termine (Schedule)

• Create - Neuen Termin erstellen
• Get Employee Status - Mitarbeiterstatus für bestimmtes Datum abrufen

🎨 Beispiel-Workflows

Workflow 1: Neues Projekt → Mail an Kunde

Ziel: Wenn ein neues Projekt angelegt wird, automatisch eine E-Mail an den Kunden senden.

MH API Trigger: Projekt eingeplant
  → E-Mail Node: Benachrichtigung an Projektleiter

✨ NEU: Nutzen Sie den Trigger-Node für Echtzeit-Benachrichtigungen statt Cron + Filter!

📥 Workflow herunterladen

Workflow 2: Zeiterfassung → Excel Export

Ziel: Bei geprüften Zeiterfassungen automatisch nach Excel exportieren.

MH API Trigger: Zeiterfassung geprüft
  → Spreadsheet: Daten in Google Sheets eintragen
  → E-Mail: Benachrichtigung an Buchhaltung

📥 Workflow herunterladen

Workflow 3: Dokument Upload → Benachrichtigung

Ziel: Bei neuen Dokumenten Push-Benachrichtigung senden.

MH API Trigger: Dokument hochgeladen
  → Telegram/Slack: Benachrichtigung senden

✨ NEU: Trigger-Node nutzt Polling für automatische Benachrichtigungen!

📥 Workflow herunterladen

🔗 Dashboard-Integration

"Mit n8n verbinden"-Button

Sie können in Ihrem MeinHandwerker-Dashboard einen Button einbauen, der Ihren Kunden die Installation noch einfacher macht.

Implementierung siehe: application/views/admin/api_interface_view.php

Der Button öffnet n8n mit einem vorkonfigurierten Workflow:

https://app.n8n.cloud/?import=https://ihre-domain.de/n8n/workflows/meinhandwerker_startpaket.json

📖 Detaillierte Dokumentation

Beispiel: Mitarbeiter erstellen

// Node-Konfiguration
Resource: Employee
Operation: Create

// Felder:
Email: [email protected]
First Name: Max
Last Name: Mustermann

Rückgabe:

{
  "success": true,
  "employee_id": 123,
  "password": "xyz789",
  "message": "Mitarbeiter erfolgreich erstellt"
}

Beispiel: Projekt-Status ändern

Resource: Construction
Operation: Update Status

// Felder:
Construction ID: 456
Status Name: "In Arbeit"

🛠️ Tipps für Handwerkerfreundlichkeit

✅ Einfache Sprache

• Alle Beschreibungen sind auf Deutsch
• Keine Fachbegriffe - verständlich für jeden

✅ Sinnvolle Standardwerte

• API-URL wird vorausgefüllt
• Häufig genutzte Felder haben Beispielwerte

✅ Visuelles Design

• Erkennbares MH-Logo als Icon
• Konsistente Farbgebung

✅ Vorlagen inklusive

• 3 fertige Workflows zum Loslegen
• Keine Programmierung nötig

🆘 Support

Probleme oder Fragen?

1. Dokumentation: https://doku.mein-handwerker-app.de
2. E-Mail: [email protected]

Häufige Fehler

"Unauthorized" / 401 Fehler

→ Überprüfen Sie Client ID und Password in den Credentials

"Construction not found" / 406 Fehler

→ Die angegebene ID existiert nicht in Ihrem System

Node wird nicht gefunden

→ Stellen Sie sicher, dass das Paket korrekt installiert wurde (siehe Installation)

🔄 Updates

Das Paket wird regelmäßig aktualisiert. Sie werden in n8n automatisch über neue Versionen informiert.

Changelog: CHANGELOG.md

📄 Lizenz

MIT License - Siehe LICENSE

👨‍💻 Entwicklung

Möchten Sie zur Entwicklung beitragen? Großartig!

# Repository klonen
git clone https://github.com/yourusername/n8n-nodes-mh-api.git

# Dependencies installieren
cd n8n-nodes-mh-api
npm install

# TypeScript kompilieren
npm run build

# In n8n testen
npm link

🙏 Credits

Entwickelt vom MeinHandwerker Team für die Handwerker-Community.

Viel Erfolg mit Ihren Automatisierungen! 🚀

Bei Fragen oder Feedback: [email protected]