Neu JTL-Wawi DHL Worker – DHL API, DirectJTL, OTTO-Retoure & Auto-Druck – All-in-One

[NikuTRAX]

Hallo zusammen,

ich habe einen kleinen DHL-Worker für JTL-Wawi gebaut, den ich hier neutral zur Verfügung stellen möchte.

Der Worker übernimmt einen CSV-Export aus JTL-Wawi, erzeugt die Sendungen direkt über die DHL Paket API und schreibt anschließend Trackingnummer und Versanddatum direkt in die JTL-Datenbank zurück.

Damit ist kein Versanddatenimport und auch kein automatischer Import in JTL erforderlich.

Der Worker arbeitet dabei unabhängig von JTL Shipping 2.0. Für die eigentliche Versandabwicklung wird keine JTL Shipping 2.0 API und keine JTL-REST-API benötigt.

Die Kommunikation erfolgt im Wesentlichen direkt zwischen:

JTL-Wawi
↓
CSV-Export
↓
DHL-Worker
↓
DHL Paket API
↓
Tracking + Versanddatum direkt zurück nach JTL

Die DHL-Versandabwicklung erfolgt damit unabhängig von der in JTL integrierten Versand-API.

Funktionen​

Unterstützt werden aktuell:

• DHL Paket DE
• DHL Kleinpaket
• DHL Paket International / EU
• OTTO-Versand mit DHL-Retoure
• direkter Tracking-Eintrag in JTL
• automatisches Versanddatum
• optionaler automatischer Labeldruck über separaten Print-Agent
• Schutz gegen Doppelbuchungen
• Sandbox- und Production-Modus

Wichtig: kein Versanddatenimport in JTL​

Bei den verwendeten Versandarten sollte kein Versanddatenimport / Tracking-Import eingerichtet werden.

Auch ein automatischer Import ist nicht notwendig.

Der Ablauf ist:

JTL-Wawi
↓
CSV-Export
↓
DHL-Worker
↓
DHL Paket API
↓
Tracking + Versanddatum direkt zurück nach JTL

Die CSV dient also ausschließlich als Übergabe von JTL an den Worker.

Es findet anschließend kein CSV-Rückimport nach JTL statt.

Kein JTL Shipping 2.0 / keine JTL-REST-API erforderlich​

Der Worker verwendet für die Versandabwicklung nicht JTL Shipping 2.0 und nicht die JTL-REST-API.

Die Versanddaten werden aus dem CSV-Export übernommen und direkt an die DHL Paket API übertragen.

Nach erfolgreicher Erstellung der Sendung werden Trackingnummer und Versanddatum direkt in der JTL-Datenbank aktualisiert.

Verwendet werden damit im Wesentlichen:

• JTL-Wawi CSV-Export
• DHL Paket API
• direkter SQL-Zugriff auf die JTL-Datenbank

Eine zusätzliche JTL-Versand-API ist für diesen Ablauf nicht erforderlich.

DirectJTL​

Nach erfolgreicher DHL-Buchung wird die Trackingnummer direkt in:

tVersand.cIdentCode

geschrieben.

Bei einer OTTO-Retoure zusätzlich in:

tVersand.cEnclosedReturnIdentCode

Das Versanddatum wird ebenfalls gepflegt.

Ist:

tVersand.dVersendet

noch leer, wird der aktuelle Zeitpunkt gesetzt.

Anschließend wird derselbe Wert nach:

tBestellung.dVersandt

übernommen.

Dadurch erscheint das Versanddatum auch in der normalen JTL-Auftragsübersicht.

OTTO​

Für OTTO kann eine eigene Versandart verwendet werden, z. B.:

DHL Otto

Der Worker erzeugt dabei:

Hinweg:

tVersand.cIdentCode

Retoure:

tVersand.cEnclosedReturnIdentCode

Das Retourenlabel wird nicht zusammen mit dem normalen Versandlabel gedruckt.

Die Retouren-Sendungsnummer bleibt trotzdem erhalten und kann von JTL bzw. OTTO verwendet werden.

Print-Agent​

Im Paket befindet sich zusätzlich ein kleiner Print-Agent.

Dieser überwacht den Labelordner und druckt neue DHL-PDFs automatisch über PDF24 auf einen frei konfigurierbaren Drucker.

Druckername, Labelordner und PDF24-Pfad werden separat konfiguriert.

Nach erfolgreichem Druck werden die Dateien archiviert, damit sie beim nächsten Start nicht erneut gedruckt werden.

Retouren-Dateien mit entsprechenden Dateinamen werden vom automatischen Druck ausgeschlossen.

Sicherheitsmechanismen​

Der Worker prüft vor einer Buchung unter anderem:

• PaketRef
• Lieferschein
• Versandart
• vorhandene Trackingnummer
• vorhandenen State

Nach einer erfolgreichen DHL-Buchung wird sofort ein lokaler State gespeichert.

Falls anschließend beispielsweise der SQL-Zugriff fehlschlägt, wird beim nächsten Lauf nicht erneut bei DHL gebucht, sondern nur das fehlende JTL-Update nachgeholt.

Die Datenbankänderungen erfolgen innerhalb einer SQL-Transaktion.

Damit soll verhindert werden, dass bei einem Fehler nach erfolgreicher DHL-Buchung versehentlich eine zweite Sendung erzeugt wird.

Installation​

1. ZIP-Datei entpacken, z. B.:

C:\JTL-DHL\

1. config.example.json nach config.json kopieren.
2. Eigene Daten eintragen:

• DHL API-Zugang
• DHL-Abrechnungsnummern
• SQL-Server
• JTL-Datenbank
• Absenderadresse
• Ordner
• OTTO-Retourenadresse
• OTTO-Retouren-Abrechnungsnummer

1. Zunächst Sandbox verwenden:

"Environment": "Sandbox"

1. JTL-CSV-Export einrichten.
2. Testauftrag erzeugen und Sandbox testen.
3. Erst danach Production-Zugang einrichten.
4. Production zunächst nur im Validierungsmodus testen.
5. Erst nach erfolgreicher Prüfung den automatischen Production-Betrieb aktivieren.

JTL-Versandarten​

Bei den Versandarten, die über den Worker verarbeitet werden, sollte kein zusätzlicher automatischer Versanddatenimport eingerichtet werden.

Insbesondere sollte nicht parallel versucht werden, dieselben Trackingdaten über einen separaten CSV-Import wieder in JTL einzulesen.

Der Worker trägt die Trackingnummer direkt selbst in JTL ein.

Auch ein automatischer Import der erzeugten Trackingdateien ist daher nicht erforderlich.

CSV-Export​

Erwartete Kopfzeile:

PaketRef;Lieferschein;Versandart;Vorname;Nachname;Firma;Adresszusatz;Strasse;Hausnummer;PLZ;Ort;LandISO;Email;Telefon;Mobil;Gewicht

Beispiel:

P1234;1234-001;Versicherter Versand DHL;Max;Mustermann;;;Musterstrasse;1;12345;Musterstadt;DE;;;;0,50

PaketRef entspricht dem jeweiligen kVersand.

Beispiel:

P1234 → kVersand 1234

Enthalten​

Das All-in-One-Paket enthält:

• Server / Worker
• Print-Agent / Client
• Beispielkonfigurationen
• Production-Zugang-Setup
• Sandbox-Startdateien
• Production-Validierung
• Production-Automatik
• CSV-Beispiel
• CSV-Kopfzeile
• README

Technischer Ablauf​

Der komplette Ablauf sieht vereinfacht so aus:

JTL-Wawi erzeugt CSV
↓
Worker erkennt neue CSV
↓
Versanddaten werden geprüft
↓
Sendung wird direkt über die DHL Paket API erzeugt
↓
DHL liefert Label und Trackingnummer
↓
Label wird gespeichert
↓
Trackingnummer wird direkt in tVersand.cIdentCode geschrieben
↓
Versanddatum wird in tVersand.dVersendet gesetzt
↓
Versanddatum wird nach tBestellung.dVersandt übernommen
↓
optional druckt der Print-Agent das Label automatisch

Ein zusätzlicher Versanddatenimport nach JTL ist nicht notwendig.

Hinweis​

Der Worker greift direkt schreibend auf die JTL-Datenbank zu.

Daher bitte unbedingt zuerst:

• Datenbanksicherung erstellen
• Testauftrag verwenden
• Sandbox testen
• SQL-Zugang prüfen
• Production zunächst nur validieren
• erst danach Production freigeben

Der Worker verwendet für die Versandabwicklung nicht JTL Shipping 2.0 und nicht die JTL-REST-API, sondern kommuniziert direkt mit der DHL Paket API.

Die Rückmeldung von Trackingnummer und Versanddatum erfolgt anschließend direkt über die JTL-Datenbank.

Das Ganze ist kein offizielles JTL- oder DHL-Plugin, sondern eine eigene Automatisierung.

Bei Änderungen an der JTL-Datenbankstruktur oder an der DHL API kann eine Anpassung notwendig werden.

Nutzung daher auf eigene Verantwortung und bitte zunächst immer mit Testaufträgen bzw. in der Sandbox prüfen.

Aktueller Stand des Pakets:

v1.13 All-in-One Server + Client

 

[KristinaS]

Tolle Arbeit, Dankeschön. Läuft 🎉 und fühlt sich fast genauso an im Betrieb wie die Shipping 1.0 Anbindung, vielleicht 1-2 Sekunden langsamer. Stört hier aber nicht, weil hier in der Zwischenzeit ohnehin schon die Ware für die nächste Auslieferung zurechtgelegt wird.

Amazon Kunden aufgepasst: Zumindest bei mir wird die Sendungsnummer erst nach Veranlassung der Versanddatenübermittlung an Amazon eingetragen, so dass die erste automatische Übermittlung fehlschlägt. Am Tagesende oder nach Versandschluss daher einmal alle Auslieferung MFN an Amazonkunden im Versandmenü einmal im Block anwählen und die erneute Übertragung der Versanddaten an Amazon veranlassen. Ob es geklappt hat, seht ihr ein paar Minuten später in Eurer Sellercentral Auftragsübersicht. Vielleicht gibts dafür auch noch eine automatische Lösung? Dann her damit, ich habe noch keine gefunden.

Um es Euch ein wenig einfacher zu machen, gibt es von mir noch
- die Exportvorlage für den JTL-Versand-Export zum DHL-Worker
=> siehe unten angehängte zip-Datei
- den Codeblock für die Datei JTL-DHL-Worker.ps1 für die Aktivierung des Zusatzservices "Filial-Routing" zum DHL Kleinpaket (wer es braucht, kann es auch für Pakete auf gleiche Weise ergänzen) und "Premium" zur Warenpost International:
(ersetze in deiner Funktion den Bereich ab $shipment = [ordered]@{ bis einschließlich der drei schließenden Klammern darunter durch diesen Code):

$shipment = [ordered]@{
product = $Product
billingNumber = $Billing
refNo = ([string]$Row.Lieferschein)
shipper = $shipper
consignee = (Build-Consignee $Row)
details = [ordered]@{
weight = [ordered]@{
uom = 'kg'
value = $WeightKg
}
}
}

# DHL-Zusatzservices je Produkt
switch ($Product) {
'V62KP' {
$recipientEmail = ([string]$Row.Email).Trim()

if ([string]::IsNullOrWhiteSpace($recipientEmail)) {
throw "Filialrouting für DHL Kleinpaket benötigt die Empfänger-E-Mail-Adresse aus der CSV."
}

$shipment['services'] = [ordered]@{
parcelOutletRouting = $recipientEmail
}
}

'V66WPI' {
$shipment['services'] = [ordered]@{
premium = $true
}
}
}

- den zusätzlichen Codeblock für die Datei JTL-DHL-Worker.ps1 zur Integration von Warenpost International Premium (nur EU) (falls jemand nur einfache Warenpost International (EU) benötigt, das Premium weglassen und den Codeblock für den zusätzlichen Service "Premium" (vorangegangener Block) nicht einbauen):

'Warenpost International Premium' {
if ($country2 -eq 'DE') {
throw "Versandart 'Warenpost International Premium' ist für EU-Ausland gedacht, Ziel ist aber Deutschland."
}
if (-not (Test-IsEuCountry $country2)) {
throw "Versandart 'Warenpost International Premium' wird nur für EU-Länder automatisch gebucht. Ziel '$country2' bleibt für Zoll/International bewusst manuell."
}
if ($WeightKg -gt 1) {
throw "DHL Paket International Premium darf in diesem Worker höchstens 1 kg wiegen. CSV: $WeightKg kg."
}
return @{
Product = 'V66WPI'
Name = 'Warenpost International Premium'
Country = $country2
IsOtto = $false
}
}

Allen gutes Gelingen!

MfG Kristina