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.

 

[wawi-dl]

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.

genau dafür ist ja eine API eigentlich da, dass die Endpunkte immer gleich bleiben ... man sollte das eigentlich vermeiden, unschön von JTL

 

[css-umsetzung]

Ja es ist grausig und ich finde dazu auch nichts weiter in der Doku.

Ich habe das also gestern noch ausgiebig getestet.
Der vernünftigste Weg ist, die 2.0er API gar nicht anzufassen und sich weiter im Verzeichnis /v1/ zu bewegen.

Ich habe auch irgendwie das Gefühl das, dass was in der Doku steht nicht mit dem jSon File zum Einspielen in Postman übereinstimmt, dort wird von diesen Variablen gesprochen:

• X-AppID : Dies ist der Name Ihrer Anwendung, in diesem Fall „MyApp/1.0.0“. Er dient zur Identifizierung Ihrer Anwendung.
• X-AppVersion : Hier wird die Versionsnummer Ihrer Anwendung eingegeben, in diesem Fall „1.0.0“.
• X-RunAs : Hier kann ein JTL-Wawi-Benutzer angegeben werden, der in seinem Namen einen API-Aufruf durchführt (weitere Details in der Dokumentation).
• X-ChallengeCode : Hier können Sie einen beliebigen Wert eingeben. Der X-ChallengeCode wird bei der App-Registrierung verwendet und muss für alle Registrierungsanfragen identisch sein. Die maximale Länge beträgt 30 Zeichen.
• Autorisierung : Der API-Schlüssel. Beispiel: „Wawi 00000000-0000-00000-0000-000000000000“

Nach dem Einspielen in Postman sind diese in den Vorgaben aber alle kleingeschrieben.

gebe ich kein Verzeichnis /v1/ oder eben /v2/ ein, und gehe mit den Variablen wie hier beschrieben rein geht das, die Version kann ich dann über api-version umschalten.

Die Ausgabe der Variablen, wenn ich auf 2.0.0 gehe ist dann eben alles kleingeschrieben.
Irgendwie eigenartig.

Ausgabe für Company

Version (api-version) 1.0.0 (nur 1 geht auch):

[
    {
        "Id": 1,
        "Name": "css-Develope"
    }
]

Version (api-version) 2.0.0:

[
    {
        "id": 1,
        "name": "css-Develope"
    }
]

 

[morpheusd]

Leider gibt es Funktionen die die V1 nicht kann und erst ab der V2 integriert wurden.
Wäre toll wenn sich der JTL REST-API Entwickler hier mal äußern könnte.