ANBINDUNGSLEITFADEN WARENPOST INTERNATIONAL FÜR SELBSTPROGRAMMIERER (REST-API)
←
→
Transkription von Seiteninhalten
Wenn Ihr Browser die Seite nicht korrekt rendert, bitte, lesen Sie den Inhalt der Seite unten
Anbindungsleitfaden
Warenpost International für
Selbstprogrammierer (ReST-API)
Version 1.0/Stand 3.3.2020Warenpost International Seite 2 von 65
Anbindungsleitfaden
Information und Identifikation
0.1 Änderungshistorie
Version Datum Bearbeitungsart Bearbeiter
1.0 3.3.2020 Erstellung Jan Henrik Walter,
Georg Herrmann,
Michael Steets
1.01 18.3.2020 Kleinere Korrekturen Michael Steets
1.03 5.6.2020 Feldänderungen für gepl. Release Michael Steets
Mitte Juni 2020 (addressLine1-3,
senderPostalCode, contentPieceValue,
jobReference)
2Warenpost International Seite 3 von 65
Anbindungsleitfaden
Inhaltsverzeichnis
Information und Identifikation ...................................................................................................... 2
0.1 Änderungshistorie............................................................................................................................ 2
1 Einleitung ................................................................................................................................. 7
1.1 Was ist Warenpost International? ................................................................................................ 7
1.2 Wofür ist dieser Leitfaden? ............................................................................................................ 7
1.3 Welche Möglichkeiten gibt es sonst noch, Warenpost International zu nutzen?............. 8
1.4 Wofür ist dieser Leitfaden nicht?.................................................................................................. 9
2 Grundlegende Funktionsprinzipien von Warenpost International .................................. 10
2.1 Funktionalitäten .............................................................................................................................. 10
2.2 Zugang zu den Systemen ............................................................................................................. 10
2.3 Umgebungen ................................................................................................................................... 10
2.3.1 Sandbox – Ihre Spielwiese ................................................................................................... 10
2.3.2 Livesystem ............................................................................................................................... 10
2.4 Einschränkungen der API Warenpost International .............................................................. 10
3 Aufschaltprozess................................................................................................................... 11
3.1 Dokumentation ............................................................................................................................... 11
3.2 Account zu Testsystem und Testportokasse erhalten .......................................................... 11
3.3 Testing............................................................................................................................................... 12
3.4 Umstellung der Software auf die Liveumgebung .................................................................. 12
4 Workflows der Auftragserstellung (“Logiken”) ................................................................ 14
4.1 Gemeinsamkeiten der Logiken: .................................................................................................. 14
4.2 Unterschiede der Logiken ............................................................................................................ 14
4.3 Logik 1: „Create Order Finalized“ ............................................................................................... 15
4.4 Logik 2: „Create Order Open“ ...................................................................................................... 15
5 Prozesse der Auftragslogik - Basics .................................................................................... 16
5.1 Authentizierung .............................................................................................................................. 16
5.2 Testumgebung (Sandbox) ........................................................................................................... 16
5.3 Livesystem ....................................................................................................................................... 16
6 Detailprozesse der Auftragslogik - Ordererzeugung ........................................................ 17
6.1 Prozess/Logik Create Order Finalized....................................................................................... 17
6.1.1 Request „Get Access Token“ ............................................................................................... 17
6.1.2 Beispiel: .................................................................................................................................... 17
6.1.3 Request „Create Order“ ........................................................................................................ 18
6.1.4 Request „Get Item Labels” ................................................................................................... 19
6.2 Beschreibung der Logik: Create Order Open........................................................................... 20
6.2.1 Request „Get Access Token” ............................................................................................... 20
3Warenpost International Seite 4 von 65
Anbindungsleitfaden
6.2.2 Request „Create Order” ........................................................................................................ 20
6.2.3 Request „Add Items to an Order” ....................................................................................... 20
6.2.4 Request „Get Item Label“ ..................................................................................................... 20
6.2.5 Request „Finalize Order“ ...................................................................................................... 21
6.3 Weitere verfügbare Requests...................................................................................................... 21
6.3.1 Get item .................................................................................................................................... 21
6.3.2 Get Order.................................................................................................................................. 21
6.3.3 Get shipments for an order ................................................................................................. 21
6.3.4 Validate order items .............................................................................................................. 21
7 Umstieg und Einsatz im Produktivsystem .......................................................................... 21
7.1 Voraussetzungen ............................................................................................................................ 21
8 Beispiel-Requests ................................................................................................................. 23
8.1 Beispiel „Get Access Token“ in JSON und cURL (Sandbox) ................................................. 23
JSON ........................................................................................................................................................... 24
cURL............................................................................................................................................................ 24
URL.............................................................................................................................................................. 24
Autorisation .............................................................................................................................................. 24
Header........................................................................................................................................................ 24
Body ............................................................................................................................................................ 24
Request ...................................................................................................................................................... 24
8.2 Beispiel „Get Access Token“ in JSON und cURL (Livesystem) ............................................ 25
JSON ........................................................................................................................................................... 25
cURL............................................................................................................................................................ 25
URL.............................................................................................................................................................. 25
Autorisation .............................................................................................................................................. 25
Header........................................................................................................................................................ 25
Body ............................................................................................................................................................ 25
Request ...................................................................................................................................................... 25
8.3 Beispiel „Create Order Finalized” in Maximalausprägung (Sandbox) ............................... 26
JSON ........................................................................................................................................................... 26
cURL............................................................................................................................................................ 26
URL.............................................................................................................................................................. 26
Autorisation .............................................................................................................................................. 26
Header........................................................................................................................................................ 26
Body ............................................................................................................................................................ 26
Request ...................................................................................................................................................... 26
8.4 Beispiel für „Create Order Finalized” in Minimalausprägung (Sandbox) ......................... 28
8.4.1 URL ............................................................................................................................................ 28
4Warenpost International Seite 5 von 65
Anbindungsleitfaden
8.4.2 Autorisation ............................................................................................................................. 28
8.4.3 Header ...................................................................................................................................... 28
8.4.4 Body .......................................................................................................................................... 28
8.4.5 Response.................................................................................................................................. 29
8.5 Beispiel für „Get Item Labels” ...................................................................................................... 30
8.5.1 URL ............................................................................................................................................ 30
8.5.2 Autorisation ............................................................................................................................. 30
8.5.3 Header ...................................................................................................................................... 30
8.5.4 Body .......................................................................................................................................... 30
8.5.5 Response.................................................................................................................................. 30
8.6 Beispiel für „Create Order Open” ................................................................................................ 31
8.6.1 URL ............................................................................................................................................ 31
8.6.2 Autorisation ............................................................................................................................. 31
8.6.3 Header ...................................................................................................................................... 31
8.6.4 Body .......................................................................................................................................... 31
8.6.5 Response.................................................................................................................................. 31
8.7 Beispiel für „Add Items to an Order” in Minimalausprägung .............................................. 32
8.7.1 URL ............................................................................................................................................ 32
8.7.2 Autorisation ............................................................................................................................. 32
8.7.3 Header ...................................................................................................................................... 32
8.7.4 Body .......................................................................................................................................... 32
8.7.5 Response.................................................................................................................................. 32
8.8 Beispiel für „Add Items to an Order” in Maximalausprägung.............................................. 34
8.8.1 URL ............................................................................................................................................ 34
8.8.2 Autorisation ............................................................................................................................. 34
8.8.3 Header ...................................................................................................................................... 34
8.8.4 Body .......................................................................................................................................... 34
8.8.5 Response.................................................................................................................................. 35
8.9 Beispiel für ”Get Item Label” ........................................................................................................ 37
8.9.1 URL ............................................................................................................................................ 37
8.9.2 Autorisation ............................................................................................................................. 37
8.9.3 Header ...................................................................................................................................... 37
8.9.4 Body .......................................................................................................................................... 37
8.9.5 Response.................................................................................................................................. 37
8.10 Beispiel für einen „Finalize Order” request (Sandbox): .................................................... 38
8.10.1 URL ............................................................................................................................................ 38
8.10.2 Autorisation ............................................................................................................................. 38
8.10.3 Header ...................................................................................................................................... 38
5Warenpost International Seite 6 von 65
Anbindungsleitfaden
8.10.4 Body .......................................................................................................................................... 38
8.10.5 Response.................................................................................................................................. 38
8.11 Beispiel für einen „Get item“ request (Sandbox) ............................................................... 41
8.11.1 URL ............................................................................................................................................ 41
8.11.2 Autorisation ............................................................................................................................. 41
8.11.3 Header ...................................................................................................................................... 41
8.11.4 Body .......................................................................................................................................... 41
8.11.5 Response.................................................................................................................................. 41
8.12 Beispiel für einen „Get Order“ Request (Sandbox) ............................................................ 43
8.12.1 URL ............................................................................................................................................ 43
8.12.2 Autorisation ............................................................................................................................. 43
8.12.3 Header ...................................................................................................................................... 43
8.12.4 Body .......................................................................................................................................... 43
8.12.5 Response.................................................................................................................................. 43
8.13 Beispiel für einen „Get shipments for an order“ Request ................................................ 46
8.13.1 URL ............................................................................................................................................ 46
8.13.2 Autorisation ............................................................................................................................. 46
8.13.3 Header ...................................................................................................................................... 46
8.13.4 Body .......................................................................................................................................... 46
8.13.5 Response.................................................................................................................................. 46
8.14 Beispiel für einen „validate order item“ Request ............................................................... 48
8.14.1 URL ............................................................................................................................................ 48
8.14.2 Autorisation ............................................................................................................................. 48
8.14.3 Header ...................................................................................................................................... 48
8.14.4 Body .......................................................................................................................................... 48
8.14.5 Response.................................................................................................................................. 50
9 Detaillierte Feldbeschreibung ............................................................................................. 51
10 Produktliste Warenpost International ............................................................................ 55
11 Liste der Länder, in die Warenpost International verschickt werden kann ................. 56
12 Support und Ansprechpartner ......................................................................................... 65
6Warenpost International Seite 7 von 65
Anbindungsleitfaden
1 Einleitung
1.1 Was ist Warenpost International?
Warenpost International ist die Lösung für den Versand kleinteiliger Produkte, Ersatzteile, Warenproben oder
Muster.
verschiedene Varianten und Tarife
Nutzung ausschließlich online
Mehrere Zugangskanäle
Einlieferung der physischen Sendungen wie gewohnt
Abrechnung über Internetmarke
Weitere Details finden Sie im offiziellen Produktblatt:
https://www.deutschepost.de/content/dam/dpag/images/B_b/Briefe_ins_Ausland/warenpostintern
ational/dp-warenpost-international-produktblatt-012020.pdf
Informationen zur Nutzung des Kilotarifs finden Sie unter: https://www.deutschepost.de/de/b/briefe-
ins-ausland/warenpost-international/warenpost-international-kilotarif.html
Antworten auf weitere grundsätzliche Fragen finden Sie auch unter
https://www.deutschepost.de/de/b/briefe-ins-ausland/haeufige-fragen.html
1.2 Wofür ist dieser Leitfaden?
Auf den nachfolgenden Seiten finden Sie eine erste Anleitung zur Erstellung von Aufträgen für Warenpost
International und die Erzeugung der dafür genutzten Sendungsetiketten (Label) über die ReST-basierte
Deutsche Post International Shipping-API (aka PacketPlus-API).
Die API unterstützt Sie dabei besonders in folgenden Aspekten:
Erfassung von Zollinhaltsdaten
o Bei Sendungen in Nicht-EU-Länder ist neben Absender und Empfänger auch die Angabe des
Sendungsinhalts zwingend erforderlich. Diese Daten werden digital an die Zollbehörden des
jeweiligen Ziellandes übermittelt.
Nutzung international standardisierter Etiketten
o Die Nutzung von Warenpost International setzt im Wesentlichen die Nutzung des „Harmonized
Labels“, einem standardisierten Labelformat für den internationalen Warenversand, voraus.
(vgl.
https://www.deutschepost.de/content/dam/dpag/images/B_b/Briefe_ins_Ausland/warenpos
tinternational/dp-warenpost-international-harmonisiertes-label-01-2020.pdf ).
Lediglich beim Warenversand innerhalb der EU ohne Sendungsverfolgung (EU untracked) kann darauf
verzichtet werden. Jedoch empfehlen wir auch für diese Sendungen, das Harmonized Label zu nutzen. Über
7Warenpost International Seite 8 von 65
Anbindungsleitfaden
die PacketPlus-API wird für alle Produkte Warenpost International das Harmonized Label in der jeweils
aktuellen Version erzeugt.
Nutzung vorhandener Zahlungsart per Internetmarke
o Die Frankierung auf dem Label wird über die Internetmarke erstellt. Daher ist zur Nutzung von
Warenpost International über die API auch eine Portokasse zur Bezahlung der erzeugten
Internetmarken erforderlich. Die API stellt dabei eine (implizite) ReST-Service-Fassade für den
ihnen evtl. bekannten Internetmarken-SOAP-Webservice bereit.
1.3 Welche Möglichkeiten gibt es sonst noch, Warenpost International zu
nutzen?
Falls die Selbstprogrammierung unter Nutzung der API nicht in Frage kommt, bieten wir zusätzliche, hier nicht
weiter ausgeführte, Möglichkeiten zur Nutzung von Warenpost International an:
Alle Produkte der Kategorie „Warenpost International “ werden über verschiedene elektronische Plattformen
angeboten, aktuell verfügen Sie über drei weitere Möglichkeiten:
1. Für kleine Versandmengen bieten wir registrierten Geschäftskunden den Abruf über den Shop der
Deutschen Post an unter https://shop.deutschepost.de/shop/katalog/index.jsp.
Der Online-Shop der Deutschen Post bietet Ihnen folgende Vorteile:
a. Einfache Datenerfassung
b. Erstellung des empfohlenen Harmonized Label (aber eben nur einzeln)
c. Kein eigener Programmieraufwand
2. Für Kunden mit großem Sendungsvolumen steht das elektronische Auftragsmanagement der
Deutschen Post (AM.exchange) auch für Warenpost International offen. Die Direktanbindung
finden Sie unter deutschepost.de/am (
https://www.deutschepost.de/de/e/elektronisches_auftragsmanagement.html)
3. Darüber hinaus ist Warenpost International in verschiedene Versand- und Logistiksoftwareprodukte
von Drittanbietern integriert. Den aktuellen Stand erhalten Sie jeweils unter
https://www.deutschepost.de/de/b/briefe-ins-ausland/warenpost-international.html sowie unter
https://www.deutschepost.de/de/i/internetmarke-porto-
drucken/geschaeftskunden/partner.html#partnerfinder
8Warenpost International Seite 9 von 65
Anbindungsleitfaden
1.4 Wofür ist dieser Leitfaden nicht?
Diese Anleitung beschreibt nicht den Versand nationaler Warenpost oder anderer Brief- oder Paketprodukte.
Sie ersetzt auch nicht die möglicherweise bekannte Beschreibung der SOAP-Schnittstelle für die Nutzung der
Internetmarke.
9Warenpost International Seite 10 von 65
Anbindungsleitfaden
2 Grundlegende Funktionsprinzipien von Warenpost International
2.1 Funktionalitäten
ReST-API als Ersatz der bekannten Internetmarken-SOAP-Schnittstelle
o sofern Harmonized Label benötigt
o sofern Zollinhaltsdaten benötigt
Integration von Portokassen über Autorisierungsfunktion
Zusammenstellung von Einzelsendungen zu größeren Einheiten, sog. Orders oder Aufträgen
Übertragung in die Systeme der Deutschen Post zur Weiterverarbeitung und automatischen
Übertragung von Zollinhaltsdaten
Erzeugung von Harmonized Labels/Sendungsetiketten mittels standardisierter ReST-Calls
2.2 Zugang zu den Systemen
Der Einsatz der ReST-API für Warenpost International ist ausschließlich für Geschäftskunden
(Selbstprogrammierer) und Partner vorgesehen. Zugangsdaten können über den zuständigen vertrieblichen
Ansprechpartner oder auch direkt vom technischen Support angefordert werden.
2.3 Umgebungen
2.3.1 Sandbox – Ihre Spielwiese
Testsystem zur Unterstützung für Partner und Selbstprogrammierer
Bereitstellung ReST-Schnittstelle zur kompletten Abbildung des Workflows
Keine Kosten durch Nutzung von Testportokasse
Geringer Umstellungsaufwand auf Livesystem
2.3.2 Livesystem
Bereitstellung ReST-Schnittstelle zur kompletten Abbildung des Workflows
Nutzung existierender Portokassen (Internetmarke) zur Abrechnung der Versände; Kilotarif-
Abrechnung zusätzlich über AM
Vollständige Nutzung der Produkte nur für Geschäftskunden mit Kilotarifen
2.4 Einschränkungen der API Warenpost International
Tracking von Sendungsinformationen über die API ist nicht möglich. Funktionalität nur über die
bekannten Methoden des Track Event Information Services bzw. Aufruf der Webseite zu Tracking
Informationen der Deutsche Post DHL.
10Warenpost International Seite 11 von 65
Anbindungsleitfaden
3 Aufschaltprozess
3.1 Dokumentation
Diese Dokumentation soll Ihnen die fachlichen und technischen Prinzipien der ReST-API für
Warenpost International verdeutlichen und Ihnen die notwendigen Informationen für eine erfolgreiche
Programmierung bereitstellen.
Im Bestreben, Ihnen den bestmöglichen Support zu bieten und die Dokumentation laufend zu
verbessern, nehmen wir Anregungen bzgl. Unklarheiten, Ungenauigkeiten oder Fehlern zur
Verbesserung dieser Dokumentation unter api@deutschepost.de gerne entgegen.
3.2 Account zu Testsystem und Testportokasse erhalten
Die Aufschaltung für Warenpost International mittels API (für Selbstprogrammierer) erfolgt im ersten
Schritt mit einer Aufschaltung für die Testumgebung („Sandbox“) und stellt die hierfür notwendigen
Zugänge zur Verfügung.
Minimale Voraussetzungen hierfür sind:
Ihr Firmenname
Ihr Name und Ihre Email
Post-Kundennummer (EKP)
Falls Sie bereits über eine Partneranbindung (PARTNER_ID) an die Internetmarke (in der
Liveumgebung) verfügen, wäre eine Information darüber wünschenswert. Für den Test in der
Sandbox wird sie nicht benötigt, im Vorfeld können wir aber ggfs. bereits „Stolpersteine“
beseitigen, die sich ggfs. durch unklare Formulierungen in dieser Doku ergeben.
Das Anlegen der Zugänge auf Seiten der Post beinhaltet:
Das Anlegen notwendiger Kundenstammdaten zur Nutzung individueller Tarife (Kilotarif).
die Bereitstellung einer kundenspezifischen Testportokasse in der Sandbox. Die Portokasse stellt
die erste Autorisierungsebene innerhalb der Requests an die API dar.
Die Testportokasse in Form einer fiktiven Mailadadresse und das Portokassenpasswort werden vom
API-Support erzeugt und dem Kunden per E-Mail übermittelt. Diese kundenindividuellen Daten dienen
als Nutzername und Passwort, um den zur Nutzung aller folgenden Requests jeweils notwendigen
Usertoken zu erzeugen.
Bitte beachten Sie, dass in der Sandbox Ihre möglicherweise bereits existierenden Portokassen aus der
Produktionsumgebung oder eine im Rahmen einer Anbindung an die Internetmarke (SOAP-API)
existierenden Testportokassen nicht nutzbar sind. Test- und Produktionsumgebung sind strikt
voneinander getrennt.
Einschränkungen:
11Warenpost International Seite 12 von 65
Anbindungsleitfaden
Eine Entwicklung gegen die Liveumgebung ist für die Nutzung der PacketPlus-API nicht
zweckmäßig und wird nur in Ausnahmefällen unterstützt.
3.3 Testing
Der Kunde kann nun mit den ihm zur Verfügung gestellten Zugangsdaten seine Software für die
Erzeugung von Aufträgen und Labels mittels der erforderlichen ReST-Calls gegen die Sandbox
durchführen.
Nach erfolgreicher Entwicklung erfolgt dann auf Kundenwunsch der Schritt zur Liveumgebung.
3.4 Umstellung der Software auf die Liveumgebung
Der Wechselzeitpunkt auf die Liveumgebung wird vom Kunden selbst bestimmt. Hierfür sind nur
wenige Schritte notwendig, die dafür notwendigen Informationen und Zugangsdaten liegen in der
Regel bereits im Vorfeld vor, können durch den Kunden selbst durchgeführt bzw. angefordert
werden.
Notwendige durchzuführende Anpassungen und Voraussetzungen:
1. Die Aufrufpfade der API ändern sich von https://api-qa.deutschepost.com auf
https://api.deutschepost.com
2. Für die Autorisierung muss eine Kunden-Portokasse aus der Liveumgebung genutzt werden. In der
Regel liegen Nutzername („Mailadresse“ der Portokasse) sowie Passwort dem Kunden bereits vor. Ist
dies nicht der Fall, kann der Kunde eine individuelle, sich selbst zugeordnete Portokasse unter
https://portokasse.deutschepost.de/portokasse/#!/ selbst erstellen.
Hinweis: Nutzernamen und Passwort dürfen kein „&“ enthalten!
3. Zur Nutzung der Kilotarif-Produkte ist der Abschluss eines entsprechenden Vertrags erforderlich, dies
kann online unter
https://www.dhl.de/content/dpks/de/themenauswahl/kundenservice-formulare/warenpost-
international.html geschehen. Das Vorliegen einer Post-Kundennummer (EKP) wird dabei
vorausgesetzt.
4. Stellen Sie sicher, dass bei (geplanter) Nutzung von Kilotarifen die EKP auch in der genutzten
Kundenportokasse hinterlegt ist. Dies können Sie in den Einstellungen Ihrer Portokasse überprüfen
bzw. ändern (siehe Screenshot).
12Warenpost International Seite 13 von 65
Anbindungsleitfaden
Beachten Sie, dass es nach Eintragen Ihrer EKP bis zu 24h dauern kann, bis Kilotarife mit Ihrer
Portokasse nutzbar sind.
Die Nutzung von Einzeltarifprodukten ist dagegen nicht an eine EKP gebunden.
5. Sofern noch nicht vorliegend, sollte nun spätestens die Anforderung von PARTNER_ID und
SCHLUESSEL_DPWN_PARTNER beim Team der Internetmarke (mail: pcf-1click@deutschepost.de)
erfolgt sein. Falls diese noch nicht vorliegen, können sie über folgenden Link beantragt werden
https://www.deutschepost.de/content/dam/dpag/images/i_i/Internetmarke/partnerwerden/dp-
internetmarke-anmeldebogen-api-anbindung.pdf
Partnern der Deutschen Post, die bereits die Programmierung der Internetmarke nutzen, liegen diese
Daten in der Regel vor. Diese kundenindividuellen Daten werden in der Liveumgebung für die
Berechnung eines gültigen Request-Headers zwingend benötigt. Falls erforderlich, können diese beim
Team Internetmarke erneut angefordert werden.
6. Anders als in der Sandbox ist die Gültigkeit eines Request-Header durch Verwendung eines
Timestamps auf vier Minuten begrenzt. Das bedeutet, dass ein gültiger Request-Header jeweils
zeitnah neu berechnet werden muss. Die genaue Berechnungsvorschrift zur Generierung des Headers
finden Sie in Kapitel 7.1 (Umstieg aufs Livesystem).
Zusammenfassend gesagt, sind Ihre Requests gegen das Livesystem also immer durch Ihre
individuelle Liveportokasse („Internetmarken-Token“) autorisiert und Ihren individuellen, jeweils
dynamisch erzeugten, Header authentifiziert.
13Warenpost International Seite 14 von 65
Anbindungsleitfaden
4 Workflows der Auftragserstellung (“Logiken”)
Um einen Auftrags („order“) für Warenpost International über die API zu erstellen, existieren aktuell zwei
verschiedene Möglichkeiten (im weiteren Verlauf “Logiken“ genannt).
Beiden Logiken liegt ein grundsätzlicher Workflow zur Erstellung von Aufträgen zugrunde. Dieser richtet sich
letzten Endes nach den individuellen Prozessen und Bedürfnissen der sie verwendenden Kunden. Vereinfacht
gesagt, ein Auftrag kann entweder in einem einzigen Schritt vollständig erzeugt werden oder aber eine
Auftragshülle wird sukzessive mit Auftragspositionen gefüllt.
4.1 Gemeinsamkeiten der Logiken:
1. Authentifizieren
2. Zusammenstellung eines Auftrags inkl. der Auftragspositionen („items“)
a. Druck der Versandetiketten („Label“) vor Finalisierung
3. Finalisierung des Auftrags
a. alternativ Druck der Versandetiketten nach Finalisierung
Die Finalisierung eines Auftrags sorgt für seine Übertragung und Weiterverarbeitung in die Systeme der
Deutschen Post. Unter anderem wird die notwendige Übertragung der Sendungsdaten in die Zollsysteme der
Empfängerländer sowie (zukünftig (!) auch die Übertragung an das Auftragsmanagement AM der Deutschen
Post) angestoßen. Deshalb kann ein finalisierter Auftrag nicht mehr verändert werden.
Ein finalisierter Auftrag wird als Shipment oder „AWB“ gespeichert und erhält eine AWB-ID (sichtbar in der
Response beim Finalisieren).
Ein AWB entspricht in etwa der möglicherweise aus dem Bereich „Auftragsmanagement“ bereits
bekannten Einlieferungsliste.
4.2 Unterschiede der Logiken
Unterschiede gibt es, wie gesagt, in der zeitlichen Abfolge/Dauer der Auftragserstellung, also letzten Endes im
Workflow.
Ein Auftrag kann
1. In einem einzigen Vorgang erstellt und abgeschlossen werden („Logik 1“) oder
2. eröffnet, über einen Zeitraum hinweg mit Items gefüllt und erst am Schluss abgeschlossen/finalisiert
werden („Logik 2“).
14Warenpost International Seite 15 von 65
Anbindungsleitfaden
4.3 Logik 1: „Create Order Finalized“
Diese Logik eignet sich, wenn alle Sendungen („Items“), die zu einem Auftrag zusammengefasst werden
sollen, bereits bekannt/fertig sind. In einem einzigen großen Request wird der Auftrag erstellt, die Sendungen
diesem Auftrag zugeordnet und der Auftrag automatisch abgeschlossen (finalisiert). Daraufhin können dann
alle zu diesem Auftrag gehörenden Label mit einem weiteren Request erstellt werden.
Eine nachträgliche Änderung des Auftrags ist jedoch in dieser Logik nicht mehr möglich.
Aus Performancegründen sollte die Anzahl der Sendungen hier nicht mehr als 300 Sendungen in einem
Auftrag betragen.
Die drei hierfür mindestens zu implementierenden Requests sind:
1. Get Access Token
2. Create Order
3. Get Item Labels
Darüber hinaus existiert eine Reihe weiterer nutzbarer Requests, welche Ihnen im Verlauf dieses Dokumentes
vorgestellt werden.
4.4 Logik 2: „Create Order Open“
Bei dieser Logik wird zunächst eine Auftragshülle angelegt und danach werden einzelne Sendungen
hinzugefügt. Die Item-Label können dann einzeln und direkt nach dem Hinzufügen der Sendungen zum
Auftrag erzeugt werden.
Die maximal einem Auftrag zuordenbare Menge an Sendungen beträgt in dieser Logik 5000.
Aus Performancegründen und zur Erhöhung der Übersichtlichkeit wird jedoch empfohlen, deutlich unter
diesem Maximums zu bleiben.
Alternativ (und wie in Logik 1) können auch hier alle Label nach Finalisierung eines Auftrages erzeugt werden.
In diesem Fall sollte auch hier die Anzahl von Sendungen in einem Auftrag auf maximal 300 Sendungen
beschränkt werden.
Die hierfür mindestens zu implementierenden Requests sind:
1. Get Access Token
2. Create Order
3. Add Items to an Order
4. Get Item Label
5. Finalize Order
Auch hier stehen weitere Requests zur Verfügung, welche ihnen im Verlauf dieses Dokuments vorgestellt
werden.
15Warenpost International Seite 16 von 65
Anbindungsleitfaden
5 Prozesse der Auftragslogik - Basics
5.1 Authentizierung
Zur erfolgreichen Ausführung eines Requests ist jeweils das Vorliegen eines (zeitlich begrenzen) gültigen
Zugriffstokens erforderlich.
Die API nutzt das OAuth 2.0-Protokoll, um durch eine Kombination aus Authentifizierung und Autorisierung
durch den „Get Access Token“ API-Call ein „OAuth2 Bearer Token“ zu generieren und Ihnen dadurch den
Zugang zur „Deutschen Post International Shipping API“ zu ermöglichen
Die Autorisierung und damit die Nutzung der API ist durch HTTP Basic Authentifizierung gesichert, bei der Sie
Ihre Portokassen E-Mail und das Portokassenpasswort angeben müssen, da hierüber die Bezahlung durch die
Internetmarke erfolgt.
Vereinfacht gesagt: die Informationen des Headers berechtigt einen Partner zum grundsätzlichen Zugriff auf
das System der Internetmarke. Dieser Zugriff erfolgt implizit durch die Nutzung der entsprechenden API-
Requests. Ein expliziter Aufruf, wie es der Partner ggfs. aus der Internetmarken-(SOAP)-API kennt, findet hier
nicht statt.
In der Sandbox nutzt er die PARTNER_ID (auch bekannt als „Channel“) „DP_LT“ der Deutschen Post (die als
alleiniger Partner in der Sandbox fungiert), in der Liveumgebung nutzt ein Partner oder Eigenentwickler seine
individuelle PARTNER_ID.
Die Nutzung einer spezifischen Portokasse für einen Auftrag (nämlich über den mit der jeweiligen
Autorisierung abgerufenen Token) legt dann zum Beispiel fest, aus welcher Kasse resp. von welchem
Endkunden/Mandanten die jeweiligen Sendungen bezahlt werden (vereinfacht gesagt).
5.2 Testumgebung (Sandbox)
In der Sandbox wird ein vereinfachter Authentifizierungsprozess genutzt, um u.a. Aufwände im Zuge einer
Entwicklung zu minimieren. Die Gültigkeitsdauer eines durch die Internetmarke bereitgestellten Tokens ist
deutlich länger und die Zugangsberechtigung zum System der Internetmarke wird durch einen für alle Nutzer
vereinheitlichten Header sichergestellt.
5.3 Livesystem
Im Livesystem erfolgt der grundsätzliche Zugang über einen firmenspezifischen und jeweils zeitnah neu zu
berechnenden Header (Aktualisierung des Timestamps und der abhängigen Felder), darüber hinaus beträgt
die Gültigkeit eines Tokens lediglich vier Minuten.
16Warenpost International Seite 17 von 65
Anbindungsleitfaden
6 Detailprozesse der Auftragslogik - Ordererzeugung
6.1 Prozess/Logik Create Order Finalized
6.1.1 Request „Get Access Token“
Als ersten Schritt müssen Sie sich gegen die API authentifizieren, um Warenpost International nutzen zu
können. Dazu wird ein Token über die Internetmarke abgerufen.
Im Folgenden zur Verdeutlichung ein Beispiel aus der Testumgebung; wie bereits oben erwähnt,
unterscheiden sich die notwendigen Angaben zur Authentifizierung auf dem Testsystem von denen in der
Produktion. Daher wird das folgende Beispiel auch nur in der Testumgebung funktionieren!
6.1.2 Beispiel:
Voraussetzungen/Annahmen:
1. Für die Testumgebung erhalten Sie ihre Portokassen-Email und -Passwort von der Deutschen Post im
folgenden beispielhaften Format. Zusammen mit den weiter unten angegeben Headerdaten können
Sie in unserer Testumgebung ein Access Token erhalten. Das Vorgehen zur Produktivnutzung ist in
Kapitel 7 beschrieben.
2. Beispiel für Portokassen-Email: wapo@test.de
3. Beispiel für Portokassen Passwort: wapoTestPw123
4. Im HTTPS Request muss die HTTP Basic Authentifizierung genutzt werden.
Portokassen-Email und Portokassen-Passwort müssen dabei base64 verschlüsselt werden. Bei der
Verschlüsselung werden E-Mail und das Passwort mit einem Doppelpunkt „:“ getrennt. Weiterhin ist
UTF-8 als Characterset zu verwenden.
Authentifizierung: BasicWarenpost International Seite 18 von 65
Anbindungsleitfaden
KEY_PHASE: 1
PARTNER_ID: DP_LT
REQUEST_TIMESTAMP: 16082018-122210
PARTNER_SIGNATURE: 9d7c35be
Diese konkreten vier Header-Informationen sind, wie bereits erwähnt, ausschließlich in der
Testumgebung nutzbar, da in dieser die dynamische Prüfung von TIMESTAMP und Hashwert
(PARTNER_SIGNATURE) entfällt.
6. Sie erhalten daraufhin eine Antwort (Response) im SOAP/XML-Format mit einem gültigen Token, dem
UserToken für die weiterführenden Requests. Dieses Format wurde gewählt, da es den meisten
Kunden bereits von den nativen Internetmarken-SOAP-Requests bekannt sein dürfte. Alle weiteren
Responses sind demgegenüber in JSON gehalten.
Beispielantwort/-Response:
yDI0S6akfOJsY7DV6EcKeaAfsCIAlbpGKv1ppielQ6o=
484440
false
6.1.3 Request „Create Order“
Der nächste Schritt ist die Anlage einer sogenannten „Order“. Dies ist eine Auftragshülle zur Erfassung von 1 –
max. 5000 Einzelsendungen, wobei wir je nach Nutzungskontext empfehlen deutlich weniger Sendungen in
einem Auftrag zusammenzufassen. Für jede Einzelsendung können die folgenden Datenfelder erfasst werden.
Der Content-Part ist dabei nur für Nicht-EU-Sendungen notwendig. Details sowie die Angabe welche Felder
verpflichtend oder optional sind, finden sie in Kap. 7. In Kap. 6 finden sie Beispiel-Requests. Informationen zu
den nutzbaren Länderkürzeln finden sie in Kap. 9.
-customerEkp Items (1/2): Items(2/2): Contents:
-orderStatus -product -returnItemWanted -contentPieceHsCode
-serviceLevel -shipmentAmount -contentPieceDescription
Paperwork: -shipmentCurrency -contentPieceNetweight
18Warenpost International Seite 19 von 65
Anbindungsleitfaden
-contactName -custRef -shipmentGrossWeight -contentPieceOrigin
-jobReference -recipient -senderName -contentPieceAmount
-pickupType -recipientPhone -senderAddressLine1 -contentPieceValue
-awbCopyCount -recipientFax -senderAddressLine2
-recipientEmail -senderCountry
-addressLine1 -senderCity
-addressLine2 -senderPostalCode
-addressLine3 -senderPhone
-city -senderEmail
-state -shipmentNaturetype
-postalCode
-destinationCountry
6.1.4 Request „Get Item Labels”
Mit diesem Request rufen sie alle Labels ihrer Sendungen in einer Datei ab und können diese nun ausdrucken.
Dabei stehen ihnen folgende Optionen zur Verfügung:
“image/png” (A6)
“image/png+6x4” (6x4 inch)
“application/pdf” (A6)
“application/pdf+singlepage” (A6)
“application/pdf+singlepage+6x4” (6x4 inch)
“application/zpl” (A6)
“application/zpl+rotated” (rotated by 90 degrees for label printers)
“application/zpl+6x4” (6x4 inch)
“application/zpl+rotated+6x4” (6x4 inch and rotated by 90 degrees for label printers)
Die Festlegung erfolgt im Header-Parameter ACCEPT.
19Warenpost International Seite 20 von 65
Anbindungsleitfaden
6.2 Beschreibung der Logik: Create Order Open
6.2.1 Request „Get Access Token”
Als erstes müssen sie einen Token über die Internetmarke abfragen. Siehe Kapitel 3.1.
6.2.2 Request „Create Order”
Nun können sie einen neuen Auftrag erstellen/öffnen, in welchen Sie die Items über den Tag verteilt
hinzufügen können.
Benötigte Felder (required fields):
customerEkp
orderStatus
6.2.3 Request „Add Items to an Order”
Nach der Erstellung eines Auftrags werden nun die Sendungen einzeln oder max. 2500 mit diesem Request
hinzugefügt. Details zu den einzelnen Feldern finden sie in Kap. 7. In Kap. 6 finden sie Beispiele. Informationen
zu den nutzbaren Länderkürzeln finden sie in Kap. 9
Items (1/2): Items(2/2): Contents:
-product -returnItemWanted -contentPieceHsCode
-serviceLevel -shipmentAmount -contentPieceDescription
-custRef -shipmentCurrency -contentPieceNetweight
-recipient -shipmentGrossWeight -contentPieceOrigin
-recipientPhone -senderName -contentPieceAmount
-recipientFax -senderAddressLine1 -contentPieceValue
-recipientEmail -senderAddressLine2
-addressLine1 -senderCountry
-addressLine2 -senderCity
-addressLine3 -senderPostalCode
-city -senderPhone
-state -senderEmail
-postalCode -shipmentNaturetype
-destinationCountry
6.2.4 Request „Get Item Label“
Mit diesem Request rufen sie jeweils genau ein Label in einer Datei ab und können dieses nun ausdrucken.
Dabei stehen ihnen folgende Optionen zur Verfügung:
“image/png” (A6)
20Warenpost International Seite 21 von 65
Anbindungsleitfaden
“image/png+6x4” (6x4 inch)
“application/pdf” (A6)
“application/pdf+singlepage” (A6)
“application/pdf+singlepage+6x4” (6x4 inch)
“application/zpl” (A6)
“application/zpl+rotated” (rotated by 90 degrees for label printers)
“application/zpl+6x4” (6x4 inch)
“application/zpl+rotated+6x4” (6x4 inch and rotated by 90 degrees for label printers)
Die Festlegung erfolgt im Header-Parameter ACCEPT
6.2.5 Request „Finalize Order“
Den erstellten Auftrag müssen sie nun noch abschließen/finalisieren. Dies können sie einmalig am Ende eines
Tages machen oder nach Bedarf über den Tag verteilt. Z.B. um mehrere Label mit einem Request zu erzeugen
oder um die Anzahl der Sendungen pro Auftrag zu begrenzen.
6.3 Weitere verfügbare Requests
6.3.1 Get item
Sie erhalten alle Information über das angegebene Item.
6.3.2 Get Order
Sie erhalten die Auftragsdaten (den „Auftragskopf“) für die angegebenen orderID.
6.3.3 Get shipments for an order
Sucht nach Sendungen, die an eine bestimmte Bestellung angehängt sind. Antworten mit dem Status
"Nicht gefunden" (404) erscheinen, wenn keine Bestellung vorhanden ist oder wenn dieser
Bestellung keine Sendungen beigefügt sind.
6.3.4 Validate order items
Vorabprüfung eines create-order Auftrages.
Beispiele für diese Requests finden sie in Kap. 8
7 Umstieg und Einsatz im Produktivsystem
7.1 Voraussetzungen
21Warenpost International Seite 22 von 65
Anbindungsleitfaden
Jeder Request für Warenpost International wird daraufhin geprüft, ob die Anfrage von einem zugelassenen
System stammt. Dazu übermittelt das anfragende System im Header folgende
Authentifizierungsinformationen:
Header Element Kurzbeschreibung notwendig Typ Länge Hash Beispiel- Default
(JA/NEIN) Werte
PARTNER_ID Die mit dem Partner JA STRING 5 Y IMPAR
vereinbarte ID.
REQUEST_TIMESTAMP Absendezeitpunkt JA DDMMYYY 15 Y 02022020-
(Datum und Uhrzeit) Y- 0135500
des Requests. Darf bei HHMMSS
Absetzten des
Requests nicht älter als
vier Minuten sein,
ansonsten wird der
Request abgewiesen.
KEY_PHASE vereinbarte Version des JA NUMBER 3 Y 1 1
Geheimnisses (Default:
1).
SIGNATURE_ALGORIT Verwendeter NEIN STRING 16 Y md5 Md5
HM Signaturalgorithmus
sha-256
(entfällt bei Warenpost
International; nur für sha-384
Internetmarken-API
sha-512
relevant)
PARTNER_SIGNATURE Signatur (Hash) des JA ALPHANU 8 Y a0b1c2d3
Requests über die M-
zwischen DPAG und
ERISCH
Drittanbieter
definierten Felder.
Stimmt der Hash nicht
überein, so wird der
Request abgewiesen.
Die genaue
Zusammensetzung der
Signatur ist
nachfolgend
beschrieben.
Die Signatur/Prüfsumme wird als MD5-Hash, basierend auf den Inhalten der folgenden Felder berechnet:
PARTNER_ID
REQUEST_TIMESTAMP
KEY_PHASE
SCHLUESSEL_DPWN_PARTNER
22Warenpost International Seite 23 von 65
Anbindungsleitfaden
Für die Prüfsummenbildung werden die Inhalte der o. g. Felder aneinandergehängt.
Alle Feldinhalte werden rechts und links um Blanks bereinigt und mit dem Trenner „::“ versehen konkateniert.
Wenn ein Feld leer oder im Request nicht vorhanden ist, werden folgende Trennzeichen angewendet „::::“
Das Ergebnis wird als Eingabe für die HASH Erstellung verwendet, das Ergebnis ist ein MD5-Hashwert. Die
Bytes werden in ihrer hexadezimalen Darstellung (mit a–f in Kleinbuchstaben) in einen Text umgewandelt.
Hexadezimale Darstellungen von Bytes, die nur über eine Stelle verfügen (0–f) werden um eine führende Null
erweitert (00–0f).
Die ersten 8 Zeichen des daraus resultierenden Textes werden im Feld PARTNER_SIGNATURE abgelegt.
Auf der Empfängerseite (also der Post) werden dieselben Schritte zur Verifizierung der
PARTNER_SIGNATURE durchgeführt. Zusätzlich wird geprüft, ob zwischen dem Wert REQUEST_TIMESTAMP
und dem aktuellen Systemdatum nicht mehr als vier Minuten vergangen sind.
Berechnungsbeispiel:
PARTNER_ID, SCHLUESSEL_DPWN_PARTNER: statisch je Partner
KEY_PHASE: immer = „1“
TIMESTAMP: aktuelle Zeit
Ergebnis: PARTNER_SIGNATURE
POST-Parameter Wert
URL https://internetmarke.deutschepost.de/OneClickForApp/V3 (nur z.K.)
PARTNER_ID XXXXX
REQUEST_TIMESTAMP 15012020-102200
KEY_PHASE 1
SCHLUESSEL_DPWN_PARTNER 5q6gTCuKgrgoAEbH47Wtvh6mtYEWZKEZ
Concat PARTNER_ID::REQUEST_TIMESTAMP::KEY_PHASE::SCHLUESSEL_DPWN_PARTNER
XXXXX::15012020-
Signatur-String 102200::1::5q6gTCuKgrgoAEbH47Wtvh6mtYEWZKEZ
md5-Hash
MD5-Hash 5038e6461d37943a5b852a41f9961a9b
Zeichen 1-8
PARTNER_SIGNATURE 5038e646
8 Beispiel-Requests
8.1 Beispiel „Get Access Token“ in JSON und cURL (Sandbox)
23Warenpost International Seite 24 von 65
Anbindungsleitfaden
JSON cURL
URL Request
GET https://api- curl --location --request GET 'https://api-
qa.deutschepost.com/v1/auth/accesstoken qa.deutschepost.com/v1/auth/accesstoken' \
--header 'KEY_PHASE: 1' \
Autorisation
Basic --header 'PARTNER_ID: DP_LT' \
d2Fwb0B0ZXN0LmRlOndhcG9UZXN0UHcxMjM --header 'REQUEST_TIMESTAMP: 16082018-
= 122210' \
Header --header 'PARTNER_SIGNATURE: 9d7c35be' \
KEY_PHASE: 1 --header 'Authorization: Basic
PARTNER_ID: DP_LT d2Fwb0B0ZXN0LmRlOndhcG9UZXN0UHcxMjM='
REQUEST_TIMESTAMP: 16082018-122210
PARTNER_SIGNATURE: 9d7c35be
Body
Keiner
24Warenpost International Seite 25 von 65
Anbindungsleitfaden
8.2 Beispiel „Get Access Token“ in JSON und cURL (Livesystem)
JSON cURL
URL Request
GET curl --location --request GET
https://api.deutschepost.com/v1/auth/accesstok 'https://api.deutschepost.com/v1/auth/accesstoken' \
en
--header 'KEY_PHASE: 1' \
Autorisation --header 'PARTNER_ID: XXXXX' \
Basic --header 'REQUEST_TIMESTAMP: 15012020-
ZWNodGVwb3J0b2thc3NlQGt1bmRlbmRvbWFp 102200' \
bjplY2h0ZXNwYXNzd29ydA==
--header 'PARTNER_SIGNATURE: 5038e646' \
Header --header 'Authorization: Basic
KEY_PHASE: 1 ZWNodGVwb3J0b2thc3NlQGt1bmRlbmRvbWFpbjplY
PARTNER_ID: XXXXX 2h0ZXNwYXNzd29ydA=='
REQUEST_TIMESTAMP: 15012020-102200
PARTNER_SIGNATURE: 5038e646
Body
Keiner
Response:
nBI2fcUsyE9VztC8MnnjvXBECzmHk_qNA_srfCNvFLY=
968101
false
25Sie können auch lesen
