Lies in den Artikel rein und unten bekommst Du ein unschlagbares Angebot!
Beim Versand von Paketen kommt recht oft DHL zum Einsatz. Die einfachste Form der computergestützten Erstellung von Paketlabeln ist dabei das Anmelden bei DHL und das Erstellen eines Labels durch Eingabe der Adressdaten und Bezahlung auf der Webseite. Etwas mehr Möglichkeiten bietet ein Geschäftskundenkonto beim Anbieter DHL. Hier können wir einen Schritt weitergehen und die Adressdaten beispielsweise per CSV übermitteln. Noch schöner wäre es, wenn wir von der jeweiligen Anwendung aus – ob es sich nun um eine Access-Datenbank, eine Excel-Tabelle oder sogar Outlook handelt – direkt per Mausklick ein Paketlabel zur Sendung eines Pakets an den jeweiligen Kontakt erstellen könnten, dass dann beispielsweise als PDF auf unserem Rechner landet. Wie das gelingt, zeigen wir im vorliegenden Artikel.
Voraussetzung: Geschäftskundenkonto bei DHL
Bevor Du weiter in diesen Artikel einsteigst, hier ein wichtiger Hinweis: Um die Beispiele in der Praxis einzusetzen, benötigst Du ein Geschäftskundenkonto bei DHL – beziehungsweise der Kunde, für den Du diese Anwendung erstellst. Zum Ausprobieren der Beispiele reicht ein einfaches Entwicklerkonto bei DHL aus. Wie Du ein Geschäftskundenkonto erstellst, wollen wir hier nicht demonstrieren – aber zumindest den Weg dorthin. Dazu folgst Du diesem Link und klickst dann auf Geschäftskunden (siehe Bild 1):
Bild 1: Hier gelangst Du zum Geschäftskundenbereich von DHL.
https://www.dhl.de
Entwickler-Konto bei DHL erstellen
Wenn Du das für die Umsetzung benötigte Entwicklerkonto bei DHl erstellen möchtest, folgst Du diesem Link:
https://entwickler.dhl.de/
Hier findest Du im unteren Bereich einen Link mit dem Text Registrieren Sie sich jetzt. Dieser führt bereits zur Registrierungsseite, wo zunächst nur eine Entwickler-ID, die E-Mail sowie ein Kennwort einzugeben sind – nebst Bestätigung von AGB und Datenschutzerklärung.
Übersicht der Dienste
Nach der Registrierung des Entwicklerkontos und der ersten Anmeldung sehen wir die zur Verfügung stehenden Dienste (siehe Bild 2). Uns interessiert als Erstes der Geschäftskundenversand. Nach einem Klick auf den entsprechenden Link landen wir direkt auf der Seite Geschäftskundenversand API, die erste Informationen für uns bereithält. Hier finden wir zum Zeitpunkt der Erstellung des Artikels die Information, dass es eine neue Version mit der Nummer 3.3 mit neuer Fehlerbehandlung gibt. Und da dies beim Zugriff auf APIs über das Internet immer besonders wichtig ist, wollen wir direkt mit dieser Version einsteigen. Dazu erhalten wir den wichtigen Tipp, die gewünschte Version im XML-Block namens Version zu übergeben.
Bild 2: Bereiche im Entwicklerportal
Anlegen einer Applikation
Bevor wir richtig einsteigen können, legen wir eine Applikation an. Das erledigen wir im Bereich Freigabe & Betrieb der Webseite (siehe Bild 3). Hier tragen wir den technischen Namen, den Namen und eine Beschreibung ein.
Bild 3: Anlegen einer neuen Anwendung
Außerdem fügen wir alle Operationen hinzu, die wir verwenden wollen. In diesem Fall klappen wir den Bereich Geschäftskundenversand/Business customer shipment auf und selektieren dort alle Einträge. Anschließend schließen wir das Anlegen der Applikation mit einem Klick auf Applikation speichern ab.
Authentifizierung
Nach dem Anlegen der Applikation können wir zum nächsten Menüpunkt springen und uns die Informationen rund um die Authentifizierung ansehen. Wichtig ist hier für uns die Kenntnis der sogenannten Endpunkte für Test und Entwicklung sowie später für die produktive Nutzung. Vor dieser steht allerdings noch die Freigabe. Wir wollen den Zugriff per SOAP nutzen, also können wir uns den folgenden Endpunkt für die Tests mit der Sandbox merken:
https://cig.dhl.de/services/sandbox/soap
Außerdem erhalten wir hier noch wichtige Informationen über die zu verwendenden Zugangsdaten. Für den Testzugriff auf die Sandbox verwenden wir dabei als Benutzername die zuvor festgelegte Entwickler-ID und als Kennwort das für das Entwicklerkonto festgelegte Kennwort.
Später, wenn wir die Freigabe der Anwendung erhalten haben, können wir als Benutzernamen den Namen der Anwendung angeben und ein dafür festgelegtes Token. Beides erhalten wir im Bereich Freigabe & Betrieb der Webseite, also an der gleichen Stelle, an der wir auch die Applikation erstellt haben.
Neben den Informationen über die Authentifizierung erhalten wir auch noch den wichtigen Hinweis, dass wir für den produktiven Betrieb im Header noch die jeweilige Aktion angeben müssen – dazu kommen wir später noch.
Die Geschäftskundenversand-API
Danach folgen im Menü die einzelnen Bereiche, die wir programmieren können. Wie weiter oben festgelegt, wollen wir den Geschäftskundenversand automatisieren und wechseln daher zum Menü Geschäftskundenversand.
Fingerübung: Version abfragen
Bevor wir uns an die Programmierung der Erstellung von Versandlabeln begeben, wollen wir zum Warmmachen die aktuell verfügbar maximale Version abfragen. Dazu erstellen wir als Erstes eine Funktion, die ein entsprechendes SOAP-Dokument zusammenstellt und dieses dann an eine Funktion zum Senden der Anfrage an die API schickt.
Die Funktion heißt VersionErmitteln und erwartet die beiden Parameter intMajor und intMinor, welche beides Rückgabeparameter sind, also die als leere Variablen übergeben und von der Funktion gefüllt werden (siehe Listing 1).
Public Function VersionErmitteln(intMajor As Integer, intMinor As Integer) Dim objXMLRequest As MSXML2.DOMDocument60 Dim objXMLResponse As MSXML2.DOMDocument60 Dim objMinor As MSXML2.IXMLDOMNode Dim objMajor As MSXML2.IXMLDOMNode Dim strRequest As String strRequest = "<soapenv:Envelope xmlns:soapenv=""http://schemas.xmlsoap.org/soap/envelope/"" " _ & "xmlns:ns=""http://dhl.de/webservices/businesscustomershipping/3.0"">" & vbCrLf strRequest = strRequest & " <soapenv:Body>" & vbCrLf strRequest = strRequest & " <ns:Version>" & vbCrLf strRequest = strRequest & " <majorRelease>?</majorRelease>" & vbCrLf strRequest = strRequest & " <minorRelease>?</minorRelease>" & vbCrLf strRequest = strRequest & " <build>?</build>" & vbCrLf strRequest = strRequest & " </ns:Version>" & vbCrLf strRequest = strRequest & " </soapenv:Body>" & vbCrLf strRequest = strRequest & "</soapenv:Envelope>" & vbCrLf Set objXMLRequest = New MSXML2.DOMDocument60 If Not objXMLRequest.loadXML(strRequest) Then Debug.Print objXMLRequest.parseError.Line, objXMLRequest.parseError.linepos, objXMLRequest.parseError.reason, _ objXMLRequest.parseError.errorCode Else If RequestSandbox(strRequest, objXMLResponse) Then Set objMinor = objXMLResponse.selectSingleNode("//minorRelease") If Not objMinor Is Nothing Then intMinor = objMinor.nodeTypedValue End If Set objMajor = objXMLResponse.selectSingleNode("//majorRelease") If Not objMajor Is Nothing Then intMajor = objMajor.nodeTypedValue End If End If End If End Function
Listing 1: Prozedur zum Zusammenstellen einer Abfrage der aktuellen Version