Partner Login

venabo lässt sich über seine REST-API mit dem Automatisierungstool n8n verbinden. So können Sie Daten aus venabo in eigene Workflows einbinden – etwa um Adressen, Projekte oder Zeiten automatisiert weiterzuverarbeiten. Diese Anleitung führt Sie Schritt für Schritt durch die Einrichtung.

💡 Tipp: Die vollständige API-Dokumentation mit allen verfügbaren Endpunkten finden Sie unter https://IHRSERVER.venabo.cloud/api/v1/docs.

API-Benutzer anlegen

Für die Kommunikation zwischen n8n und venabo benötigen Sie einen dedizierten API-Benutzer mit den passenden Berechtigungen. Gehen Sie dazu wie folgt vor:

  1. Öffnen Sie die Benutzerverwaltung in venabo.
  2. Legen Sie einen neuen Benutzer an und wählen Sie als Benutzertyp „API“ – nur dieser Typ erzeugt automatisch einen API-Token und ist für maschinelle Zugriffe vorgesehen.
  3. Vergeben Sie die Berechtigungen für genau die Bereiche, auf die n8n später zugreifen soll (z. B. Adressen, Projekte, Zeiten). Welche Berechtigungen Sie benötigen, hängt von Ihren geplanten Workflows ab.
  4. Deaktivieren Sie im selben Dialog die Option „Content-Hash aktivieren“ – dieser Mechanismus ist für die API-Authentifizierung nicht geeignet und kann zu Zugriffsfehlern führen.
  5. Stellen Sie sicher, dass der Benutzer als „Aktiv“ markiert ist, damit venabo eingehende API-Anfragen akzeptiert.
  6. Notieren Sie den angezeigten API-Token an einem sicheren Ort – Sie benötigen ihn für die Einrichtung in n8n.

⚠️ Hinweis: Den API-Token zeigt venabo nur einmalig an. Kopieren Sie ihn direkt nach dem Anlegen des Benutzers und bewahren Sie ihn sicher auf.

Workflow in n8n anlegen

Wechseln Sie nach der Vorbereitung des API-Benutzers zu n8n und erstellen Sie einen neuen Workflow:

  1. Öffnen Sie die n8n-Oberfläche und legen Sie einen neuen, leeren Workflow an.
  2. Der Startknoten ist bereits vorhanden. Ziehen Sie per Drag-and-Drop einen neuen HTTP-Request-Knoten auf die Arbeitsfläche.
  3. Verbinden Sie den Startknoten mit dem HTTP-Request-Knoten.
  4. Öffnen Sie den HTTP-Request-Knoten per Doppelklick, um ihn zu konfigurieren.

HTTP-Request-Knoten konfigurieren

URL eintragen

Tragen Sie im Feld URL den gewünschten venabo-API-Endpunkt ein. Möchten Sie beispielsweise Adressdaten abrufen, verwenden Sie:

https://IHRSERVER.venabo.cloud/api/v1/addresses

Ersetzen Sie IHRSERVER durch die Subdomain Ihrer venabo-Instanz. Eine vollständige Liste aller verfügbaren Endpunkte finden Sie in der API-Dokumentation unter https://IHRSERVER.venabo.cloud/api/v1/docs.

Authentifizierung einrichten

venabo authentifiziert API-Anfragen ausschließlich über einen HTTP-Header. Konfigurieren Sie die Authentifizierung im Knoten wie folgt:

  1. Setzen Sie den Authentifizierungstyp auf „Generic Credential Type“.
  2. Wählen Sie innerhalb dieser Option die Variante „Header Auth“.
  3. Öffnen Sie die Credential-Verwaltung von n8n und legen Sie ein neues Credential-Set an.
  4. Definieren Sie einen Header mit dem Namen x-api-token und tragen Sie als Wert den API-Token ein, den Sie zuvor aus venabo kopiert haben.
  5. Speichern Sie das Credential – n8n übermittelt den Token ab sofort automatisch bei jeder Anfrage.

Verbindung testen

Testen Sie die Verbindung direkt nach der Konfiguration:

  1. Klicken Sie im HTTP-Request-Knoten auf „Execute Node“.
  2. n8n sendet eine Anfrage an venabo und zeigt das Ergebnis im Ausgabebereich an.
  3. Bei erfolgreicher Verbindung erscheint eine strukturierte Ausgabe der abgerufenen Daten – im Beispiel die Liste der Adressen aus venabo.

⚠️ Hinweis: Schlägt die Verbindung fehl, zeigt n8n eine Fehlermeldung an. Prüfen Sie in diesem Fall, ob der API-Token korrekt eingetragen wurde und ob der API-Benutzer in venabo über die erforderlichen Berechtigungen verfügt.

Praxisbeispiel

Szenario: Sie möchten täglich automatisch alle Adressen aus venabo abrufen und in ein Google Sheet übertragen.

Schritt Aktion Wert / Einstellung
1API-Benutzer anlegenTyp: API, Berechtigung: Adressen lesen
2n8n-Workflow erstellenTrigger: Schedule (täglich 06:00 Uhr)
3HTTP-Request-Knoten konfigurierenURL: /api/v1/addresses, Auth: Header Auth (x-api-token)
4Google-Sheets-Knoten hinzufügenDaten aus dem HTTP-Knoten in Tabelle schreiben
ErgebnisTäglich aktualisierte Adressliste im Google Sheet

Häufige Fragen

Warum erhalte ich einen „401 Unauthorized“-Fehler?

Der Fehler tritt auf, wenn der API-Token fehlt, falsch eingetragen wurde oder der API-Benutzer in venabo nicht als „Aktiv“ markiert ist. Prüfen Sie außerdem, ob die Option „Content-Hash aktivieren“ wirklich deaktiviert ist.

Welche Berechtigungen muss der API-Benutzer haben?

Das hängt von Ihrem Workflow ab. venabo prüft bei jeder API-Anfrage, ob der API-Benutzer für den jeweiligen Bereich (z. B. Adressen, Projekte, Zeiten) berechtigt ist. Vergeben Sie daher nur die Berechtigungen, die Ihr Workflow tatsächlich benötigt.

Kann ich mehrere n8n-Workflows mit demselben API-Benutzer betreiben?

Ja, das ist möglich. Achten Sie jedoch darauf, dass der API-Benutzer alle Berechtigungen besitzt, die die verschiedenen Workflows zusammen benötigen. Für mehr Übersichtlichkeit und Sicherheit empfiehlt es sich, pro Anwendungsfall einen eigenen API-Benutzer anzulegen.

Wo finde ich alle verfügbaren API-Endpunkte?

Die vollständige API-Dokumentation mit allen Endpunkten, Parametern und Beispielantworten erreichen Sie unter https://IHRSERVER.venabo.cloud/api/v1/docs – ersetzen Sie IHRSERVER durch die Subdomain Ihrer venabo-Instanz.

Zusammenfassung

Bereich Was ist zu tun?
API-Benutzer in venaboTyp „API“ wählen, Rechte vergeben, Content-Hash deaktivieren, Benutzer aktivieren
API-TokenEinmalig nach Anlage kopieren und sicher aufbewahren
n8n-WorkflowHTTP-Request-Knoten mit venabo-API-URL und Header-Auth (x-api-token) konfigurieren
Verbindungstest„Execute Node“ ausführen und Ausgabe prüfen
API-Dokumentationhttps://IHRSERVER.venabo.cloud/api/v1/docs
Inhaltsverzeichnis