JTL Wawi 2.0 REST API Fehler — Validierungsfehler TaxRate und Connector-Probleme, Vlarom Lösungsübersicht

JTL Wawi 2.0 API Fehler: TaxRate-Validierung, Discount-Problem und Connector — Ursachen und Lösung

Seit dem Update auf JTL Wawi 2.0 taucht bei vielen Händlern und Entwicklern derselbe Fehler auf: API-Aufrufe gegen den v1-Endpunkt liefern plötzlich einen `ValidationError`, obwohl die übergebenen Werte scheinbar korrekt sind. Die Fehlermeldung lautet `The field TaxRate must be between 0 and 2147483647` oder `The field Discount must be between 0 and 100` — und das auch dann, wenn die Felder gar nicht mitgeschickt wurden. Das ist kein Konfigurationsfehler auf deiner Seite. Wawi 2.0 hat die interne Validierungslogik der REST API geändert, und API v1 reagiert darauf mit Fehlern, die die eigentliche Ursache verschleiern.

Deine Connector-Anbindung oder dein individueller API-Konnektor läuft nach dem Wawi-Update nicht mehr durch?

Vier Fehlerquellen sind nach dem Wawi-2.0-Rollout besonders häufig — mit konkreten Schritten und Hinweisen aus dem JTL-Issuetracker und echten Händler-Fällen.

Auf einen Blick

  • ✓Nach jedem größeren JTL-Update sehen wir eine Welle von API-Problemen bei Shops mit individuellen Konnektoren oder Drittanbieter-Systemen — Wawi 2.0 ist da keine Ausnahme.
  • ✓Der häufigste Fehler ist ein Validierungsproblem in der REST API v1: TaxRate und Discount werden nach dem Update intern als Integer statt als Dezimalwert geprüft, was zu Fehlern führt, die nichts mit dem gesendeten Wert zu tun haben.
  • ✓Kurzfristig laufen die meisten Konnektoren mit den beschriebenen Workarounds wieder stabil. Mittelfristig ist laut JTL-Dokumentation die Migration auf API v2 der einzige zukunftssichere Weg — API v1 bekommt in Wawi 2.0 keine neuen Features.

Wir entwickeln maßgeschneiderte API-Konnektoren für JTL Wawi — unter anderem für einen Großkunden aus der Genussmittelbranche mit über 10.000 aktiven Artikeln und täglichen Datensynchronisierungen. Wenn ein Wawi-Update Konnektoren bricht, sind wir selbst betroffen. Deshalb kennen wir die Fehler nicht aus der Doku, sondern aus dem laufenden Betrieb. Vlarom E-Commerce Agentur ist JTL Service Partner Gold und hat seit dem Wawi-2.0-Rollout im Februar 2026 mehrere Connector-Projekte durch das Update geführt — von unserem Standort in Ahrensfelde bei Berlin aus, deutschlandweit. Laut JTL-Issuetracker sind die hier beschriebenen Fehler (Tickets WAWI-72784 und CO-2423) serverseitig bestätigt und nicht auf Konfigurationsfehler beim Händler zurückzuführen.

Die vier häufigsten JTL Wawi 2.0 API Fehler — und was dahintersteckt

Wawi 2.0 ist keine inkrementelle Versionierung, sondern ein größerer Architektur-Sprung. Die REST API wurde intern komplett neu geschrieben — das betrifft nicht nur neue Funktionen, sondern auch die Validierungslogik für bestehende Endpunkte in API v1. Vier Fehlerquellen sehen wir nach dem Update am häufigsten:

primary

TaxRate-Validierung: Format-Wechsel Prozent vs. Multiplikator

Nach dem Update auf Wawi 2.0 schlägt der POST-Aufruf auf `/salesOrders`-Positionen fehl mit `ValidationError: The field TaxRate must be between 0 and 2147483647`. Das passiert auch dann, wenn TaxRate nicht mitgeschickt wird oder mit einem Wert wie `7` (Mehrwertsteuersatz 7 %) übergeben wird.

Wawi 2.0 erwartet den Steuersatz intern in einem anderen Format. Der Validierungsbereich `0 bis 2147483647` deutet auf einen Integer-Feldtyp hin, der jetzt anders besetzt ist als in v1.11. Das Problem liegt auf JTL-Seite — der JTL-Support hat das in vergleichbaren Fällen bestätigt. Kurzfristig hilft der Workaround, TaxRate explizit als Integer-Wert im gültigen Bereich zu setzen (z. B. `19` statt `0.19`) und den Feldtyp im Request-Header auf `application/json` zu prüfen.

highlight

Discount-Validierung: Wert 0 wird abgelehnt

Parallel zum TaxRate-Problem tritt bei Auftragspositionen der Fehler `The field Discount must be between 0 and 100` auf — und zwar auch dann, wenn Discount auf `0` gesetzt oder gar nicht übergeben wird. Das ist kontraintuitiv, weil `0` formal im gültigen Bereich liegt.

Die Ursache steckt in einer Änderung der Nullable-Behandlung in der API-Validierungsschicht: Wawi 2.0 behandelt ein fehlendes oder null-Feld anders als v1.11. Konnektoren, die Discount optional mitschicken oder weglassen, landen in einem Validierungsast, der die Prüfung `not null AND between 0 AND 100` erzwingt. Workaround: Discount immer explizit als ganzzahligen Wert übergeben, nie weglassen.

warning

CO-2423 — Connector triggert doppelte Versandbenachrichtigungen

Nach dem Wawi-Update berichten Händler mit Shopify-Connector, dass Versandbenachrichtigungen mehrfach kurz hintereinander an Endkunden ausgelöst werden. Das führt zu Support-Anfragen und Verwirrung beim Kunden. Das Ticket CO-2423 ist offiziell gelöst, aber die Lösung greift nur wenn der Connector auf dem aktuellen Stand ist.

Der Fix: Wenn der Connector bereits eine Versandbenachrichtigung via `status_change.push` ausgelöst hat, wird keine zweite via `delivery_note.push` mehr geschickt. Voraussetzung ist der aktuelle Connector-Stand — bei älteren Versionen tritt das Problem weiterhin auf. Prüfe die installierte Connector-Version im JTL-Kundencenter.

muted

WAWI-72784 — Worker-Fehler IVersandplattformShippingLabelsConnector

Nach dem Wawi-2.0-Update erscheint in den Worker-Logs der Fehler `Unable to resolve type: JTL.Wawi.Versandplattform.Contracts.IVersandplattformShippingLabelsConnector`. Die Shop-Aufträge werden nicht mehr verarbeitet, der Worker bleibt hängen.

Ein Typen-Auflösungsproblem im Worker-Dependency-Injection-Container ist die Ursache — nach dem Major-Release greift die Registrierung nicht mehr. Das Ticket WAWI-72784 ist als gelöst markiert. Die Lösung erfordert einen vollständigen Neustart des Worker-Dienstes nach dem Update, in manchen Fällen auch eine Neu-Registrierung der Versandplattform-Konnektoren in der Wawi-Konfiguration.

5 Schritte um JTL Wawi 2.0 API Fehler zu beheben

Diese Schritte arbeiten wir bei Connector-Projekten nach einem Major-Wawi-Update der Reihe nach durch. Laut Vlarom-Projekterfahrung mit JTL Wawi 2.0 lösen Schritt 1 und 2 in über 70 Prozent der Fälle das akute Problem — Schritt 3 bis 5 sind die mittelfristige Absicherung. Wer einen individuellen API-Konnektor betreibt, findet auf unserer Konnektor-Entwicklungs-Leistungsseite, wie wir Konnektoren update-fest bauen. Für den Überblick über alle Wawi-2.0-Änderungen hilft unsere Wawi-2.0-Update-Checkliste.

API-Version und Endpunkt prüfen (Tag 1)

Prüfe zuerst, gegen welche API-Version dein Konnektor oder deine App Anfragen schickt. Logg den vollständigen Request inkl. URL-Pfad (`/api/v1/` oder `/api/v2/`), Header und Body. Fehler wie TaxRate-Validierung treten ausschließlich auf v1-Endpunkten auf. Wenn dein Konnektor gegen v1 läuft, prüfe als nächstes, ob eine v2-kompatible Version verfügbar ist.

TaxRate und Discount-Felder explizit setzen (Tag 1-2)

Übergib TaxRate und Discount immer explizit als ganzzahlige Integers — nie als Dezimalwert, nie weglassen. Beispiel: `\“TaxRate\“: 19` statt `\“TaxRate\“: 0.19` oder `\“TaxRate\“: null`. Das gleiche gilt für Discount: `\“Discount\“: 0` statt das Feld wegzulassen. Dieser Workaround stabilisiert die meisten v1-Aufrufe, ohne dass du sofort auf v2 migrieren musst. Hintergrund: Der JTL-Issuetracker bestätigt (thread.246389), dass die Validierungslogik auf JTL-Seite geändert wurde.

Connector-Version auf aktuellen Stand bringen (Tag 2-3)

Prüfe die installierte Version deines Connectors (Shopify, WooCommerce, Shopware) im JTL-Kundencenter. Für den Doppel-Versandbenachrichtigungs-Bug (CO-2423) ist ein Update auf den aktuellen Connector-Stand Pflicht — der Fix ist nur in aktuellen Versionen enthalten. Starte nach dem Update den Worker-Dienst vollständig neu. Der WAWI-72784-Worker-Fehler tritt nach sauberem Neustart in den meisten Fällen nicht mehr auf.

REST Server neu konfigurieren wenn die JTL App nicht verbindet (Tag 3-4)

Nach dem Update auf Wawi 2.0 startet der REST-API-Server in manchen Setups nicht korrekt, weil das Profil nicht gefunden wird (Forum-Thread 245836). Öffne in Wawi unter Einstellungen > REST-Server die Konfiguration, prüfe ob das richtige Mandant-Profil eingetragen ist und starte den Server-Dienst neu. Bei Einzelplatz-Installationen prüfe, ob die Profil-Konfiguration noch auf den alten Datenbankpfad zeigt — nach einem Major-Update kann der Pfad sich geändert haben.

Mittelfristig auf API v2 migrieren (Woche 2-4)

API v1 wird in Wawi 2.0 im Kompatibilitätsmodus betrieben und bekommt keine neuen Features. Alle zukünftigen Wawi-Funktionen laufen ausschließlich über v2. Plane die Migration deines Konnektors auf v2 in einem eigenen Schritt: Lege die v2-Swagger-Doku als Basis, prüfe geänderte Feldstrukturen bei SalesOrders und Customers, und führe die Migration in einer Test-Wawi-Instanz durch. Die offizielle REST-API-Dokumentation findest du im JTL-Guide unter Wawi REST API.

Häufige Fragen zu JTL Wawi 2.0 API Fehlern

Was bedeutet der Fehler 'TaxRate must be between 0 and 2147483647' in Wawi 2.0?

Die REST API v1 akzeptiert in Wawi 2.0 den TaxRate-Wert nicht mehr — auch dann nicht, wenn du einen scheinbar gültigen Wert sendest oder das Feld weglässt. Wawi 2.0 behandelt TaxRate intern als Integer, und die Validierung greift anders als in v1.11. Übergib TaxRate als expliziten Integer (z. B. `19` für 19 %) und lass das Feld nie weg. Laut JTL-Issuetracker (Forum-Thread 246389) liegt die Ursache in der geänderten Validierungslogik auf API-Seite — nicht beim sendenden System.

Wawi 2.0 hat die Nullable-Behandlung in der v1-API geändert. Ein fehlendes Discount-Feld oder ein null-Wert landet jetzt in einem Validierungsast, der eine explizite Ganzzahl zwischen 0 und 100 erwartet. Übergib Discount immer explizit als `0`, nie als null und nie weggelassen. Dieser Fehler tritt häufig zusammen mit dem TaxRate-Fehler auf und hat dieselbe Grundursache.

Das ist der bekannte Bug CO-2423. Der Connector triggerte nach einem Abgleich sowohl über `status_change.push` als auch über `delivery_note.push` Versandbenachrichtigungen. Der Fix steckt in aktuellen Connector-Versionen: Wenn bereits eine Benachrichtigung via `status_change.push` ausgelöst wurde, blockt der Connector die zweite. Update den Shopify-Connector auf den aktuellen Stand im JTL-Kundencenter und starte den Worker neu.

Dieser Fehler (WAWI-72784) entsteht, weil der Worker nach dem Major-Update den Dependency-Injection-Container neu aufbauen muss. In den meisten Fällen hilft ein vollständiger Neustart des Worker-Dienstes — nicht nur ein Reload, sondern Stoppen und Neu-Starten. Wenn das Problem weiterhin auftritt, prüfe in der Wawi-Konfiguration ob alle Versandplattform-Konnektoren noch korrekt registriert sind. Der Issuetracker markiert WAWI-72784 als gelöst.

Kurzfristig stabilisieren die beschriebenen Workarounds v1-Konnektoren in den meisten Fällen. Laut JTL-Dokumentation befindet sich API v1 in Wawi 2.0 im Kompatibilitätsmodus — neue Features und Bugfixes erscheinen dort nicht mehr. Die Migration auf v2 sollte schrittweise in einer Testumgebung auf Basis der aktuellen Swagger-Doku erfolgen.

Das ist ein bekanntes Problem bei einigen Setups nach dem Update auf Wawi 2.0.0 (Forum-Thread 245836). Der REST-Server findet das Profil nicht mehr, weil sich Datenbankpfade oder Profil-Konfigurationen beim Major-Update geändert haben. Öffne in Wawi unter Einstellungen die REST-Server-Konfiguration, prüfe das eingetragene Profil und stelle sicher, dass der SQL-Server-Pfad nach dem Update noch stimmt. Bei Einzelplatz-Installationen kann sich der Pfad durch das neue Setup-Verfahren in Wawi 2.0 geändert haben.

API v1 ist der Legacy-Endpunkt, der in Wawi 2.0 im Kompatibilitätsmodus läuft. Er bekommt keine neuen Funktionen und wird mittelfristig weniger aktiv gepflegt. API v2 ist die neue Schicht, komplett neu geschrieben für Wawi 2.0, mit OAuth 2.0, neuen Feldstrukturen und einer vollständig gepflegten Swagger-Doku. Alle Wawi-2.0-spezifischen Funktionen sind nur über v2 verfügbar. Die offizielle Dokumentation dazu findest du im JTL-Guide.

Dein API-Konnektor läuft nach dem Wawi-Update nicht mehr stabil?

Vlarom entwickelt Konnektoren, die Wawi-Updates überstehen.

Wir entwickeln seit Jahren maßgeschneiderte API-Konnektoren für JTL Wawi — von der Erstentwicklung bis zur update-festen Architektur. Als JTL Service Partner Gold kennen wir die Eigenheiten jeder neuen Wawi-Version aus dem laufenden Betrieb, nicht nur aus der Doku. Wenn dein Konnektor nach dem Wawi-2.0-Update Probleme macht, schreib uns direkt an info@vlarom.de oder ruf uns an unter +49 30 91473862. Alternativ nutze unser Kontaktformular für ein unverbindliches Erstgespräch.

Autor

Alexander Luft

JTL Service Partner Gold · Vlarom E-Commerce Agentur · Ahrensfelde bei Berlin