REST Api v2 (Wawi 1.11.7)

[morpheusd]

Hallo zusammen,

wir nutzen die JTL REST API (OnPrem) für ein internes Web-Tool, das Produktionsnummern (Eigene Felder), Lieferanten-Artikelnummern und Versandklassen von Artikeln ändert.

Über v1 funktioniert alles einwandfrei. Wir möchten aber auf v2 umstellen, insbesondere um mehrere Änderungen in einem Call zu bündeln (PATCH /itemdetails/change mit Custom Fields + Suppliers + ShippingClass).


Unser Setup
- JTL-Wawi: 1.11.7
- REST API Server: OnPrem (Windows-Dienst)
- App-Registrierung: Version 3.0.0 mit Scopes: all.read, items.read, items.write, suppliers.read, item.updateitem, item.updateitemsupplier, item.createitemsupplier


Was funktioniert

v1-Endpoints (alle OK):
- GET /v1/items/{id} — Artikel lesen
- PATCH /v1/items/{id} — Versandklasse ändern
- PATCH /v1/items/{id}/customfields/201 — Eigenes Feld ändern
- PATCH /v1/items/{id}/suppliers/{id} — Lieferanten-Sku ändern

v2-Lesen (über api-version: 2 Header, NICHT über /v2/ im Pfad):
- GET /items/{id} mit Header api-version: 2 liefert Daten
- GET /items/{id}/suppliers mit Header api-version: 2 liefert Daten
- GET /shippingClasses mit Header api-version: 2 liefert Daten

v2 mit /v2/ im URL-Pfad:
- Gibt immer 400 UnsupportedApiVersion zurück


Das Problem: v2-Write ändert nichts

PATCH /itemdetails/change mit Header api-version: 2 gibt HTTP 200 (leere Response) zurück, ändert aber keine Daten in der Datenbank. Teilweise kommt auch HTTP 404.


Was wir alles getestet haben:

1. Einfacher Request (einzelnes Objekt):

curl -X PATCH '<server>/api/eazybusiness/itemdetails/change' \
-H 'Authorization: Wawi <token>' \
-H 'X-AppId: produktionsnummer-tool-v3' \
-H 'X-AppVersion: 3.0.0' \
-H 'api-version: 2' \
-H 'Content-Type: application/json' \
-d '{"ItemId": 151147, "ShippingClassId": 7}'

Ergebnis: HTTP 200, leere Response, ShippingClassId bleibt unverändert bei 4.


2. Mit Variations (laut OpenAPI-Spec ein required-Feld):

{"ItemId": 151147, "ShippingClassId": 7, "Variations": {"Variations": []}}

Ergebnis: HTTP 200, keine Änderung.


3. Als Array (Bulk-Format):

[{"ItemId": 151147, "ShippingClassId": 7, "Variations": {"Variations": []}}]

Ergebnis: HTTP 404.


4. Mit Wrapper-Objekt:

{"items": [{"ItemId": 151147, "ShippingClassId": 7}]}

Ergebnis: HTTP 200, keine Änderung.


5. camelCase statt PascalCase:

{"itemId": 151147, "shippingClassId": 7, "variations": {"variations": []}}

Ergebnis: HTTP 200, keine Änderung.


6. Vollständiger Payload (Custom Fields + Suppliers + Variations):

{
"itemId": 151147,
"shippingClassId": 7,
"customFields": {
"fieldValues": [{"fieldId": 201, "value": "TEST", "valueCultureName": ""}]
},
"suppliers": {
"suppliers": [{"supplierId": 2, "supplierItemNumber": "TEST"}]
},
"variations": {"variations": []}
}

Ergebnis: HTTP 404.


7. api-version: 2.0 statt api-version: 2:

Ergebnis: HTTP 404.


Zum Vergleich — v1 funktioniert sofort:

curl -X PATCH '<server>/api/eazybusiness/v1/items/151147' \
-H 'Authorization: Wawi <token>' \
-H 'Content-Type: application/json' \
-d '{"ShippingClassId": 7}'

Ergebnis: ShippingClassId sofort auf 7 geändert.


Zusätzliche Info:
- Swagger UI ist auf dem Server nicht erreichbar (404 unter /swagger, /api/eazybusiness/swagger und /api/eazybusiness/swagger.json)
- Wir können das erwartete Request-Schema deshalb nicht direkt am Server prüfen


Zusammenfassung:

Funktion | v1 (Pfad-basiert) | v2 (api-version Header)
Artikel lesen | OK | OK
Lieferanten lesen | OK | OK
Versandklassen lesen | OK | OK
Artikel ändern | OK | 200 aber keine Änderung
Custom Fields ändern | OK | 200 aber keine Änderung
Suppliers ändern | OK | 200 aber keine Änderung


Unsere Fragen:

1. Hat jemand PATCH /itemdetails/change mit api-version: 2 Header erfolgreich im Einsatz? Wenn ja — wie sieht der Request-Body genau aus?
2. Wie kann man die Swagger UI auf dem OnPrem-Server aktivieren, um das erwartete Schema direkt zu prüfen?
3. Werden v2-Write-Endpoints eventuell erst mit einem neueren Wawi-Update freigeschaltet?
4. Ist es korrekt, dass der api-version Header der richtige Weg für v2 ist (und nicht /v2/ im Pfad)?

Danke für jeden Hinweis!

 

[css-umsetzung]

Es wurden in der V2 viele Variablen geändert, der Name ist gleich aber ein ->Id wurde nun zu ->id, ->Name zu ->name

Die Version die du verwenden möchtest kannst du mit /v2/ oder /v1/ in der URL übergeben, nimmst du diese Übergabe nicht, nimmt er die aktuelle der WAWI.

Die Version kann auch über Parameter im Header übergeben werden "api-version"

 

[morpheusd]

Es wurden in der V2 viele Variablen geändert, der Name ist gleich aber ein ->Id wurde nun zu ->id, ->Name zu ->name

Die Version die du verwenden möchtest kannst du mit /v2/ oder /v1/ in der URL übergeben, nimmst du diese Übergabe nicht, nimmt er die aktuelle der WAWI.

Die Version kann auch über Parameter im Header übergeben werden "api-version"

Danke für die Hinweise!

Wir haben das direkt getestet, leider ohne Erfolg:

1. /v2/ im Pfad: Gibt bei uns bei ALLEN Endpoints "400 UnsupportedApiVersion" zurück — auch bei reinen GET-Abfragen:

GET /v2/shippingClasses → 400 UnsupportedApiVersion
GET /v2/items/151147 → 400 UnsupportedApiVersion
GET /v2/items/151147/suppliers → 400 UnsupportedApiVersion

2. camelCase haben wir ebenfalls getestet (itemId statt ItemId, shippingClassId statt ShippingClassId) — in Kombination mit /v2/ im Pfad, mit api-version: 2 Header, und ohne Versionsangabe. Kein Unterschied.

3. Ohne Versionsangabe im Pfad (also z.B. GET /shippingClasses) funktioniert die API — scheint aber auf v1 zu fallen, da die Response-Struktur identisch mit /v1/ ist.

Es sieht so aus, als ob unser REST API Server v2 schlicht nicht kennt. Swagger UI ist bei uns ebenfalls nicht erreichbar (404 auf /swagger und allen Varianten).

Zwei Fragen dazu:
- Muss der REST API Server möglicherweise separat aktiviert oder konfiguriert werden, damit v2 verfügbar ist?
- Gibt es eine Möglichkeit zu prüfen welche API-Version der laufende REST-Server tatsächlich unterstützt (z.B. ein Info- oder Health-Endpoint)?

Danke!

 

[css-umsetzung]

Also ich habe gestern nur den Registrierungsvorgang und einige andere kleine Sachen durchgetestet.
Die Registrierung hat nachdem ich die Variablen angepasst hatte geklappt.

Am WE wollte ich mich da weiter mit beschäftigen.

Ist schon doof, wenn die Variablen auf einmal anders sind.