JTL-App erstellen

Hinweis: Die fett gesetzten Bezeichnungen entsprechen der deutschen Oberfläche. Ist die App auf Englisch eingestellt, erscheinen sie auf Englisch.

Balta Labs verbindet sich mit dem JTL Fulfillment Network (JTL FFN) über eine App, die Sie selbst bei JTL registrieren. JTL nennt sie OAuth-Client. Die App liefert Ihnen eine Client-ID und ein Client-Secret. Sie geben beide in Balta Labs ein und erlauben anschließend den Zugriff bei JTL, wie unter JTL mit dem Hub verbinden beschrieben.

JTL beschreibt diese Schritte unter Getting started in seiner Dokumentation der Merchant API. Die Ansichten bei JTL können sich ändern. Weicht eine Bezeichnung von dieser Anleitung ab, folgen Sie der aktuellen Formulierung bei JTL.

Vorbereitung

• Ein Konto im JTL-Kundencenter. Dort erstellen Sie die App.
• Ein JTL-Konto mit der Rolle Merchant (Händler) in JTL FFN. Mit diesem Konto melden Sie sich beim Verbinden an. JTL erlaubt nur Benutzern mit der Rolle Merchant, die API zu nutzen, die Balta Labs benötigt.
• Eine einmalige Anmeldung im FFN-Portal mit diesem Konto. Verwenden Sie fulfillment.jtl-software.com für die Produktion oder fulfillment-sandbox.jtl-software.com für die Sandbox. JTL legt den API-Benutzer bei der ersten Anmeldung an. Bis dahin antwortet JTL mit not found, und Balta Labs meldet, dass das JTL-Konto noch nicht bereit ist.
• Die Berechtigung „Verbindungen“ in Ihrem Balta-Labs-Workspace. Sie benötigen sie, um den Verbindungsdialog zu öffnen und die Callback-URL zu kopieren.

Callback-URL aus Balta Labs kopieren

Nachdem Sie den Zugriff erlaubt haben, leitet JTL Sie über die Callback-URL der App zurück zu Balta Labs. Diese URL muss genau der Adresse entsprechen, die Balta Labs anzeigt.

1. Öffnen Sie in Balta Labs Einstellungen → Verbindungen, wählen Sie Add account und dann JTL FFN. Alternativ wählen Sie Anbieter hinzufügen im Bereich Fulfillment-Anbieter. Der Dialog JTL Fulfillment Network verbinden öffnet sich.
2. Suchen Sie unter Bevor Sie fortfahren die Callback-URL und wählen Sie Kopieren. Die Adresse sieht etwa so aus: https://api.example.com/connections/oauth/jtl_ffn/callback. Verwenden Sie immer die Adresse aus Ihrem Dialog, nicht dieses Beispiel.
3. Lassen Sie den Dialog geöffnet, während Sie die App erstellen. Er nennt auch die zu aktivierenden Scopes und verlinkt auf diese Anleitung.

Tippen Sie die Adresse nicht von Hand ab. Ein abweichendes Zeichen, http statt https, ein zusätzlicher Schrägstrich am Ende oder ein Leerzeichen führt dazu, dass die Callback-URL nicht übereinstimmt. Meldet der Dialog JTL-Verbindungen sind auf diesem Server noch nicht verfügbar, kann Balta Labs keine Callback-URL anbieten. Wenden Sie sich an den Balta-Labs-Support.

App bei JTL erstellen

1. Öffnen Sie kundencenter.jtl-software.de/oauth und melden Sie sich an. Der Link JTL-Kundencenter öffnen im Dialog führt zur selben Seite. Die Seite ist im Menü des Kundencenters nicht verlinkt; öffnen Sie diese Adresse deshalb direkt.
2. Legen Sie einen neuen OAuth-Client an.
3. Wenn JTL nach einem Namen fragt, wählen Sie einen, den Sie später wiedererkennen, zum Beispiel Balta Labs.
4. Aktivieren Sie die Scopes ffn.merchant.read und ffn.merchant.write. JTL bietet Scopes möglicherweise über eine Vorlage an; wählen Sie eine, die beide enthält. Fulfiller-Scopes allein reichen nicht aus.
5. Tragen Sie die Callback-URL aus Balta Labs als Redirect-URI der App ein. JTL bezeichnet dieses Feld möglicherweise auch als callback URI.
6. Speichern Sie den Client.
7. Kopieren Sie die Client-ID und das Client-Secret, die JTL für den Client anzeigt.

Scope	Beschreibung von JTL	Verwendung in Balta Labs
ffn.merchant.read	Vollständiger Lesezugriff auf die Merchant API	Lesen Ihres Kontos, Ihrer Lager, Versandarten, Artikel, Bestände und Aktualisierungen zu Lieferungen
ffn.merchant.write	Vollständiger Schreibzugriff auf die Merchant API	Anlegen von Lieferungen, Artikeln und Wareneingängen, nur für Abläufe, die Sie aktiv geschaltet haben

Produktion und Sandbox

JTL betreibt ein Produktionssystem und eine separate Sandbox zum Testen. Laut JTL funktioniert ein OAuth-Client für beide, und die Callback-URL ist dieselbe. Unterschiedlich sind das Konto, mit dem Sie sich anmelden, und das Portal, in dem sich dieses Konto einmal angemeldet haben muss.

	Produktion	Sandbox
FFN-Portal für die erste Anmeldung	fulfillment.jtl-software.com	fulfillment-sandbox.jtl-software.com
JTL-Konto	Ihr echtes Händlerkonto	Ein Sandbox-Konto
Option unter Umgebung im Dialog	Produktion	Sandbox
Daten	Echte Lieferungen und Bestände	Testdaten, getrennt von der Produktion

Jede Option im Dialog zeigt auch die Adresse ihres Portals an. Eine Verbindung bleibt in der Umgebung, in der sie erstellt wurde. Um von der Sandbox in die Produktion zu wechseln, fügen Sie eine neue Verbindung mit der Auswahl Produktion hinzu. Sie können für Tests auch eine separate JTL-App verwenden.

Client-ID und Secret sicher eingeben

• Geben Sie Client-ID und Client-Secret nur in die Felder Client-ID und Client-Secret des Dialogs JTL Fulfillment Network verbinden ein. Balta Labs speichert das Secret verschlüsselt und zeigt es nie wieder an.
• Senden Sie das Client-Secret niemals per E-Mail, Chat oder Support-Ticket und fügen Sie es nicht in gemeinsam genutzte Dokumente ein. Der Support benötigt nur die Client-ID.
• Wenn Sie ein Konto neu verbinden, können Sie beide Felder leer lassen, um die gespeicherten App-Zugangsdaten zu behalten.
• Wenn das Secret offengelegt worden sein könnte, ersetzen Sie es bei JTL. Lässt JTL keine Erneuerung zu, erstellen Sie eine neue App. Verbinden Sie das Konto anschließend mit den neuen Werten neu.

Als Nächstes: JTL mit dem Hub verbinden.