WZ 2025 API: Branchenklassifizierung ins eigene System integrieren

Die WZ 2025 API im Überblick

Die WZ 2025 API besteht aus einem einzigen HTTP-Endpoint. Sie senden einen POST-Request an https://www.wz2025.io/api/v1 und steuern über den Request-Body, welche der beiden Aufgaben ausgeführt wird.

Fehlt das Feld action, klassifiziert die API. Die Eingabe im Feld query ist auf 1.000 Zeichen begrenzt. Wer die Zuordnung zunächst ohne Code testen möchte, findet die interaktive Demo mit derselben Logik auf der Startseite unter WZ 2025 API. Wie die Ermittlung aus einer Beschreibung fachlich funktioniert, beschreibt der Artikel WZ-Code ermitteln.

Authentifizierung und API-Key

Jede Anfrage authentifiziert sich über den Header x-api-key. Den Schlüssel erhalten Sie nach Abschluss des Tarifs einmalig per E-Mail. Der Schlüssel beginnt mit wz_ und wird serverseitig nur als Hash gespeichert, weshalb er nach der Zustellung nicht erneut angezeigt werden kann. Im Konto-Bereich lässt er sich bei Verdacht auf Kompromittierung erneuern, wobei der bisherige Verbrauch erhalten bleibt.

Ohne gültigen Header lehnt die API die Anfrage ab. Prüfen Sie den Key deshalb serverseitig und geben Sie ihn nicht im Frontend aus, damit er nicht im ausgelieferten Quelltext landet.

Unternehmen klassifizieren

Für die Klassifizierung senden Sie im Body das Feld querymit dem Unternehmensgegenstand oder einer kurzen Tätigkeitsbeschreibung. Das folgende Beispiel ordnet die Tätigkeit „Buchbinder" zu. Ersetzen Sie <token> durch Ihren API-Key.

curl -X POST 'https://www.wz2025.io/api/v1' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <token>' \
  --data-raw '{ "query": "Buchbinder" }'

const resp = await fetch('https://www.wz2025.io/api/v1', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<token>',
  },
  body: JSON.stringify({ query: 'Buchbinder' }),
});
const data = await resp.json();
console.log(data.code, data.text);

import requests

resp = requests.post(
    'https://www.wz2025.io/api/v1',
    headers={'x-api-key': '<token>'},
    json={'query': 'Buchbinder'},
)
data = resp.json()
print(data['code'], data['text'])

Die Antwort enthält den Code in mehreren Feldern:

{
  "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 }
}

Für die maschinelle Weiterverarbeitung nutzen Sie code und text getrennt. Das Feld result ist der kombinierte String für die direkte Anzeige.

WZ 2008 in WZ 2025 übersetzen

Bestandsdaten tragen häufig noch WZ-2008-Codes. Um einen solchen Code auf WZ 2025 zu heben, setzen Sie im Body das Feld action auf translate und übergeben den WZ-2008-Code im Feld query.

curl -X POST 'https://www.wz2025.io/api/v1' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <token>' \
  --data-raw '{ "action": "translate", "query": "47.91.1" }'

{
  "result": "47.91.2 - Sonstige Vermittlungstätigkeiten für den Einzelhandel ohne ausgeprägten Schwerpunkt",
  "code": "47.91.2",
  "text": "Sonstige Vermittlungstätigkeiten für den Einzelhandel ohne ausgeprägten Schwerpunkt",
  "usage": { "used": 43, "included": 300, "hardLimit": 330 }
}

Eindeutige Zuordnungen beantwortet die API deterministisch über den amtlichen Umsteigeschlüssel, ohne ein Sprachmodell zu bemühen. Nur bei mehrdeutigen Codes, bei denen ein WZ-2008-Code auf mehrere WZ-2025-Codes aufgeteilt wurde, entscheidet das Modell anhand der offiziellen Kandidatenliste. Wie die Zuordnung inhaltlich funktioniert und warum sie nicht immer 1:1 ist, erklärt der Artikel WZ 2008 auf WZ 2025 umschlüsseln.

Response-Felder und Statuscodes

Bei Erfolg antwortet die API mit dem Statuscode 200 und einem JSON-Objekt. Die Felder sind bei Klassifizierung und Übersetzung identisch aufgebaut:

Fehler meldet die API über den HTTP-Statuscode und ein Feld error im Body. Behandeln Sie in Ihrer Integration mindestens diese Fälle:

Ein 422 ist kein technischer Fehler, sondern ein Hinweis, dass die Beschreibung zu vage war. In diesem Fall präzisieren Sie die Eingabe, etwa indem Sie den vollständigen Unternehmensgegenstand statt nur des Firmennamens senden. Ein 429 signalisiert das Ende des Kontingents und setzt sich mit der nächsten Abrechnungsperiode zurück.

Batch-Verarbeitung für Onboarding und Rezertifizierung

Im Onboarding rufen Sie die API pro neuem Datensatz einmal auf und schlagen dem Nutzer den ermittelten Code direkt im Formular vor. Für die turnusmäßige Rezertifizierung von Bestandskunden iterieren Sie über Ihre Datenbank und verarbeiten die Sätze im Stapel. Das folgende Muster zeigt eine schlichte Schleife in Python, die pro Datensatz übersetzt oder klassifiziert und das Ergebnis zurückschreibt.

import time, requests

API = 'https://www.wz2025.io/api/v1'
HEADERS = {'x-api-key': '<token>'}

def wz2025(payload):
    r = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    if r.status_code == 429:
        raise SystemExit('Kontingent aufgebraucht')
    if r.status_code != 200:
        return None
    return r.json()

for kunde in bestandskunden:  # aus DB, CRM oder CSV
    # Alt-Code auf WZ 2025 heben ...
    res = wz2025({'action': 'translate', 'query': kunde['wz2008']})
    # ... oder aus dem Unternehmensgegenstand neu klassifizieren:
    # res = wz2025({'query': kunde['gegenstand']})
    if res:
        kunde['wz2025'] = res['code']
    time.sleep(0.2)  # Anfragen etwas entzerren

Prüfen Sie im Ergebnis das Feld usage, um das Kontingent im Blick zu behalten, und stoppen Sie den Lauf sauber bei einem 429. Warum die Rezertifizierung der natürliche Moment für die Migration alter WZ-2008-Bestände ist, behandelt der Artikel KYC-Rezertifizierung: WZ-Codes automatisiert prüfen und aktualisieren. Ohne eigenen Code lässt sich derselbe Ablauf per Workflow-Tool bauen, siehe mit n8n die WZ 2025 API abfragen. Für KI-Agenten steht die gleiche Logik zusätzlich als MCP-Server bereit.

Kontingent und Limits

Der Tarif Flat 300 umfasst 300 Abfragen pro Monat für 39 Euro zuzüglich Umsatzsteuer. Jede erfolgreiche Anfrage zählt eine Abfrage, unabhängig davon, ob klassifiziert oder übersetzt wird. Bis zu einem harten Limit von 330 Abfragen läuft die Verarbeitung weiter. Diese 10 Prozent Kulanz fangen Lastspitzen ab. Danach antwortet die API mit 429, bis das Kontingent zu Beginn der nächsten Abrechnungsperiode zurückgesetzt wird. Den aktuellen Verbrauch lesen Sie jederzeit aus dem Feld usage jeder Antwort oder im Konto-Bereich ab.

Einen fachlichen Gesamtüberblick zur Klassifikation, ihrem Aufbau und dem Verhältnis zu NACE Rev. 2.1 gibt der Übersichtsartikel WZ 2025 im Überblick.

Häufige Fragen zur WZ 2025 API

Was ist die WZ 2025 API?

Die WZ 2025 API ist ein REST-Endpoint (POST /api/v1), der eine freie Unternehmensbeschreibung in den passenden WZ-2025-Code klassifiziert und bestehende WZ-2008-Codes in WZ 2025 übersetzt. Die Antwort kommt als JSON mit Code, Klartext und Kontingent-Verbrauch zurück.

Wie authentifiziere ich mich an der API?

Jede Anfrage sendet den API-Key im Header x-api-key. Den Key erhalten Sie nach dem Kauf des Tarifs einmalig per E-Mail. Fehlt der Header, antwortet die API mit 401. Über die Weboberfläche im Konto-Bereich lässt sich der Key bei Bedarf erneuern.

Welche Statuscodes gibt die WZ 2025 API zurück?

200 bei erfolgreicher Zuordnung, 400 bei fehlerhaftem Body, 401 bei fehlendem oder ungültigem Key, 403 bei inaktivem Abo, 422 wenn kein Code ermittelbar ist, 429 bei aufgebrauchtem Kontingent sowie 502/503 bei temporären Verarbeitungsfehlern.

Kann ich WZ-2008-Codes über die API übersetzen?

Ja. Senden Sie im Body zusätzlich das Feld action mit dem Wert translate und im Feld query den WZ-2008-Code. Eindeutige Zuordnungen beantwortet die API deterministisch über den amtlichen Umsteigeschlüssel, mehrdeutige Codes werden anhand der Kandidatenliste bestimmt.

Wie viele Abfragen sind im Tarif enthalten?

Der Tarif Flat 300 umfasst 300 Abfragen pro Monat für 39 Euro zzgl. USt. Bis 330 Abfragen (plus 10 Prozent Kulanz) läuft die Verarbeitung weiter, danach antwortet die API mit 429. Das Kontingent setzt sich zu Beginn jeder Abrechnungsperiode zurück.

Eignet sich die API für die Rezertifizierung im Batch?

Ja. Für einen Rezertifizierungslauf iterieren Sie über Ihre Bestandsdaten und rufen die API pro Datensatz auf. Über action translate heben Sie alte WZ-2008-Codes auf WZ 2025, über die Klassifizierung prüfen Sie den Unternehmensgegenstand gegen den hinterlegten Code.