JTL-Wawi REST-API in der Praxis: was sie schreiben kann – und wo sie endet

Seit einigen Versionen bringt JTL-Wawi eine eigene REST-API mit. Damit lassen sich Artikeldaten, Preise oder Aufträge aus anderen Programmen lesen und schreiben – ohne Ameise-Import und ohne direkten Griff in die Datenbank. In der Praxis stellt sich aber schnell die Frage: Was genau kann ich darüber schreiben? Die Antwort ist kleiner, als viele erwarten – und an einigen Stellen anders, als die Begriffe vermuten lassen.

Dieser Beitrag fasst zusammen, was wir an echten Installationen geprüft haben: Registrierung, schreibbare Bereiche, typische Fehler und die Grenzen der Schnittstelle.

Wofür die REST-API gedacht ist

Die REST-API ist die offizielle Schnittstelle für Fremdanwendungen, die mit der Wawi Daten austauschen: CRM-Systeme, eigene Tools, Preis- oder Lagerautomatisierungen. Ihr Vorteil gegenüber direkten SQL-Zugriffen:

• Jede App hat einen eigenen Schlüssel mit genau festgelegten Rechten (Scopes).
• Die Wawi prüft die Daten selbst und protokolliert die Aufrufe.
• Schreibzugriffe laufen über die Geschäftslogik der Wawi statt an ihr vorbei.

Die Struktur der Pfade folgt immer demselben Muster:

https://<server>:<port>/api/eazybusiness/v1/<ressource>

Die vollständige Beschreibung aller Endpunkte veröffentlicht JTL als OpenAPI-Spezifikation im JTL Developer Portal. Auf der Wawi-Instanz selbst gibt es in der Regel keine Swagger-Oberfläche.

JTL Cloud bietet zusätzlich eine GraphQL-Schnittstelle. Die On-Premise-Wawi auf Ihrem eigenen Server hat nur die REST-API.

Voraussetzungen

• Eine aktuelle JTL-Wawi (in unseren Fällen ab 1.10).
• Die REST-API-Instanz muss im JTL-Administrator gestartet sein. Dass der Windows-Dienst läuft, reicht allein nicht.
• Die API lauscht auf einem HTTPS-Port und optional auf einem HTTP-Port. Achten Sie darauf, das Protokoll passend zum Port zu wählen: Eine https://-Adresse auf dem reinen HTTP-Port scheitert schon beim Verbindungsaufbau.
• Die Wawi verwendet standardmäßig ein selbstsigniertes Zertifikat. Ihr Client muss diesem Zertifikat vertrauen oder entsprechend konfiguriert sein.

Die App-Registrierung – und der häufigste Fehler

Bevor eine Anwendung auch nur einen Artikel lesen darf, muss sie sich bei der Wawi registrieren. Das ist ein zweiseitiger Handschlag, und die Reihenfolge entscheidet:

1. In JTL-Wawi unter Admin > App-Registrierung auf „Hinzufügen“ klicken. Der Assistent öffnet sich und wartet auf eine eingehende Registrierung.
2. Erst jetzt in der Fremdanwendung die Registrierung auslösen (oft ein Knopf „Registrieren“ – ein reiner „Verbindung testen“-Knopf prüft nur die Erreichbarkeit).
3. Zurück in der Wawi: App-Daten bestätigen, einen eigenen Benutzer zuweisen, Scopes freigeben, fertigstellen.
4. Die Anwendung erhält ihren API-Schlüssel.

Wird Schritt 2 vor Schritt 1 ausgeführt, hat die Wawi nichts, wogegen sich die App registrieren könnte. Die Fremd-App meldet dann nur ein allgemeines „Verbindung fehlgeschlagen“ oder „nicht als App registriert“ – obwohl Adresse und Port stimmen.

Technisch sendet die App dabei eine Anfrage an /v1/authentication (mit App-Kennung, Anzeigename, Version, Anbieter, gewünschten Scopes und Icon) und fragt anschließend den Status ab, bis der Schlüssel ausgestellt ist.

Scopes bewusst wählen: Eine App, die nur Lese-Scopes erhalten hat, kann zwar alles abfragen, bekommt beim Schreiben aber eine Ablehnung. Wer später Sonderpreise oder eigene Felder setzen will, muss die passenden Schreibrechte im Assistenten freigeben. Die Registrierung gilt pro Wawi-Instanz – bei mehreren Mandanten oder Servern ist sie jeweils separat nötig.

Was die API schreiben kann – und was nicht

Die folgende Übersicht beruht auf der offiziellen OpenAPI-Beschreibung und auf Prüfungen an laufenden Installationen.

Eigene Felder sind nicht „Attribute“

Hier passieren die meisten Missverständnisse. Die REST-API spricht von Custom Fields. Gemeint sind ausschließlich die eigenen Felder der Wawi – nicht die klassischen Attribute aus Attributgruppen, die zum Beispiel viele Marktplatz-Anbindungen als Datenquelle nutzen. Beide Begriffe tauchen in der Wawi ähnlich auf, sind technisch aber getrennt. Klassische Attribute lassen sich per REST weder lesen noch schreiben.

Prüfen Sie vor dem Projektstart mit GET /items/customfields, welche Felder die API tatsächlich anbietet. Was dort nicht in der Liste steht, ist per REST nicht erreichbar.

Verkaufskanal: Artikel ja, Mapping nein

PATCH /items/salesChannels ordnet Artikel einem Kanal zu. Die Konfiguration, welche Kategorie welche Kanal-Attribute bekommt, gehört nicht dazu. Ein fehlerhaftes Kategorie-Mapping lässt sich also nicht per API reparieren.

Sonderpreise und Kanäle

Sonderpreise werden je Kundengruppe und Verkaufskanal gesetzt. Die Kanal-IDs liefert GET /salesChannels. Dort erscheinen nur Kanäle, die Sonderpreise unterstützen. Einige Marktplatz-Anbindungen fehlen in dieser Liste ganz – für sie gibt es dann keinen REST-Weg.

Beispielaufruf: einen Sonderpreis setzen

Jeder authentifizierte Aufruf braucht drei Header: den Schlüssel, die App-Kennung und die App-Version. Fehlt die App-Kennung, antwortet die API mit einem 400-Fehler.

PATCH https://<server>:<port>/api/eazybusiness/v1/items/<artikel-id>/specialprices
Authorization: Wawi <api-schluessel>
x-appid: <app-id>
x-appversion: <app-version>
Content-Type: application/json

{
  "IsActive": true,
  "StartDate": "2026-11-01T00:00:00",
  "EndDate": "2026-11-30T23:59:59",
  "EndDateActive": true,
  "TillAmountActive": false,
  "SpecialPrice": [
    {
      "IsActive": true,
      "CustomerGroupId": <kundengruppen-id>,
      "SalesChannelId": "<kanal-id-aus-salesChannels>",
      "NetPrice": 19.90
    }
  ]
}

Zum Beenden der Aktion genügt ein PATCH mit {"IsActive": false}. Datumswerte werden im Format JJJJ-MM-TTTHH:MM:SS übergeben.

Ein eigenes Feld setzen Sie analog:

PATCH https://<server>:<port>/api/eazybusiness/v1/items/<artikel-id>/customfields/<feld-id>
Authorization: Wawi <api-schluessel>
x-appid: <app-id>
x-appversion: <app-version>
Content-Type: application/json

{ "Value": "<neuer-wert>" }

Typische Fehlerbilder

Wenn die API nicht reicht

Für die Lücken gibt es drei Wege – mit sehr unterschiedlichem Risiko:

• JTL-Ameise: Der offizielle Import für klassische Attribute und Massendaten. Gut für einmalige oder regelmäßige Dateiimporte, nicht für Echtzeit.
• Custom Workflows: Eigene Workflow-Aktionen als Stored Procedure, die die Wawi selbst auslöst. Sinnvoll, wenn etwas automatisch bei einem Ereignis passieren soll. Wie das geht, zeigen wir in Eigene Workflow-Aktionen in JTL-Wawi.
• Direkter Datenbankzugriff: Technisch alles möglich, aber ohne Prüfung durch die Wawi, ohne API-Protokoll und mit dem Risiko, dass ein Update Tabellen verändert.

Schreiben Sie nur dann direkt in die Wawi-Datenbank, wenn jemand mit genauer Kenntnis des Datenmodells es tut – und nur nach einer Sicherung und einem Test auf einer Kopie. Fehlerhafte Einträge fallen oft erst Tage später beim Abgleich mit Shop oder Marktplatz auf.

Unsere Faustregel: Was die REST-API kann, läuft über die REST-API. Erst wenn ein Bereich nachweislich fehlt, kommen Ameise, Workflow oder Datenbank ins Spiel – in dieser Reihenfolge.

Bei PC-Mixx setzen wir die REST-API in eigenen Werkzeugen für JTL-Wawi ein und kennen ihre Grenzen aus der Praxis. Wenn Sie prüfen möchten, ob Ihr Vorhaben per API umsetzbar ist, sprechen Sie uns an.

Häufige Fragen