Mit n8n die WZ 2025 API abfragen: Batch-Klassifizierung ohne eigene Software

Warum n8n für die WZ-Klassifizierung?

n8n ist ein Workflow-Automatisierungstool. Es lässt sich selbst hosten, was in Compliance-Umgebungen oft Voraussetzung ist, oder als Cloud-Dienst nutzen. Ein Workflow besteht aus Nodes für Datenquelle, HTTP-Request und Ziel und läuft auf Knopfdruck, per Zeitplan oder Webhook. Die typischen Aufgaben bei der Branchenklassifizierung sind Stapelarbeit: hunderte Bestandskunden auf WZ 2025 heben, Onboarding-Listen nachklassifizieren oder im Rezertifizierungslauf die Branchencodes aktualisieren. Solche Läufe erledigt n8n ohne eigenes Integrationsprojekt.

Voraussetzung: API-Key aus dem Abo

Nach Abschluss des Flat-300-Abos (39 €/Monat, 300 Abfragen) erhalten Sie Ihren persönlichen API-Key automatisch per E-Mail. Er beginnt mit wz_ und wird aus Sicherheitsgründen nur einmal übermittelt. Behandeln Sie ihn wie ein Passwort. Er gehört in den Credential-Store von n8n, nicht in den Workflow selbst und nicht in geteilte Exporte.

Schritt 1: API-Key als Credential hinterlegen

Legen Sie in n8n unter Credentials → Add credential ein neues Credential vom Typ „Header Auth" an:

Damit liegt der Key verschlüsselt im Credential-Store von n8n. Jeder HTTP-Request-Node referenziert ihn per Auswahl, und der Klartext taucht nicht im Workflow-JSON auf.

Schritt 2: HTTP-Request-Node konfigurieren

Fügen Sie einen HTTP-Request-Node hinzu und konfigurieren Sie ihn so:

• Method: POST
• URL: https://www.wz2025.io/api/v1
• Authentication: Generic Credential Type → Header Auth → Ihr Credential aus Schritt 1
• Body Content Type: JSON

Als Body senden Sie pro Datensatz die Unternehmensbeschreibung. Eine Expression liest sie direkt aus dem Feld Ihrer Quelle, hier aus der Spalte beschreibung:

{
  "query": "{{ $json.beschreibung }}"
}

Für die Übersetzung vorhandener WZ-2008-Codes (Details: WZ 2008 auf WZ 2025 umschlüsseln) lautet der Body stattdessen:

{
  "action": "translate",
  "query": "{{ $json.wz2008 }}"
}

Die Antwort enthält den Code in drei Feldern. Für das spätere Mapping nutzen Sie code und text:

{
  "result": "18.14.0 - Binden von Druckerzeugnissen und damit verbundene Dienstleistungen",
  "code": "18.14.0",
  "text": "Binden von Druckerzeugnissen und damit verbundene Dienstleistungen",
  "usage": { "used": 42, "included": 300, "hardLimit": 330 }
}

Schritt 3: Große Stapel im Loop verarbeiten

Für eine Liste mit hunderten Einträgen hängen Sie vor den HTTP-Request einen „Loop Over Items"-Node (Split in Batches). Mit Batch-Größe 1 läuft die Verarbeitung kontrolliert sequenziell. Alternativ bietet der HTTP-Request-Node unter Options → Batching eine eingebaute Drosselung mit Items pro Batch und Intervall. Der komplette Workflow in der Übersicht:

Ihr Monatskontingent steht in jeder API-Antwort im Feld usage: used zählt den Verbrauch, included und hardLimit nennen die Grenzen Ihres Tarifs. Ein IF-Node prüft usage.used und beendet den Workflow, bevor die API mit HTTP 429 antwortet. Fehlerfälle wie HTTP 422 (keine eindeutige Klassifizierung möglich) leiten Sie über die Fehlerausgabe des HTTP-Nodes in eine separate Nachprüfliste, statt den Lauf abzubrechen. Für größere Bestände gibt es das Professionell-Paket mit individuellem Kontingent.

Schritt 4: Ergebnisse in CSV oder Datenbank schreiben

Nach dem HTTP-Request übernimmt ein Set-Node („Edit Fields") die Felder code und text aus der Antwort und kombiniert sie mit den Stammdaten (z. B. Kundennummer). Danach haben Sie zwei bewährte Wege:

• CSV-Datei: Ein „Convert to File"-Node erzeugt aus allen Items eine CSV, zum Beispiel mit den Spalten kundennr;beschreibung;code;text. Die Datei laden Sie herunter oder schreiben sie per Write-File-Node ins Zielverzeichnis.
• Datenbank: Der Postgres- bzw. MySQL-Node schreibt die Ergebnisse per Insert in Ihre Stammdatentabelle. Ein Update über die Kundennummer macht den Lauf wiederholbar, ohne Duplikate zu erzeugen.

Aus einer Liste mit Beschreibungen wird so eine Liste mit gültigen WZ-2025-Codes. Der Lauf lässt sich jederzeit wiederholen und für die Dokumentation archivieren. Wie die Klassifizierung inhaltlich funktioniert, beschreibt der Artikel WZ-Code ermitteln. Alle Details zur API stehen auf der Startseite der WZ 2025 API. Wer statt des Batch-Laufs einen Chat-Agenten mit Werkzeugzugriff möchte, nutzt den WZ 2025 MCP-Server mit dem MCP-Client-Node von n8n.

Häufige Fragen zu n8n und der WZ 2025 API

Brauche ich Programmierkenntnisse, um die WZ 2025 API mit n8n zu nutzen?

Nein. Der komplette Workflow besteht aus Standard-Nodes: Daten einlesen, HTTP-Request an die API, Ergebnis in CSV oder Datenbank schreiben. Sie konfigurieren einmalig die JSON-Struktur des Request-Bodys, mehr nicht.

Welchen Credential-Typ muss ich in n8n nutzen?

„Header Auth", mit x-api-key als Name und Ihrem API-Key als Wert. So liegt der Key verschlüsselt im Credential-Store von n8n und taucht nicht im Workflow-JSON auf. Das ist wichtig, sobald Workflows exportiert oder geteilt werden.

Wie viele Anfragen kann ich im Batch verarbeiten?

So viele, wie Ihr Tarif-Kontingent zulässt. Jede API-Antwort enthält ein usage-Feld mit dem aktuellen Verbrauch (used) und den Grenzen Ihres Tarifs (included und hardLimit). Ist das Kontingent aufgebraucht, antwortet die API mit HTTP 429. Für größere Bestände gibt es das Professionell-Paket mit individuellem Kontingent.

Kann ich mit n8n auch WZ-2008-Codes übersetzen?

Ja, über denselben Endpoint: Statt { "query": "…" } senden Sie { "action": "translate", "query": "47.91.1" }. Eindeutige Codes beantwortet die API deterministisch über den amtlichen Umsteigeschlüssel.

Was passiert, wenn die API keinen Code ermitteln kann?

Bei zu vagen Beschreibungen antwortet die API mit HTTP 422 (no_match). Im n8n-Workflow fangen Sie das über die Fehlerausgabe des HTTP-Request-Nodes ab und schreiben solche Fälle in eine separate Nachprüfliste, statt den Batch abzubrechen.