{"id":55000333,"date":"2022-12-01T00:00:00","date_gmt":"2023-03-02T17:03:26","guid":{"rendered":"http:\/\/access-im-unternehmen.aix-dev.de\/aiu\/?p=333"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-30T00:00:00","slug":"DHLPaketlabel_per_VBA_erstellen","status":"publish","type":"post","link":"https:\/\/vbentwickler.de\/DHLPaketlabel_per_VBA_erstellen\/","title":{"rendered":"DHL-Paketlabel per VBA erstellen"},"content":{"rendered":"

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.<\/b><\/p>\n

Voraussetzung: Geschäftskundenkonto bei DHL<\/h2>\n

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):<\/p>\n

\"Hier<\/p>\n

Bild 1: Hier gelangst Du zum Geschäftskundenbereich von DHL.<\/span><\/b><\/p>\n

https:\/\/www.dhl.de<\/pre>\n
Entwickler-Konto bei DHL erstellen<\/h2>\n
Wenn Du das für die Umsetzung benötigte Entwicklerkonto bei DHl erstellen möchtest, folgst Du diesem Link:<\/p>\n
https:\/\/entwickler.dhl.de\/<\/pre>\n
Hier findest Du im unteren Bereich einen Link mit dem Text Registrieren Sie sich jetzt<\/b>. 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.<\/p>\n
Übersicht der Dienste<\/h2>\n
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<\/b>. Nach einem Klick auf den entsprechenden Link landen wir direkt auf der Seite Geschäftskundenversand API<\/b>, 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 <\/b>zu übergeben.<\/p>\n
\"Bereiche<\/p>\n
Bild 2: Bereiche im Entwicklerportal<\/span><\/b><\/p>\n
Anlegen einer Applikation<\/h2>\n
Bevor wir richtig einsteigen können, legen wir eine Applikation an. Das erledigen wir im Bereich Freigabe & Betrieb<\/b> der Webseite (siehe Bild 3). Hier tragen wir den technischen Namen, den Namen und eine Beschreibung ein.<\/p>\n
\"Anlegen<\/p>\n
Bild 3: Anlegen einer neuen Anwendung<\/span><\/b><\/p>\n
Außerdem fügen wir alle Operationen hinzu, die wir verwenden wollen. In diesem Fall klappen wir den Bereich Geschäftskundenversand\/Business customer shipment <\/b>auf und selektieren dort alle Einträge. Anschließend schließen wir das Anlegen der Applikation mit einem Klick auf Applikation speichern <\/b>ab.<\/p>\n
Authentifizierung<\/h2>\n
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:<\/p>\n
https:\/\/cig.dhl.de\/services\/sandbox\/soap<\/pre>\n
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.<\/p>\n
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 <\/b>der Webseite, also an der gleichen Stelle, an der wir auch die Applikation erstellt haben.<\/p>\n
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.<\/p>\n
Die Geschäftskundenversand-API<\/h2>\n
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<\/b>.<\/p>\n
Fingerübung: Version abfragen<\/h2>\n
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.<\/p>\n
Die Funktion heißt VersionErmitteln <\/b>und erwartet die beiden Parameter intMajor <\/b>und intMinor<\/b>, welche beides Rückgabeparameter sind, also die als leere Variablen übergeben und von der Funktion gefüllt werden (siehe Listing 1).<\/p>\n
Public Function <\/span>VersionErmitteln(intMajor As Integer<\/span>, intMinor As Integer<\/span>)\r\n     Dim <\/span>objXMLRequest As <\/span>MSXML2.DOMDocument60\r\n     Dim <\/span>objXMLResponse As <\/span>MSXML2.DOMDocument60\r\n     Dim <\/span>objMinor As <\/span>MSXML2.IXMLDOMNode\r\n     Dim <\/span>objMajor As <\/span>MSXML2.IXMLDOMNode\r\n     Dim <\/span>strRequest As String<\/span>\r\n     strRequest = \"<soapenv:Envelope xmlns:soapenv=\"\"http:\/\/schemas.xmlsoap.org\/soap\/envelope\/\"\" \" _\r\n         & \"xmlns:ns=\"\"http:\/\/dhl.de\/webservices\/businesscustomershipping\/3.0\"\">\" & vbCrLf<\/span>\r\n     strRequest = strRequest & \"   <soapenv:Body>\" & vbCrLf<\/span>\r\n     strRequest = strRequest & \"      <ns:Version>\" & vbCrLf<\/span>\r\n     strRequest = strRequest & \"         <majorRelease>?<\/majorRelease>\" & vbCrLf<\/span>\r\n     strRequest = strRequest & \"         <minorRelease>?<\/minorRelease>\" & vbCrLf<\/span>\r\n     strRequest = strRequest & \"         <build>?<\/build>\" & vbCrLf<\/span>\r\n     strRequest = strRequest & \"      <\/ns:Version>\" & vbCrLf<\/span>\r\n     strRequest = strRequest & \"   <\/soapenv:Body>\" & vbCrLf<\/span>\r\n     strRequest = strRequest & \"<\/soapenv:Envelope>\" & vbCrLf<\/span>\r\n     Set<\/span> objXMLRequest = New<\/span> MSXML2.DOMDocument60\r\n     If <\/span>Not<\/span> objXMLRequest.loadXML(strRequest) Then<\/span>\r\n         Debug.Print<\/span> objXMLRequest.parseError.Line, objXMLRequest.parseError.linepos, objXMLRequest.parseError.reason, _\r\n             objXMLRequest.parseError.errorCode\r\n     Else<\/span>\r\n         If <\/span>RequestSandbox(strRequest, objXMLResponse) Then<\/span>\r\n             Set<\/span> objMinor = objXMLResponse.selectSingleNode(\"\/\/minorRelease\")\r\n             If <\/span>Not<\/span> objMinor Is Nothing Then<\/span>\r\n                 intMinor = objMinor.nodeTypedValue\r\n             End If<\/span>\r\n             Set<\/span> objMajor = objXMLResponse.selectSingleNode(\"\/\/majorRelease\")\r\n             If <\/span>Not<\/span> objMajor Is Nothing Then<\/span>\r\n                 intMajor = objMajor.nodeTypedValue\r\n             End If<\/span>\r\n         End If<\/span>\r\n     End If<\/span>\r\nEnd Function<\/span><\/pre>\n
Listing 1: Prozedur zum Zusammenstellen einer Abfrage der aktuellen Version<\/span><\/b><\/p>\n
Sie deklariert zwei Variablen des Typs MSXML2.DOMDocument60<\/b>, womit wir gleich bei einer Voraussetzung landen – dem Hinzufügen eines Verweises auf die Bibliothek Microsoft XML, v6.0<\/b>. Dies erledigen wir im Dialog Verweise<\/b>, den wir vom VBA-Editor der verwendeten Anwendung aus mit dem Menübefehl Extras|Verweise <\/b>öffnen. Die benötigte Bibliothek fügen wir wie in Bild 4 hinzu. Anschließend können wir die enthaltenen Klassen, Methoden und Eigenschaften im VBA-Editor unter Verwendung von IntelliSense eingeben.<\/p>\n
\"Hinzufügen<\/p>\n
Bild 4: Hinzufügen eines Verweises auf die XML-Bibliothek<\/span><\/b><\/p>\n
Neben diesen beiden Objektvariablen nutzen wir zwei weitere namens objMinor <\/b>und objMajor<\/b>, jeweils mit dem Typ MSXML2.IXMLDOMNode<\/b>, um Elemente mit Versionsangabe zu referenzieren. Die Funktion stellt nun den Code der Anfrage zusammen, die wir an die API von DHL schicken wollen. Zusammengefasst sieht diese in der Variablen strRequest <\/b>erfasste Zeichenkette wie folgt aus:<\/p>\n
<soapenv:Envelope         xmlns:soapenv=\"http:\/\/schemas.xmlsoap.org\/soap\/        envelope\/\" xmlns:ns=\"http:\/\/dhl.de\/webservices\/        businesscustomershipping\/3.0\">\r\n     <soapenv:Body>\r\n         <ns:Version>\r\n             <majorRelease>?<\/majorRelease>\r\n             <minorRelease>?<\/minorRelease>\r\n             <build>?<\/build>\r\n         <\/ns:Version>\r\n     <\/soapenv:Body>\r\n<\/soapenv:Envelope><\/pre>\n
Nach dem Zusammenstellen dieser Zeichenkette erstellt die Funktion ein neues Objekt des Typs DOMDocument60 <\/b>und ruft dessen Funktion loadXML <\/b>auf. Dieser übergibt sie den Inhalt von strRequest <\/b>und füllt das Objekt aus objXMLRequest <\/b>damit mit der XML-Anfrage. Die loadXML<\/b>-Funktion prüft gleichzeitig die Gültigkeit des übergebenen XML-Dokuments und gibt eine Meldung im Direktbereich aus, sollte dieses nicht gültig sein.<\/p>\n
Anderenfalls ruft sie die Funktion Request <\/b>auf und übergibt dieser das gefüllte Objekt objXMLRequest <\/b>sowie das noch leere Objekt objXMLResponse<\/b>. Diese Funktion beschreiben wir gleich im Anschluss. Wenn die Funktion den Wert True <\/b>zurückgibt, die Abfrage also erfolgreich war, dann ist objXMLResponse<\/b> anschließend mit einem XML-Dokument wie dem folgenden gefüllt:<\/p>\n
<soapenv:Envelope \r\n         xmlns:bus=\"http:\/\/dhl.de\/webservices\/\r\n         businesscustomershipping\/3.0\" \r\n         xmlns:soapenv=\"http:\/\/schemas.xmlsoap.org\/soap\/\r\n         envelope\/\">\r\n     <soapenv:Header\/>\r\n     <soapenv:Body>\r\n         <bus:GetVersionResponse>\r\n             <bus:Version>\r\n                 <majorRelease>3<\/majorRelease>\r\n                 <minorRelease>0<\/minorRelease>\r\n                 <build>0<\/build>\r\n             <\/bus:Version>\r\n         <\/bus:GetVersionResponse>\r\n     <\/soapenv:Body>\r\n<\/soapenv:Envelope><\/pre>\n
Die Aufgabe lautet nun noch, den Inhalt der beiden Elemente majorRelease <\/b>und minorRelease <\/b>auszulesen und in die Rückgabeparameter zu schreiben. Das erledigen wir, indem wir mit der Funktion selectSingleNode <\/b>nach den entsprechenden Elementen suchen. Finden wir diese, lesen wir daraus über die Eigenschaft nodeTypedValue <\/b>die enthaltenen Werte aus. Diese füllen wir in die Rückgabeparameter intMinor <\/b>und intMajor<\/b>.<\/p>\n
Diese Funktion rufen wir beispielsweise mit der folgenden Prozedur auf:<\/p>\n
Public Sub <\/span>Test_VersionErmitteln()\r\n     Dim <\/span>intMajor As Integer<\/span>\r\n     Dim <\/span>intMinor As Integer<\/span>\r\n     VersionErmitteln intMajor, intMinor\r\n     Debug.Print<\/span> \"Version \" & intMajor & \".\" & intMinor\r\nEnd Sub<\/span><\/pre>\n
Die Request-Funktion<\/h2>\n
Die eigentliche Arbeit beim Aufruf der DHL-API übernimmt die Funktion RequestSandbox<\/b> (siehe Listing 2). Diese nimmt über den Parameter strRequest <\/b>den Aufruf entgegen und soll den Rückgabeparameter objXMLResponse <\/b>mit dem DOMDocument60<\/b>-Objekt mit der Antwort füllen. Dieses erstellt die Funktion mit dem New<\/b>-Schlüsselwort zunächst neu. Außerdem erstellt sie ein Objekt des Typs XMLHTTP60 <\/b>und referenziert es mit der Objektvariablen objXMLHTTP<\/b>. Hier kommt nun eine Konstante ins Spiel, die wir im Kopf des Moduls deklarieren und mit der weiter oben angegebenen URL für den Zugriff auf die API in der Sandbox-Version füllen – also mit der URL für unsere Tests der API:<\/p>\n
Public Function <\/span>RequestSandbox(strRequest As String<\/span>, objXMLResponse As <\/span>MSXML2.DOMDocument60) As Boolean<\/span>\r\n     Dim <\/span>strURL As String<\/span>\r\n     Dim <\/span>objXMLHTTP As <\/span>MSXML2.XMLHTTP60\r\n     Set<\/span> objXMLHTTP = New<\/span> MSXML2.XMLHTTP60\r\n     Set<\/span> objXMLResponse = New<\/span> MSXML2.DOMDocument60\r\n     With<\/span> objXMLHTTP\r\n         .Open \"post\", cStrURLBase, False<\/span>\r\n         .setRequestHeader \"Content-Type\", \"text\/xml; charset=utf-8\"\r\n         .setRequestHeader \"Content-Length\", Len<\/span>(strRequest)\r\n         .setRequestHeader \"Authorization\", \"Basic \" + Base64Encode(strUserSandbox + \":\" + strPasswordSandbox)\r\n         .send strRequest\r\n         Select Case <\/span>.status\r\n             Case <\/span>200\r\n                 Request = True<\/span>\r\n                 objXMLResponse.loadXML .responseText\r\n             Case Else<\/span>\r\n                 MsgBox<\/span> \"Fehler beim Request:\" & vbCrLf<\/span> & .statusText\r\n         End Select<\/span>\r\n     End With<\/span>\r\nEnd Function<\/span><\/pre>\n
Listing 2: Die Request-Funktion zum Durchführen eines API-Aufrufs<\/span><\/b><\/p>\n
Public <\/span>Const cStrURLBase As String<\/span> = _\r\n     \"https:\/\/cig.dhl.de\/services\/sandbox\/soap\"<\/pre>\n
Diese übergeben wir als zweiten Parameter der Open<\/b>-Methode von objXMLHTTP<\/b>. Der erste Parameter lautet post <\/b>und bedeutet, dass wir später mit der send<\/b>-Methode noch Informationen senden statt diese an die URL anzuhängen.<\/p>\n
Danach stellen wir drei Header ein, zunächst Content-Type <\/b>und Content-Length<\/b>. Der erste gibt an, dass wir mit Daten im Format text\/xml <\/b>mit dem Zeichensatz utf-8 <\/b>arbeiten. Der zweite legt die Länge des übermittelten XML-Dokuments fest. Der dritte Header nimmt die Zugangsdaten auf. Diese speichern wir in Form entsprechender Konstanten wieder im Kopf des Moduls mdlDHL<\/b>. Die Konstanten sehen wie folgt aus:<\/p>\n
Public <\/span>Const strUserSandbox As String<\/span> = \"[EntwicklerID]\"\r\nPublic <\/span>Const strPasswordSandbox As String<\/span> = \"[Kennwort]\"<\/pre>\n
Für strUserSandbox <\/b>geben wir die Entwickler-ID aus dem Entwicklerportal an, die wir unter folgendem Link finden:<\/p>\n
https:\/\/entwickler.dhl.de\/group\/ep\/mein-konto<\/pre>\n
Für strPasswordSandbox <\/b>hinterlegen wir das Kennwort für die Anmeldung am Entwicklerportal. Die Anmeldedaten werden in einer durch einen Doppelpunkt getrennten Zeichenkette zusammengefasst und Base64-kodiert.<\/p>\n
Dann stellen wir diesem Ausdruck den Text Basic <\/b>und ein Leerzeichen voran und übergeben dies für den Header Authorization<\/b>. Schließlich ruft die Funktion die send<\/b>-Methode auf und übergibt dieser als Parameter die in strRequest <\/b>gespeicherte XML-Anfrage.<\/p>\n
Nachdem diese ausgeführt wurde, können wir das Ergebnis in Form der Eigenschaft status <\/b>auswerten. Der Wert 200 <\/b>entspricht dem Ergebnis OK<\/b>. In diesem Fall stellen wir das Ergebnis der Funktion auf True <\/b>ein und lesen den Inhalt der Eigenschaft responseText<\/b>, die von der API gefüllt wurde, mit der loadXML<\/b>-Methode in das DOMDocument60<\/b>-Objekt objXMLResponse <\/b>ein. Anderenfalls gibt die Funktion den Statustext mit der Fehlermeldung in einem Meldungsfenster aus.<\/p>\n
Benutzerdaten manuell eingeben<\/h2>\n
Wenn Du die Benutzerdaten nicht im Code speichern möchtest, kannst Du die Übergabe der dritten Header-Zeile auch weglassen. Dann erscheint eine Meldung wie in Bild 5, um die Zugangsdaten abzufragen.<\/p>\n
\"Manuelle<\/p>\n
Möchten Sie weiterlesen? Dann lösen Sie Ihr Ticket!<\/span>
\nHier geht es zur Bestellung des Jahresabonnements des Magazins Visual Basic Entwickler<\/strong>:<\/span>
\nZur Bestellung ...<\/a><\/span>
\nDanach greifen Sie sofort auf alle rund 200 Artikel<\/strong> unseres Angebots zu - auch auf diesen hier!<\/span>
\nOder haben Sie bereits Zugangsdaten? Dann loggen Sie sich gleich hier ein:<\/span><\/p>\n<\/div>\n\n\t\n\t
\n\n\t\t\n\t\t