DHL Web Service Dokumentation Online-Retoure Version 2.0



Ähnliche Dokumente
Version Deutsch In diesem HOWTO wird beschrieben wie Sie Ihren Gästen die Anmeldung über eine SMS ermöglichen.

ACCOUNTINFO 1.01 VERWENDEN DER ACCOUNTINFO-SCHNITTSTELLE ABFARGE VON ACCOUNT-INFORMATIONEN IN ECHTZEIT 02. MÄRZ 2010

Wie richten Sie Ihr Web Paket bei Netpage24 ein

Clientkonfiguration für Hosted Exchange 2010

Sichere Kommunikation mit Ihrer Sparkasse

Zur Bestätigung wird je nach Anmeldung (Benutzer oder Administrator) eine Meldung angezeigt:

Beschaffung mit. Auszug aus dem Schulungshandbuch: Erste Schritte im UniKat-System

Wenn Sie das T-Online WebBanking das erste Mal nutzen, müssen Sie sich zunächst für den Dienst Mobiles Banking frei schalten lassen.

Einrichten eines Postfachs mit Outlook Express / Outlook bis Version 2000

COSIDNS 2 ISPconfig3. Version 0.1 ( )

Kurzinformation Zugang zur NOVA für dezentrale Administratoren

Anleitung BFV-Widget-Generator

FritzCall.CoCPit Schnelleinrichtung

Verschlüsselung

Virtueller Seminarordner Anleitung für die Dozentinnen und Dozenten

Sichere Kommunikation mit Ihrer Sparkasse

Inhalt. meliarts. 1. Allgemeine Informationen Administration Aufruf Das Kontextmenü Vorlagen...

SharePoint-Migration.docx

PayPal API Zugang aktivieren und nutzen Version / Datum V 1.5 / a) Aktivierung auf der PayPal Internetseite. 1 von 7

BüroWARE Exchange Synchronisation Grundlagen und Voraussetzungen

DHL Online Retoure - Magento Extension zur Erstellung der Retouren-Labels durch den Kunden im Frontend

Einrichtung eines -konto mit Outlook Express

Partnerportal Installateure Registrierung

Benutzeranleitung Superadmin Tool

Kurzanleitung zum Einrichten von konten für Outlook Express 6

Schritt 2: Konto erstellen

THUNDERBIRD. Vorbereitende Einstellungen auf signaturportal.de für die Nutzung von Thunderbird

Anleitung für Kunden zum Umgang mit verschlüsselten s von der LASA Brandenburg GmbH

Maileinstellungen Outlook

teischl.com Software Design & Services e.u. office@teischl.com

Anbindung an easybill.de

VVA Webservice Online Lieferbarkeits-Abfrage

SBB Schulung für digitale Fahrplanabfrage und Ticketkäufe.

Anleitung für die Einrichtung weiterer Endgeräte in 4SELLERS SalesControl

Internationales Altkatholisches Laienforum

Frankieren in Microsoft Word mit dem E Porto Add in der Deutschen Post

Anleitung für die Lohnmeldung via ELM-Standard mittels PartnerWeb

Mediumwechsel - VR-NetWorld Software

Benutzerhandbuch. Leitfaden zur Benutzung der Anwendung für sicheren Dateitransfer.

S TAND N OVEMBE R 2012 HANDBUCH DUDLE.ELK-WUE.DE T E R M I N A B S P R A C H E N I N D E R L A N D E S K I R C H E

Software WISO Hausverwalter 2014 Datenübernahme aus WISO Mein Geld Version / Datum V 1.0 /

Version Deutsch

Ihre Interessentendatensätze bei inobroker. 1. Interessentendatensätze

Aktivieren Sie die Checkbox um von jedem Mail eine Kopie an den -absender (gemäss Einstellungen Absender) zu senden.

Aufruf der Weboberflache des HPM- Warmepumpenmanagers aus dem Internet TIPPS

Anleitungen zum KMG- -Konto

Die hierzu benötigten Zugangsinformationen (ausgenommen Ihr persönliches Kennwort) finden Sie in der Tabelle unterhalb dieses Textes.

Outlook einrichten über POP3

Intranet Moodle

KURZANLEITUNG MSDAS DMS SYSTEM - SILVERDAT II SCHNITTSTELLE

Hilfedatei der Oden$-Börse Stand Juni 2014

Sparkasse Vogtland. Secure Datensicherheit im Internet. Kundenleitfaden. Sparkasse Vogtland. Kundeninformation Secure 1

Um ein solches Dokument zu erzeugen, muss eine Serienbriefvorlage in Word erstellt werden, das auf die von BüroWARE erstellte Datei zugreift.

2. Die eigenen Benutzerdaten aus orgamax müssen bekannt sein

Updatebeschreibung JAVA Version 3.6 und Internet Version 1.2

FTP-Server einrichten mit automatischem Datenupload für

.htaccess HOWTO. zum Schutz von Dateien und Verzeichnissen mittels Passwortabfrage

Anleitung zum erfassen von Last Minute Angeboten und Stellenangebote

Einrichten des Elektronischen Postfachs

Erste Schritte ANLEITUNG Deutsche Sportausweis Vereinsverwaltung Schnittstelle zum Portal des Deutschen Sportausweises unter

So empfangen Sie eine verschlüsselte von Wüstenrot

Anleitung öffentlicher Zugang einrichten

crm-now/ps Webforms Webdesigner Handbuch Erste Ausgabe

PartnerWeb. Anleitung. Personaladministration online erledigen. Telefon:

S Sparkasse Elektronisches Postfach

Anleitung mtan (SMS-Authentisierung) mit SSLVPN.TG.CH

Daten Sichern mit dem QNAP NetBak Replicator 4.0

proles-login. Inhalt [Dokument: L / v1.0 vom ]

Einrichtung von StarMoney 9.0 für HBCI mit USB-Stick

Anleitung zur Installation von SFirm 3.1 inklusive Datenübernahme

Die Volljährigkeitsprüfung in [:lo.pro:]

Bedienung des Web-Portales der Sportbergbetriebe

Version NotarNet Bürokommunikation

Bedienungsanleitung. Matthias Haasler. Version 0.4. für die Arbeit mit der Gemeinde-Homepage der Paulus-Kirchengemeinde Tempelhof

ZEUS Energiebuchhaltung Salzburg Automatische Zählerstandanlieferung: -Schnittstelle

einrichtung in den kaufmännischen Programmen der WISO Reihe

Leitfaden Installation des Cisco VPN Clients

DELFI. Benutzeranleitung Dateiversand für unsere Kunden. Grontmij GmbH. Postfach Bremen. Friedrich-Mißler-Straße Bremen

oder ein Account einer teilnehmenden Einrichtung also

Abschluss und Kündigung eines Vertrages über das Online-Portal der Netzgesellschaft Düsseldorf mbh

Kurzanleitung. Brandschutzbeauftragte Weboberfläche. Version: 2.0

Für die Einrichtung des elektronischen Postfachs melden Sie sich wie gewohnt in unserem Online-Banking auf an.

Schützen Sie sich vor Datenkriminalität mit der sicheren .

Grundlagen 4. Microsoft Outlook 2003 / 2007 / Apple Mail (ab Version 4.0) 9. Outlook 2011 für Mac 10. IOS (iphone/ipad) 12

Melde- und Veröffentlichungsplattform Portal (MVP Portal) Hochladen einer XML-Datei

Benutzerhandbuch - Elterliche Kontrolle

Kommunikations-Management

Shellfire PPTP Setup Windows 7

1) Klicken Sie in der Menüleiste auf "Extras" -> " -Konten".

Anleitung: DynDNS-Adresse beantragen und einrichten

Aufruf der Buchungssystems über die Homepage des TC-Bamberg

myreport Benutzerhandbuch Active Tracing 3.1 Volle Transparenz Durchgehende Sendungsverfolgung und Status Reporte

vorab noch ein paar allgemeine informationen zur d verschlüsselung:

Hochschulrechenzentrum

Sicherer Mailversand des Referats Automatisiertes Auskunftsverfahren (IS14 der Bundesnetzagentur)

Enterprise Applikation Integration und Service-orientierte Architekturen. 09 Simple Object Access Protocol (SOAP)

INHALTSVERZEICHNIS Allgemeine Beschreibung... 3 Verwendung der Webseite... 4 Abbildungsverzeichnis... 12

Transkript:

DHL Web Service Dokumentation Online-Retoure Version 2.0 2010 Deutsche Post DHL

Inhaltsverzeichnis Inhaltsverzeichnis... 2 1 Willkommen beim DHL Web Service für Online-Retouren... 3 1.1 Über das Dokument... 3 1.2 Technischer Überblick... 3 1.2.1 Systemvoraussetzungen... 4 1.2.2 Benötigter Zugang... 4 1.3 Fachlicher Hintergrund die Vollintegration in Ihre Versandhandelsseite... 4 1.3.1 Vorteile... 6 1.3.2 Mögliche Varianten der Lösung... 6 1.4 Rückmeldung und Unterstützung... 6 2 Kurzanleitung: In sechs Schritten zum Retouren-Label... 7 2.1 Schritt 1: Retourenportal mit Empfangsadresse einrichten... 7 2.2 Schritt 2: Den Client aufsetzen... 8 2.3 Schritt 3: Kommunikation einrichten... 8 2.3.1 Web Service Kommunikation auf der Basis von SOAP... 8 2.4 Schritt 4: Benutzer mit ausreichenden Berechtigungen erstellen... 9 2.5 Schritt 5: Beispiel Code übernehmen und testen... 9 2.6 Schritt 6: Den Web Service zur Online-Retoure auf Ihrer Webseite aktivieren... 9 3 API Call Referenz...10 3.1 BooklabelRequest - Eingabe Parameter...11 3.2 BookLabelResponse - Ausgabe Parameter...12 3.3 Fehlerverhalten...12 3.3.1 Fehlertypen...12 4 Anhang Hilfreiche Quellen...14 4.1 XML und Web Services...14 4.2 Code Beispiel...15 4.2.1 SOAP POST Online-Retoure...15 4.2.2 SOAP Response Online-Retoure...15 Abbildungsverzeichnis Abbildung 1: Fiktives Beispiel einer Retouren-Maske auf Webseite... 5 Abbildung 2: Beispiel eines integrierten Aufrufs eines Retouren-Labels... 5 Tabellenverzeichnis Tabelle 1: Endpoint-, WSDL- und Schema-URLs des Produktionssystems... 8 Tabelle 2: DHL Online Retouren Web Service Request-/Aufruf-Parameter... 11 Tabelle 3: DHL Online Retouren Web Service Response-/Antwort-Parameter... 12

1 Willkommen beim DHL Web Service für Online-Retouren DHL macht Versandretouren ecommerce-fähig die Online-Retoure als Web Service. Willkommen beim DHL Web Service zur Online-Retoure. Über diese Schnittstelle kann die Online- Retouren Applikation der DHL nahtlos in Ihre ecommerce Shop-Seiten und Prozesse integriert werden. Somit wird das Angebot für die Käufer verbessert, die zudem auf Ihrer Seite und innerhalb Ihres Verkaufsprozesses bleiben. 1.1 Über das Dokument Diese Dokumentation enthält eine Beschreibung der Schnittstelle und ist als Referenz- Dokumentation für Software-Entwickler gedacht. Es werden Hintergründe und Zusammenhänge erläutert, sowie die Anbindung beschrieben. Die Dokumentation ist in drei Kapitel unterteilt: Kapitel 1 gibt einen Hintergrund zu den Voraussetzungen, die den Einsatz des Web Services ermöglichen. Kapitel 2 dient als Kurzanleitung in das Thema und bietet eine grobe Übersicht über den Prozessablauf, den der Web Service für die Online-Retoure mit sich bringt. In Kapitel 3 wird der Funktionsaufruf näher erläutert sowie seine Input- und Output-Parameter beschrieben. Abschließend dienen im Anhang Quellenangaben und ein Code Beispiel als Hilfestellungen zum Umgang mit dem Web Service. 1.2 Technischer Überblick Der vorliegende Web Service ist eine synchrone SOAP-Schnittstelle, die eine dezentrale Erzeugung von DHL Retouren-Labels ermöglicht. Damit bietet sie neben dem Aufruf einer URL (sog. Varianten 1 und 2) einen alternativen Zugang zur DHL Online-Retouren Applikation und ermöglicht Ihnen, als Shopbetreiber und Versandhändler oder als deren Software-Lieferant, Ihr Retouren-Management auf die nächste Stufe zu heben. Durch die Kommunikation Ihres Backend-Systems mit dem Web Service können Sie den Rückabwicklungsprozess sehr kundenfreundlich gestalten und Ihr Geschäft signifikant verbessern. Sie sind Betreiber eines Webshops und haben den Wunsch, die Effizienz des Retouren-Prozesses zu verbessern? Sie sind Software oder IT Service Provider und möchten Ihren Versandhandels-Kunden Verbesserungen Ihrer Shop-Produkte anbieten? Der Online-Retouren Web Service ermöglicht Ihrer Software: Die Erzeugung von Retouren-Labels für Ihre Käufer selbst vorzunehmen Sicherzustellen, dass die Labels an Ihre Wunsch-Adresse(n) geschickt werden und nur bei Inanspruchnahme abgerechnet werden Technisch betrachtet besteht der vorliegende Web Service aus einer einzigen Operation, die über das standardisierte SOAP Protokoll über HTTPS ansprechbar ist. Um sie aufzurufen, wird der Funktions- Aufruf als standardisiertes XML-Dokument im SOAP-Body oder alternativ im Body eines HTTPS POST DHL Web Service Dokumentation Online-Retoure v2.0 3

Requests übergeben Die Eingabeparameter beschreiben die Daten zur Erstellung des Retouren- Labels. Der Web Service antwortet unverzüglich mit einem XML Dokument, das die Ausgabe- Parameter und das Retouren-Label Base64 kodiert enthält. Um den Service nutzen zu können, sollten Entwickler ein gutes Verständnis von und Erfahrungen mit SOAP mitbringen. Im Anhang sind einige hilfreiche Links aufgeführt. 1.2.1 Systemvoraussetzungen 1.2.2 Benötigter Zugang Es ist lediglich ein Internetzugang nötig, über den der Web Service via TCP/IP angesprochen werden kann. Neben dem Verbindungs-Management mit dem DHL Service sollten SOAP- und/oder XML-Tools vorhanden sein, um Aufruf-Dokumente aus der Anwendungslogik heraus zu erstellen und die Informationen aus dem Antwort-Dokument auszulesen ( parsen ). Username und Password 1.3 Fachlicher Hintergrund die Vollintegration in Ihre Versandhandelsseite Als Anbieter von Versandhandels-Produkten oder als unterstützender Software-Lieferant definieren Sie, in welcher Form Sie die Daten zur Retouren-Lösung nutzen möchten. Ein kundenfreundlicher Prozess einer integrierten Retouren-Label-Bestellung wird wie folgt dargestellt: Der Käufer möchte Ware zurückschicken und ruft auf Ihrer Webseite den angebotenen Retouren-Service auf (die Link-Adresse übermitteln Sie ihm zum Beispiel bereits in der Kaufbestätigungs-Email). o Nachdem er identifiziert wurde und die zurückzugebende Ware aus der Liste seiner jüngsten Käufe ausgewählt hat, gelangt er auf eine Eingabemaske mit vorausgefüllten Absenderdaten, die der Lieferadresse entsprechen. Gegebenenfalls korrigiert er die Absender-Daten und schickt das Formular ab. Die variablen Daten werden an den Retouren-Webservice der DHL übertragen. Die Empfängeradresse ist hingegen vorab fest im DHL-System hinterlegt worden. Der Web Service antwortet mit einem XML-Response, welcher das fertige Retouren-Label als PDF-Dokument (Base64-kodiert) sowie weitere Sendungsdaten (IDC etc.) enthält. Das Retouren-Label wird durch den Endkunden ausgedruckt und auf das Paket aufgebracht. Der Endkunde liefert sein Paket (für ihn kostenlos) in einer Filiale ein. DHL Web Service Dokumentation Online-Retoure v2.0 4

Abbildung 1: Fiktives Beispiel einer Retouren-Maske auf Webseite Abbildung 2: Beispiel eines integrierten Aufrufs eines Retouren-Labels DHL Web Service Dokumentation Online-Retoure v2.0 5

1.3.1 Vorteile Diese Integrations-Lösung hat sowohl für Sie als Versandhändler als auch für Ihre Kunden große Vorteile. Für Sie als Betreiber: stark reduzierter Aufwand für den Kundenservice der Käufer verbleibt in Ihrem Verkaufsprozess mit konsistentem Look and Feel, sowie weiteren Möglichkeiten zu Up- und Cross-Selling Sie definieren den kompletten Prozess Nur die tatsächlich transportierten Pakete werden produktionsdatenbasiert gemäß der aktuellen DHL Abrechungs-Dokumentation abgerechnet Vorteile für den Käufer sind: wenige Prozessschritte bei der Erstellung des Retouren-Labels schnelles Ergebnis kostenfreier Service vielfältige Einlieferungsmöglichkeiten (Filiale, Abholung) benutzerfreundliches Layout 1.3.2 Mögliche Varianten der Lösung 1 Avisierung der Pakete anhand der Paket-Identnummern Einrichtung mehrerer Konten durch Ihren DHL Ansprechpartner für mögliche weitere Empfängeradressen Ihrer Retouren z.b. o Rücksendung Ihr Retourenlager o Umtausch Ihr Wareneingang o Reparatur anderer Dienstleister 1.4 Rückmeldung und Unterstützung Falls Sie weitergehende Unterstützung benötigen oder Rückmeldung zum Web Service oder das Dokument geben möchten, kontaktieren Sie bitte Ihren Vertriebs-Ansprechpartner oder den DHL- Kundenservice. 1 Die Umsetzung der Zusatzfeatures kann ausschließlich von Ihnen erfolgen. DHL Web Service Dokumentation Online-Retoure v2.0 6

2 Kurzanleitung: In sechs Schritten zum Retouren-Label 2.1 Schritt 1: Retourenportal mit Empfangsadresse einrichten Bevor Sie mit der technischen Einrichtung beginnen können müssen folgende Konfigurationsschritte durchgeführt sein: Das Retourenportal wird nach Beantragung für den Webservice durch DHL eingerichtet und vorkonfiguriert. Die Namen der Retourenportale kann von Ihnen bei der Beantragung frei gewählt werden. Nach Abschluss erhalten Sie eine Aufschalt- email u.a. mit folgenden Informationen: (Beispiel hier ohne Funktion) Zur erstmaligen Anmeldung nutzen Sie bitte die Option "Neues Passwort anfordern" unter Angabe Ihres Benutzernamens auf der Seite: https://amsel.dpwn.de/abholportal/gw/lp/portal/288test/admin/adminlogin.action Melden Sie sich bitte mit Ihrem Benutzernamen und Passwort an und - Vervollständigen im Bereich Einstellungen die Angaben zur Nutzung Ihres Portals. - Anschließend richten Sie im Bereich Adressen Retourenempfänger Ihre gewünschte Empfängeradresse der Retouren ein. Folgende Retourenportale sind bereits konfiguriert RetourenlagerDeutschland:https://amsel.dpwn.de/abholportall/gw/lp/portal/288Test/custo mer/rporder.action?delivery=retourenlagerdeutschland RetoureFrankreich:https://amsel.dpwn.de/abholportall/gw/lp/portal/288Test/customer/RpO rder.action?delivery=retourefrankreich Ihr Webservice Benutzername lautet: TEST123 Unter folgenden Link können Sie (einmalig) das Passwort für den Webservice-Nutzer festlegen: https://amsel.dpwn.de/abholportal/gw/web/admin/adminlogin.action?token=12345... Loggen Sie sich in den Administrationsbereich ein, prüfen und speichern alle notwendigen Angaben. Nutzen Sie nur den Webservice, so muss nur die Retourenempfangsadresse geprüft und gespeichert werden. Das Passwort für den Webservice muss gesondert vom Admin-Passwort von Ihnen neu gesetzt werden. Dazu öffnen Sie bitte den zugesendeten Link und ändern das Passwort gemäß Vorgaben. Ihr Webservice Retourenportal ist damit vollständig konfiguriert und kann angesprochen werden DHL Web Service Dokumentation Online-Retoure v2.0 7

2.2 Schritt 2: Den Client aufsetzen Achten Sie vor dem Aufruf des Web Services auf die entsprechende Einrichtung des Systems. Abgesehen von der Hardware und dem TCP/IP Internetzugang, benötigen Sie ein freigeschaltetes Retourenportal in der Anwendung Amsel, sowie einen für die Variante 3 konfigurierten Retourenempfänger mit einer gültigen Empfängeradresse (diese können Sie selbst im Administrationsbereich Ihres Retourenportals pflegen). 2.3 Schritt 3: Kommunikation einrichten Die Kommunikation erfolgt per SOAP Request über eine gesicherte HTTPS-Verbindung. Die Beispiele im Anhang veranschaulichen die Verwendung der Parameter ausführlich und können als Ausgangspunkt nach einer Anpassung der Zugangsdaten genutzt werden. 2.3.1 Web Service Kommunikation auf der Basis von SOAP Zunächst laden Sie die relevanten Web Service-Definitionen und Schema -Dateien der DHL. Diese werden benötigt, um Applikationen für diesen Webservice zu entwickeln. Sie spezifizieren die erforderliche Struktur der SOAP Botschaften, die Funktionssignaturen, die API Service Bindings sowie die Service Endpoints. Die nachstehende Tabelle enthält die Zugangspunkte für das Produktionssystem. PRODUKTIONSSYSTEM Ressource WSDL Endpoint URL https://amsel.dpwn.net/abholportal/gw/lp/schema/1.0/var3ws.wsdl https://amsel.dpwn.net/abholportal/gw/lp/soapconnector Tabelle 1: Endpoint-, WSDL- und Schema-URLs des Produktionssystems Nachdem Sie diese Dateien herunter geladen haben, können Sie einen SOAP Client Service nutzen, um Business-Object Interfaces sowie Network Stubs daraus zu generieren und sich die Arbeit deutlich zu erleichtern. Der Request wird schließlich als SOAP Methoden-Aufruf formuliert und an den SOAP Service-Endpoint übermittelt. DHL Web Service Dokumentation Online-Retoure v2.0 8

2.4 Schritt 4: Benutzer mit ausreichenden Berechtigungen erstellen Jede der Web Service Operationen erfordert eine Authentifizierung. Beantragen Sie daher bei Ihrem DHL Vertriebs-Ansprechpartner die notwendigen Berechtigungen für den Online-Retouren-Service der sog. Variante 3. Nach der Freischaltung erhalten Sie: einen Benutzernamen und das Passwort des eigens eingerichteten Webservice-Nutzers 2.5 Schritt 5: Beispiel Code übernehmen und testen Zur Vereinfachung Ihrer Programmierung finden Sie ein Code Beispiel im Anhang, das Sie an Ihre Anforderungen anpassen können. Um den mitgelieferten Beispiel Code zu testen, sprechen Sie bitte den Web Service über die in den Punkten 2.3.1 angegebenen URLs an. 2.6 Schritt 6: Den Web Service zur Online-Retoure auf Ihrer Webseite aktivieren Checkliste für die Aktivierung des Web Service zur Online-Retoure auf Ihrer Webseite: der Test ist erfolgreich abgeschlossen (Siehe 3.3 Fehlerverhalten) das Retouren-Label wird vollständig dargestellt und gedruckt der Aufruf ist erfolgreich in Ihre Webseite integriert Der Web Service der Online-Retoure wird synchron auf Ihre Anfrage (Request) antworten (Response). Bei erfolgreicher Übermittlung enthält die Antwortnachricht für das erzeugte Retourenlabel: den Routing-Code den nationalen IDC und den Typ des IDC (LP oder IDC) der internationale IDC mit Typ das Base64-kodierte Label im PDF Format DHL Web Service Dokumentation Online-Retoure v2.0 9

3 API Call Referenz Zum Aufruf des Web Services müssen folgende Parameter übergeben werden. Entsprechend der Fokussierung auf SOAP, wurde im Hinblick auf einen möglichst hohen Standardisierungsgrad in der Spezifikation des Produkt-Webservices das WSS Username Token als Grundlage für dokumentbasierte Sicherheit angegeben. Das WSS Username Token wird im SOAP Header übertragen und ist nicht Bestandteil der eigenen Datentypdefinitionen bzw. Messages. <wsse:security soapenv:mustunderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01 /oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsse:usernametoken> <wsse:username>nutzername Webservice-User</wsse:Username> <wsse:password >Klartextpasswort</wsse:Password> </wsse:usernametoken> </wsse:security> Das Passwort wird im Klartext in dem Tag <wsse:password> angegeben. Genauere Informationen zum WSS Username Token sind unter http://www.oasis-open.org/committees/download.php/5532/oasis-200401-wss-usernametoken-profile-1.0.pdf zu finden. DHL Web Service Dokumentation Online-Retoure v2.0 10

3.1 BooklabelRequest - Eingabe Parameter Name Pflicht Beschreibung Max. Länge portalid ja Der für das Portal vergebene URL-Postfix. Sie finden Ihre portalid im Aufschalt- email an dieser Stelle: (hier 288Test ) Zur erstmaligen Anmeldung nutzen Sie bitte die Option "Neues Passwort anfordern" unter Angabe Ihres Benutzernamens auf der Seite: https://amsel.dpwn.de/abholportal/gw/lp/portal/288test/ad min/adminlogin.action deliveryname ja Der Name des Retourenportals, welches die Retoure erhalten soll. Sie finden den jeweiligen deliveryname im Aufschalt- email an dieser Stelle: (hier RetoureFrankreich ) Folgende Retourenportale sind bereits konfiguriert: RetoureFrankreich: https://amsel.dpwn.de/abholportall/gw/lp/portal/288test/cu stomer/rporder.action?delivery=retourefrankreich customerreference nein Inhalt des 1. Eingabefeldes 40 shipmentreference nein Sendungsreferenz 50 labelformat ja Das Dateiformat des erzeugten Labels, bislang nur pfd. 10 sendername1 ja Name 1 des Absenders 50 sendername1 nein Name 2 des Absenders 50 sendercareofname nein Care Of Name. Wird momentan nicht verwendet für Label. 50 sendercontactphone nein Telefonkontakt des Absenders. Wird momentan nicht verwendet für Label. 20 senderstreet senderstreetnumber senderboxnumber senderpostalcode sendercity Je nach internationaler Adresskonfiguration Je nach internationaler Adresskonfiguration Je nach internationaler Adresskonfiguration Je nach internationaler Adresskonfiguration Je nach internationaler Adresskonfiguration Tabelle 2: DHL Online Retouren Web Service Request-/Aufruf-Parameter Straße des Absenders. Wird auf Label gedruckt. 50 Hausnummer des Absenders. Wird auf Label gedruckt. 7 Box-Number des Absenders. Wird momentan nicht verwendet für Label. Postleitzahl d. Absenders. Wird auf Label gedruckt. 8 Stadt des Absenders. Wird auf Label gedruckt. 50 8 DHL Web Service Dokumentation Online-Retoure v2.0 11

3.2 BookLabelResponse - Ausgabe Parameter Name Beschreibung label Das Base64 verschlüsselte Label als PDF issuedate Datum der Beauftragung routingcode Der Routing-Code der Beauftragung idc Der nationale (deutsche) Identifizierer der Beauftragung idctype Der Typ des nationalen Identifizierers intidc Der internationale Routing-Code falls vorhanden intidctype Der Typ des internationalen Routing-Codes Tabelle 3: DHL Online Retouren Web Service Response-/Antwort-Parameter 3.3 Fehlerverhalten 3.3.1 Fehlertypen Bei Fehlerfällen wird im Body des Soap-Responses im <fault>-tag der entsprechende Fehler ausgegeben. <env:envelope xmlns:ns4="http://docs.oasis-open.org/wss/2004/01/oasis- 200401-wss-wssecurity-secext-1.0.xsd" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:var3bl="https://amsel.dpwn.net/abholportal/gw/lp/schema/1.0/var3bl" xmlns:ns1="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <env:header/> <env:body env:encodingstyle=""> <env:fault> <faultcode>var3bl:invalidxml</faultcode> <faultstring>invalid XML</faultstring> </env:fault> </env:body> </env:envelope> DHL Web Service Dokumentation Online-Retoure v2.0 12

Folgende Fehlercodes können im Response zurückgegeben werden: <faultcode> <faultstring> Beschreibung InternalError Internal Error Bei der Verarbeitung gab es einen internen Server-Error. InvalidXml Invalid XML Der Request enthielt ein nicht valides XML NoPortal Für die angegebene Portal-ID konnte kein Retouren-Portal ermittelt werden Zu der im Feld portalid übergebene ID konnte kein Portal gefunden werden. LockedPortal Portal ist gesperrt Das im Feld portalid referenzierte Portal wurde zwar gefunden, ist aber gesperrt. Eine Beauftragung ist nicht möglich. NoDivision LockedOrDeletedDivision NoVariant3Division FieldLength MandatoryField InvalidSenderAddress NoDeliveryAddress Für die angegebene Delivery- ID konnte kein Retourenemfpà nger ermittelt werden Der gewünschte Retourenempfänger ist gesperrt oder gelöscht Der gewünschte Retourenempfänger ist nicht für Variante 3 freigeschaltet Länge eines Feldes ist nicht korrekt Der im Feld deliveryname übergebene Name des Retourenempfängers konnte nicht gefunden werden. Der im Feld deliveryname übergebene Name des Retourenempfängers konnte zwar gefunden werden, jedoch ist dieser gesperrt oder inzwischen gelöscht worden. Der im Feld deliveryname übergebene Name des Retourenempfängers konnte zwar gefunden werden, jedoch ist dieser nicht für Variante 3 (Webservice) konfiguriert. Die Länge eines übergebenen Feldes ist nicht korrekt. Entweder wurden zu kurze oder zu lange Eingaben gemacht. Ein Pflichtfeld ist nicht gesetzt Bei einem Pflichtfeld wurde kein Wert übergeben Absenderadresse konnte nicht erfolgreich validiert werden Für den Retourenempfänger wurde keine Empfängeradresse eingerichtet Die Validierung der Absenderadresse war nicht erfolgreich. Es muss sichergestellt werden, dass die Absenderadresse dem landestypischen Format entspricht. Im GK-Admin Frontend wurde für den übergebenen Retourenempfänger noch keine Empfangsadresse hinterlegt. Eine Beauftragung ist somit nicht möglich. DHL Web Service Dokumentation Online-Retoure v2.0 13

4 Anhang Hilfreiche Quellen 4.1 XML und Web Services XML.Org Home Page, Organization for the Advancement of Structured Information Standards (OASIS) http://www.xml.org/ W3 Schools XML Tutorial, Refsnes Data http://www.w3schools.com/xml/default.asp W3 Schools SOAP Tutorials, Refsnes Data http://www.w3schools.com/soap/default.asp Java Technology und Web Services, Sun Microsystems, Inc. http://java.sun.com/web Services/ Apache Web Services Project, The Apache Software Foundation http://ws.apache.org/ W3 Schools Web Services Tutorial, Refsnes Data http://www.w3schools.com/web Services/default.asp DHL Web Service Dokumentation Online-Retoure v2.0 14

4.2 Code Beispiel 4.2.1 SOAP POST Online-Retoure <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:var="https://amsel.dpwn.net/abholportal/gw/lp/schema/1.0/var3bl"> <soapenv:header> <wsse:security soapenv:mustunderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsse:usernametoken> <wsse:username>ws_online_retoure</wsse:username> <wsse:password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-tokenprofile1.0#PasswordText">Anfang1!</wsse:Password> </wsse:usernametoken> </wsse:security> </soapenv:header> <soapenv:body> <var:booklabelrequest portalid="onlineretoure" deliveryname="spanien_var3" shipmentreference="shipref Nextt" customerreference="1.feld via Webservice" labelformat="pdf" sendername1="willi Webservice" sendername2="via Webservice" sendercareofname="careofname" sendercontactphone="0800 123456" senderstreet="webservice Street" senderstreetnumber="8080" senderboxnumber="12" senderpostalcode="28010" sendercity="madrid"/> </soapenv:body> </soapenv:envelope> 4.2.2 SOAP Response Online-Retoure <env:envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:var3bl="https://amsel.dpwn.net/abholportal/gw/lp/schema/1.0/var3bl" xmlns:ns1="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns5="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <env:header/> <env:body env:encodingstyle=""> <var3bl:booklabelresponse intidctype="id_esp_ppo" intidc="pp600095823000000000923" idc="00340435019999802143" routingcode="53113019020746" issuedate="2010-11-09t12:52:11.430+0100"> <var3bl:label>label-daten Base64-kodiert</var3bl:label> </var3bl:booklabelresponse> </env:body> </env:envelope> DHL Web Service Dokumentation Online-Retoure v2.0 15