E POSTBUSINESS API Versand-API Integrationsleitfaden. Version 1.2

Transkript

1 E POSTBUSINESS API Versand-API Integrationsleitfaden

2 Impressum Handbücher und Software sind urheberrechtlich geschützt und dürfen nicht ohne schriftliche Genehmigung der Deutschen Post AG kopiert, vervielfältigt, gespeichert, übersetzt oder anderweitig reproduziert werden. Dies gilt sinngemäß auch für Auszüge. Alle Rechte bleiben vorbehalten. Die Deutsche Post AG ist berechtigt, ohne vorherige Ankündigungen Änderungen vorzunehmen oder die Dokumente/Software im Sinne des technischen Fortschritts weiterzuentwickeln. Warennamen werden ohne Gewährleistung der freien Verwendbarkeit benutzt. Alle Warenund Produktnamen sind Warenzeichen oder eingetragene Warenzeichen der jeweiligen Eigentümer Deutsche Post AG Versand-API Integrationsleitfaden

3 Inhalt 1 E POSTBUSINESS API Zweck dieses Dokuments Überblick E POST Briefversand Ihre Vorteile für Sie als E POST Partner Vorteile für Ihre Kunden 3 2 In drei Schritten zur Partner-Anwendung Registrierung Implementierung Abnahme 5 3 Technische Umsetzung Entwicklungsschritte Login-Prozess Versand-Prozess Beispiele 9 4 Weitere Informationen und Support 12 Versand-API Integrationsleitfaden

4 1 E POSTBUSINESS API 1 E POSTBUSINESS API 1.1 Zweck dieses Dokuments Dieses Dokument gibt Ihnen einen Überblick über die Funktionsweise der E POSTBUSINESS API sowie eine Hilfestellung für die Integration der Versand API in Ihre Software. 1.2 Was ist die E POSTBUSINESS API? Überblick Mit E POSTBUSINESS API, der kostenlosen Webservice-Schnittstelle zum E POST System, integrieren Sie E POST direkt in Ihre Software. Wenn Sie E POST Partner werden, können Ihre Kunden Briefe elektronisch an die Deutsche Post übertragen und sparen sich das Drucken, Kuvertieren und Frankieren sowie den Weg zur Post. Mit E-POST den Versandprozess verkürzen und sparen. Klassischer Briefversand 1. Dokument erstellen 2. Drucken 3. Kuvertieren 4. Frankieren 5. Versenden 6. Zustellung E-POST Briefversand über API-Schnittstelle 1. Dokument in Anwendung erstellen (z. B. Warenwirtschafts-Software) 2. Elektronische Übermittlung aus der Anwendung an E-POST 3. Zustellung digital oder postalisch Abbildung Versandprozess verkürzen Preise Im Hilfe-Bereich für Geschäftskunden finden Sie die aktuellen Preise für den Versand von E POSTBRIEFEN ( e_post_nutzen/abrechung/wieviel_kostet_epostbrief.html). Rechnungen Der Rechnungsversand erfolgt monatlich digital per E POSTBRIEF. Bequemer Briefversand aus Ihrer Software Die Versand API ist der Teil der E POSTBUSINESS API, mit der Nutzer Briefe versenden können. Diese können dabei zwischen dem elektronischen Versandweg oder der physischen Zusendung per Zusteller wählen. Empfänger mit E POSTBRIEF Adresse können auf Wunsch Sendungen auch ausgedruckt auf dem klassischen Versandweg erhalten. Versand-API Integrationsleitfaden 1

5 1 E POSTBUSINESS API Absender E-POST Empfänger Ihre Software Druck und physische Zustellung Empfänger ohne E-POSTBRIEF Adresse... z. B. Rechnung schreiben Login mit eigener E-POSTBRIEF Adresse des Absenders (Registrierung notwendig) Elektronischer Versand Empfänger mit E-POSTBRIEF Adresse Abbildung Funktionsweise der Versand API 1.3 E POST Briefversand Elektronischer Versand Mit dem E POSTBRIEF verschicken und empfangen Nutzer Ihrer Software bequem digitale Briefe, Einschreiben online und sogar kostenlose Faxe. Überall, rund um die Uhr und dabei immer vertraulich und sicher. Für den Empfang implementieren Sie die Mailbox API, weitere Informationen siehe Mailbox-API Referenz. Für den elektronischen E POSTBRIEF Versand gelten einfache Rahmenbedingungen: Der Dateianhang kann bis zu 99 PDF-Dateien umfassen. Die Summe der Dateigrößen der gelieferten PDF-Dokumente kann bis zu 20 MB pro E POSTBRIEF sein. Physischer Versand Bei der physischen Zustellung d. h. der E POSTBRIEF wird in Papierform zugestellt können Sie Ihren Nutzern folgende Druckoptionen anbieten: Schwarzweiß- oder Farbdruck Simplex-Druck (einseitig) oder Duplex-Druck (beidseitig) Zudem können Ihre Nutzer bei der physischen Zustellung neben der Standard-Variante eines E POSTBRIEFS Zusatzleistungen verwenden: Einschreiben (ohne Optionen): Nicht nur der Empfänger persönlich, sondern auch ein berechtigter Empfänger, z. B. ein Ehegatte, darf den Empfang bestätigen. Einschreiben Einwurf: Der Zusteller der Deutschen Post AG legt den Brief in einen Briefkasten, Postfach o.ä. des Empfängers und bestätigt dies mit seiner Unterschrift. Einschreiben nur mit Option Eigenhändig: Ausschließlich der Adressat darf den Empfang bestätigen. Einschreiben nur mit Option Rückschein: Der Versender bekommt die handschriftliche Bestätigung eines berechtigen Empfängers über die Zustellung als Original zugesandt. Versand-API Integrationsleitfaden 2

6 1 E POSTBUSINESS API Einschreiben mit den Optionen Eigenhändig und Rückschein: Der Versender bekommt die handschriftliche Bestätigung des Empfängers persönlich über die Zustellung als Original zugesandt. Der Druck erfolgt im Format A4 auf weißem Standardpapier. Es werden weiße Briefumschläge verwendet. Individuell gestaltete Umschläge sind nicht möglich. Empfänger physischer E POSTBRIEFE müssen über eine gültige postalische Adresse in Deutschland adressiert werden. Auslandsvesand ist nicht möglich. Erfolgt eine Einlieferung bis 14:00 Uhr, kann in der Regel eine Produktion der physischen Schreiben noch am selben Kalendertag erfolgen. Maßgeblich ist der Zeitpunkt der Übergabe durch die Software an die Systeme der Deutschen Post AG. Digitale Briefe werden sofort zugestellt. Alle elektronisch eingehenden E POSTBRIEFE werden an das E POST Portal Ihres Kunden geschickt, wenn Sie keine Empfangsfunktionen über die Mailbox API in Ihre Software integrieren. In diesem Fall muss Ihr Kunde von Ihrer Software auf wechseln, um seine erhaltenen E POSTBRIEFE abzurufen. Wenn Sie Empfangsfunktionen in Ihre Software integrieren möchten, finden Sie weitere Informationen in der Mailbox-API Referenz. 1.4 Ihre Vorteile für Sie als E POST Partner Wenn Sie E POST Funktionalitäten über die E POSTBUSINESS API in Ihre Software eingebunden haben und Ihre Kunden sich bei E POST angemeldet haben, sind Sie E POST Partner. Das bietet Ihnen gleich mehrere Vorteile: Sie steigern die Attraktivität und den Mehrwert Ihres Produktes. Sie können durch den einfachen und günstigen Briefversand aus Ihrer Software neue Kundenpotentiale ausschöpfen. Sie profitieren von attraktiven E POST Provisionsmodellen. Sie erhalten E POST Siegel und Zertifikat. Sie bewerben Ihre Software als Partner des DAX-Konzerns Deutsche Post DHL Group. Sie erhalten Marketingunterstützung zur Platzierung Ihrer Software. Sie erscheinen auf E POST Webseiten mit Ihrer Software als Referenz. 1.5 Vorteile für Ihre Kunden E POST erledigt für Ihre Nutzer größtenteils automatisch, was sie bisher manuell getan haben. Die Vorteile des elektronischen Versands sind neben dem günstigen Preis (Dateianhang bis 20 MB zum Preis eines Standardbriefes) die sofortige Übermittlung des Briefes ohne einen Zeitverzug durch Druck, Kuvertieren sowie Frankieren und der abschließenden Zustellung. Sowohl für elektronische als auch physische Briefe entfallen Druckmaterialien wie Papier und Druckerpatronen sowie ein aufwändiger Versandprozess. Das spart Zeit und Kosten. Versand-API Integrationsleitfaden 3

7 1 E POSTBUSINESS API Durch die digitale Zustellung wird der CO²-Ausstoß vermindert und die Umwelt wird geschont. Verweis auf E POST Registrierung Damit Ihre Kunden die Services der E POSTBUSINESS API nutzen können, müssen sie eine vollständige Registrierung als E POST Nutzer abgeschlossen haben. Prinzipiell sind Ihre Services für alle E POST Kunden nutzbar, die sich als Privatkunde oder Geschäftskunde registriert haben. Die Registrierungen für die beiden Kundengruppen finden sich auf der E POST Webseite unter unter: (Privatkunden) (Geschäftskunden) Versand-API Integrationsleitfaden 4

8 2 In drei Schritten zur Partner-Anwendung 2 In drei Schritten zur Partner-Anwendung 2.1 Vorgehen Registrierung 1. Registrieren Sie sich auf dem Partnerportal, um den Anbindungsprozess zu starten ( 2. Wenn Sie noch kein E POST Kunde sind, registrieren Sie sich auf der E POST Webseite ( Der Start der Implementierung ist ohne Anmeldung als E POST Kunde möglich. Spätestens zur Abnahme Ihrer Implementierung brauchen Sie eine E POST Adresse. Daher empfehlen wir eine frühzeitige Anmeldung, um Verzögerungen bei der Abnahme zu vermeiden. Ergebnis Sie erhalten Zugriff auf alle relevanten Informationen für die Entwicklung Ihrer Anwendung. 2.2 Vorgehen Ergebnis Ergebnis Implementierung 1. Fordern Sie Ihre Zugangsdaten zur Testumgebung an ( Sie erhalten einen Zugang zur Testumgebung. 2. Entwickeln Sie Ihre Anwendung. Ihre Anwendung kann im Testbetrieb E POSTBRIEFE versenden. Der Briefversand über die Testumgebung ist selbstverständlich kostenfrei. Digitale Briefe werden zugestellt, aber nicht gedruckt und physisch versendet. Bei Fragen oder Problemen in der Implementierungsphase wenden Sie sich gerne an unseren technischen Support (siehe 4. Weitere Informationen und Support). 2.3 Vorgehen Ergebnis Abnahme 1. Starten Sie den Abnahmeprozess nach Fertigstellung Ihrer Entwicklung. Dazu füllen Sie das Formular auf dem Partnerportal aus. Die Abnahme erfolgt auf der Testumgebung. 2. Ein Testmanager der Deutschen Post AG kontaktiert Sie und leitet Sie persönlich durch die Abnahme. Nach erfolgreicher Abnahme auf der Testumgebung erhalten Sie Ihre Produktivzugänge. 3. Führen Sie zusammen mit Ihrem Testmanager einen Test zur Produktionsintegration durch. Diese ist erfolgt, wenn Sie mit Ihrer Software ausgehend von einem produktiven Account einen E POSTBRIEF versenden können. Versand-API Integrationsleitfaden 5

9 2 In drei Schritten zur Partner-Anwendung Zur Abnahme gehören neben funktionalen Tests auch ein Security Review sowie eine Überprüfung der Masken Ihrer Software, in der E POST implementiert ist. Ergebnis Die Abnahme Ihrer Anwendung ist abgeschlossen und Sie können den Produktivbetrieb starten. Versand-API Integrationsleitfaden 6

10 3 Technische Umsetzung Technische Umsetzung Entwicklungsschritte Für die Implementierung setzen Sie schrittweise Funktionalitäten um: Login Hohes Authentifizierungsniveau für den Versand von elektronischen und physischen Briefen Normales Authentifizierungsniveau für den Versand von physischen Briefen Entwurf anlegen Vor dem Versand muss ein Entwurf angelegt werden. Dieser enthält die nötigen Metainformationen wie Empfängeradresse und Versandart sowie das Anschreiben und einen PDF-Anhang Entwurf versenden Versand des Entwurfs mit Angabe der Druckoptionen bzgl. eines Deckblatts, Farbangabe und Briefzusatzleistungen Rückmeldung erhalten Rückmeldung über die erfolgreiche Übermittlung der Daten durch HTTP-Statuscodes Abbildung Entwicklungsschritte 3.2 Login-Prozess Durch den Login-Prozess ermöglichen Sie es E POST Nutzern, sich über Ihre Applikation am E POST System anzumelden. Eine solche Anmeldung ist Voraussetzung, um E POSTBRIEFE zu versenden. Die E POSTBUSINESS API unterstützt für den Login- Prozess zwei grundsätzliche Authentisierungs-Verfahren. Es stehen Ihnen zwei Authentisierungs-Verfahren zur Verfügung: 1. Resource Owner Password Credentials Grant Der Nutzer meldet sich über Ihre Anwendung am E POST System an. Ihre Anwendung speichert die Anmeldedaten. Der Vorgang erzeugt ein normales Authentifizierungsniveau, das zum Versenden von physischen E POSTBRIEFEN benötigt wird. Ein Versand von elektronischen E POSTBRIEFEN ist mit diesem Authentifizierungsniveau nicht möglich. Es ist möglich, das Authentifizierungsniveau nachträglich zu erhöhen, um einem Nutzer zu ermöglichen, elektronische E POSTBRIEFE zu versenden. In diesem Fall muss der Anwender seine HandyTAN eingeben. Versand-API Integrationsleitfaden 7

11 3 Technische Umsetzung Mit Resource Owner Password Credentials Grant speichert Ihre Anwendung die E POST Anmeldedaten des Nutzers. Es ist für ihn somit nur eine einmalige Authentifizierung zum Versenden von physischen E POSTBRIEFEN notwendig. 2. Authorization Code Grant Der Nutzer meldet sich über Ihre Anwendung am E POST System an. In einem weiteren Schritt gibt der Nutzer eine TAN ein, die er per SMS erhält (HandyTAN). Der Vorgang erzeugt ein hohes Authentifizierungsniveau, das zum Versenden von elektronischen E POSTBRIEFEN benötigt wird. Es ist ebenfalls möglich mit diesem Authentifizierungsniveau physische E POSTBRIEFE zu versenden. Mit Authorization Code Grant werden die Anmeldedaten des Nutzers nicht gespeichert. Der Nutzer authentifiziert sich bei jedem Login über das E POST System. Voraussetzung Vorgehen ü Ihnen liegt die Dokumentation Login-API Referenz vor. Prüfen Sie, welches Verfahren für Ihre Anwendung zum Einsatz kommen soll. Setzen Sie das Verfahren Authorization Code Grant um, wenn Sie die Anmeldedaten nicht in Ihrer Anwendung speichern. 1. Setzen Sie die Nutzer-Anmeldung so um, dass zunächst eine Anmeldung mit normalem Authentifizierungsniveau erfolgt. Es ist an der Stelle dadurch für einen Nutzer keine Eingabe einer HandyTAN notwendig. Die Eingabe von E POST Adresse und Passwort ist ausreichend. Weitere Informationen siehe Login-API Referenz: Authorization Code Grant. Ergebnis Mit diesen Anmeldedaten ist ein Versand von physischen E POSTBRIEFEN möglich. 2. Wenn ein Nutzer elektronische E POSTBRIEFE versenden möchte, ist es notwendig, dass Sie über Ihre Anwendung das hohe Authentifizierungsniveau anfordern. Dies setzen Sie mit einer weiteren Funktion um. Weitere Informationen siehe Login-API Referenz: Authentifizierungsniveau erhöhen. Setzen Sie das Verfahren Resource Owner Password Credentials Grant um, wenn Sie die Anmeldedaten eines Nutzers in Ihrer Anwendung speichern. Dadurch ist es für einen Nutzer nur einmal notwendig, sich für das E POST System zu authentifizieren. Weitere Informationen siehe Login-API Referenz: Resource Owner Password Credentials Grant. Voraussetzung zur Nutzung des Resource Owner Password Credentials Grant -Verfahrens: Vorlage eines Sicherheitskonzepts E POST setzt hohe Standards in Bezug auf Sicherheit, weshalb die Vorlage eines Sicherheitskonzepts für die Speicherung von Nutzerdaten notwendig ist. Wenn Sie das Verfahren wählen, teilen Sie uns dies im Verlauf des Anbindungsprozesses mit. Bei Bedarf erhalten Sie eine Vorlage für das Sicherheitskonzept. Versand-API Integrationsleitfaden 8

12 3 Technische Umsetzung 3.3 Versand-Prozess Zur Umsetzung des Versand-Prozesses verwenden Sie verschiedene Ressourcen der Versand API. Nachfolgend ist der Prozess für die korrekte Umsetzung in Ihrer Anwendung dargestellt. Voraussetzung ü Ihnen liegt die Dokumentation Versand-API Referenz vor. Vorgehen 1. Implementieren Sie den Login-Prozess, wie in 3.2 Login-Prozess beschrieben. 2. Setzen Sie zunächst die Funktionalität zum Anlegen eines Entwurfs um. Weitere Informationen siehe Versand-API Referenz: Entwurf mit Metadaten, Anschreiben und Anhängen erstellen. Damit der Brief zugestellt werden kann, ist es notwendig, dass vorgegebene Sperrflächen eingehalten werden. PDFs, die nicht den Vorgaben entsprechen, werden abgewiesen. Es erfolgt immer ein Druck mit Rand. 3. Implementieren Sie für den physischen Versand eine Funktionalität, die die Einhaltung der Sperrflächen berücksichtigt. TIPP Sie können einem Nutzer über eine Vorschau-Funktion die Einhaltung der Sperrflächen deutlich machen. Wenn keine elektronische Zustellung eines E POSTBRIEFS erfolgt, dann werden die Schreiben zentral im Auftrag der Deutschen Post AG produziert und gedruckt. Bei der Druckproduktion von physischen E POSTBRIEFEN Ihrer Endkunden werden standardisierte Produktionsverfahren genutzt. Weitere Informationen siehe Versand-API Referenz: Druckproduktion von E POSTBRIEFEN. TIPP Sie können die Funktion Adressanreicherung aktivieren. Dadurch wird beim Einliefern eines Briefes mit einer postalischen Empfängeradresse geprüft, ob es für den Empfänger eine E POST Adresse gibt. Im Erfolgsfall wird der Brief als elektronischer E POSTBRIEF zugestellt. 4. Wenden Sie im nächsten Schritt die Preisabfrage auf den angelegten Entwurf an. Diese Informationen stellen Sie dem Nutzer vor der Versand-Möglichkeit in Ihrer Software zur Verfügung. Weitere Informationen siehe Versand-API Referenz: Preisindikation für Entwurf abfragen. 5. Nach der Darstellung der Kosten des Versands stellen Sie dem Nutzer die Möglichkeit zum Versenden zur Verfügung. Weitere Informationen siehe Versand-API Referenz: Entwurf versenden. 3.4 Beispiele Die folgenden Beispiele zeigen empfehlenswerte Umsetzungen mit der Versand API. Versand-API Integrationsleitfaden 9

13 3 Technische Umsetzung Briefvorschau Nachfolgend sehen Sie die beispielhafte Umsetzung einer Briefvorschau. Durch eine Vorschau können Sie dem Nutzer auf einen Blick anschaulich machen, wie das Layout eines zu versendenden E POSTBRIEFS aussieht (Abbildung auf Seite 10): 1. Anzahl an Seiten 2. Umschlag inklusive Adressfeld 3. Layout des Briefs 4. Einzuhaltende Sperrflächen Abbildung Briefvorschau Versandfunktion Das folgende Beispiel zeigt die Umsetzung der Versandfunktion (Abbildung auf Seite 11): Eine Übersicht zeigt die Anzahl und Art der zu versendenden Schreiben (Abbildung auf Seite 11, Position 1): elektronisch klassisch Eventuell wird der Gesamtpreis angezeigt. Preisindikation nur bei Privatkunden empfohlen Der Gesamtpreis lässt sich bei Privatkunden anzeigen (Abbildung auf Seite 11, Position 2). E POSTBRIEFE von Geschäfstkunden werden am Monatsende gemäß der Preisliste abgerechnet. Wir empfehlen deshalb, für Geschäftskunden keine Preisindikation abzurufen (Abbildung auf Seite 11). Denn die angezeigten Preise können beispielsweise durch Rabatte von den tatsächlich in Rechnung gestellten Preisen abweichen. Versand-API Integrationsleitfaden 10

14 3 Technische Umsetzung Die Schaltfläche für den Versand ist mit Kostenpflichtig versenden bezeichnet (Abbildung auf Seite 11, Position 3) Abbildung Versandfunktion: Anzeige des Gesamtpeises bei Privatkunden Abbildung Versandfunktion: Anzeige nur der Briefanzahl und der Versandarten bei Geschäftskunden Versand-API Integrationsleitfaden 11

15 4 Weitere Informationen und Support 4 Weitere Informationen und Support Wir freuen uns, Sie bald als E-POST Partner begrüßen zu dürfen. Gerne helfen wir Ihnen mit weiteren Informationen weiter. Weitere Informationen Support Auf dem E POST Partnerportal ( finden Sie alle weiteren Informationen zur Verwendung der E POSTBUSINESS API: Versand-API Referenz Login-API Referenz Gestaltungsrichtlinien für die Verwendung der Marke E-POST in Partnersoftware Java-Code-Beispiele E POSTBUSINESS API SDK für C# Für Support-Anfragen wenden Sie sich per E Mail an die entsprechenden Ansprechpartner. E POST Partnermanagement Wenden Sie sich bei allgemeinen Fragen an [email protected]. E POST Partner-Support Wenden Sie sich für technische Fragen an [email protected]. Versand-API Integrationsleitfaden 12

16 Deutsche Post DHL Group Bei Fragen zur E POSTBUSINESS API finden Sie weitere Informationen auf dem E POST Partnerportal unter Das Partnermanagement bzw. der Partner-Support unterstützen Sie gerne: Allgemeinen Fragen: [email protected] Technische Fragen: [email protected] Deutsche Post AG Charles-de-Gaulle-Straße Bonn Stand: 02/2018