API 2.1 für OnPrem?

[Care21]

Moin!
Die DevDoc für OnPrem wurde seit 2.0 / 2.1 entfernt. Bedeutet dies, dass es keine OnPrem Version gibt für die REST API 2.0/2.1?
Geht alles nur noch über den JTL Hub?

Bin da tatsächlich etwas verwirrt - auch mangels Kommunikation.
Vielen Dank falls jemand die v2 API nutzt

VG

 

[Morimus]

Vielen Dank falls jemand die v2 API nutzt

Moin,
ich hatte kürzlich mit dem JTL-Support telefoniert.
Dabei ging es unter anderem um die neue API.

Mir wurde nahegelegt, mich künftig auf die neue JTL Cloud API zu fokussieren.

Abhängig davon, was du am Ende erreichen möchtest, ist die OnPrem API aber nicht als „deprecated“ zu betrachten.
Sie ist weiterhin nutzbar und für lokale Wawi-nahe Prozesse auch nach wie vor relevant.
Nach meinem Verständnis wird es aber eher keine OnPrem API 2.0 mehr geben.

Wenn du möglichst zukunftssicher entwickeln möchtest, würde ich daher von vornherein die JTL Cloud API nutzen, also über den Hub bzw. das Partner Portal eine App registrieren.
Gerade wenn man sich Themen wie JTL Shipping 2.0 und die künftige API-Strategie anschaut, ergibt es meiner Meinung nach sehr viel Sinn, direkt auf die Cloud API zu setzen.

 

[Care21]

Im großen und ganzen möchte ich eigentlich nur Lieferscheine quittieren / bestätigen per Package Data. Aber der Endpunkt scheint in v1 entweder buggy oder defekt zu sein.
Müsste ich mal in Ruhe austesten. Vielen Dank dir.

 

[Morimus]

Im großen und ganzen möchte ich eigentlich nur Lieferscheine quittieren / bestätigen

Ich weiß nicht genau, was du in dem Zusammenhang mit „bestätigen“ meinst.

Wenn du damit meinst, den Auftrag bzw. den Lieferschein wirklich als versendet zu setzen, glaube ich nicht, dass das über die OnPrem API v1 sauber möglich ist.
Zumindest wirkt der Package-Data-Endpunkt dort eher so, als würde man Paketdaten wie Trackingnummer, Versanddatum oder Kommentar übertragen, aber nicht zwingend den kompletten Versandabschluss auslösen.

Die neue JTL Cloud API v2 sieht dafür deutlich passender aus. Dort gibt es den Endpunkt:
POST /v2/package/deliver

Der heißt in der Doku ausdrücklich „Delivers an existing Package“ und nimmt unter anderem packageId, trackingCode und shippingDate entgegen.

Das klingt für mich eher nach dem, was du suchst. Ich würde daher v1 zwar einmal gegenprüfen, aber wenn der Endpunkt dort ohnehin hakelig ist, würde ich mir direkt die Cloud API v2 anschauen.

 

[Care21]

Kurze Frage an dich: Wo finde ich (eindeutig) die Tenant-ID? Meines Wissens nach benötige ich die doch bereits fürs Auth?

 

[Morimus]

Die tenantId erhältst du offiziell aus dem Session Token, das dein Frontend über die AppBridge mit appBridge.method.call('getSessionToken') anfordert.

Dein Backend verifiziert dieses Token mithilfe der öffentlichen Schlüssel von JTL, also JWKS, und liest anschließend die tenantId aus dem Payload aus.
Diese verwendest du dann bei API-Aufrufen im Header X-Tenant-ID.

Wenn du den offiziellen Weg gehst, musst du dafür natürlich entsprechend etwas bauen.

So viel zum offiziellen Weg.

Pragmatisch geht es aber auch einfacher.
JTL sendet die Tenant-ID an mehreren Stellen über die API mit.

Wenn du deine App im Hub installiert hast, kannst du im Browser die Entwicklertools öffnen und im Netzwerk-Tab nach folgendem Request suchen:

GET https://api.jtl-cloud.com/account/tenants

In der Antwort findest du die Tenant-ID.
Für X-Tenant-ID ist dabei das Feld id relevant.

Ob das so als offizieller Weg gedacht ist, weiß ich nicht.
Für einen schnellen Test lässt sich die Tenant-ID darüber aber eindeutig ermitteln.

 

[Care21]

Hallo zusammen,

ich versuche aktuell, unsere Cloud-App (Manifest v1.0.3, 24 Scopes, korrekt installiert + konsentiert) gegen die JTL Cloud REST API zu schreiben — konkret den Endpoint POST
/erp/v2/deliveryNotes/{id}/packages, um Tracking-Codes aus unserem externen Logistik-Dienstleister zurück in die Wawi zu pushen.

Stoße aber konsequent auf folgenden Fehler bei jedem v2-Aufruf, der Versand-Daten zurückgeben würde:

{
"Status": 400,
"Detail": "No seed found for key type JTL.Data.Contracts.Keys.VersandKey.
Please ensure that the key seed data is initialized.",
"Instance": "/api/Mandant_2/v2/deliveryNotes"
}

Egal ob:
- GET /v2/deliveryNotes ohne Filter
- mit ?salesOrderNumber=… (wenn der Auftrag existiert)
- mit ?customerId=…
- mit ?salesOrderNumberId=<UUID>
- mit oder ohne x-appid/x-appversion-Header
- mit oder ohne pageSize

→ immer derselbe Seed-Fehler. Einzige Ausnahme: Wenn die Query ein leeres Resultset zurückgibt (z.B. ?salesOrderNumber=BLABLA-EXISTIERT-NICHT), kommt HTTP 200 mit totalItems: 0. Klingt für mich danach, dass
der Serializer beim Versuch, eine VersandKey-UUID aufzulösen, an einer leeren Mapping-Tabelle scheitert.

Was sonst klappt (zur Eingrenzung):
- ✅ REST V1 — GET /v1/deliveryNotes/<int-id> und …/packages funktionieren komplett (int-IDs, kein UUID-Seed nötig)
- ✅ GraphQL — QuerySalesOrders, QueryItems, QueryCustomers alle ok
- ✅ GraphQL Mutations — Permission ist nach Re-Install jetzt da (kein AppNotAllowed mehr)
- ❌ aber CreateDeliverPackage braucht packageId als UUID, und die UUID kriege ich nur über /v2/deliveryNotes/.../packages — was am Seed-Fehler scheitert. Chicken-and-Egg.

Frage an die Runde:
1. Ist das ein bekannter Init-Bug bei frisch installierten Cloud-Apps?
2. Hat jemand das schon gehabt und kennt einen Trigger, der den Seed-Build serverseitig anstößt? (Erneute Wawi-Lizenz-Refresh? Specific First Call gegen einen anderen Endpoint?)
3. Oder ist das ein klarer JTL-Support-Fall und ich mach mir umsonst Hoffnung auf eine self-service Lösung?

Würde mich freuen, wenn jemand von euch das gleiche Phänomen kennt oder einen Workaround hat.

Danke!