Unter dem Oberbegriff „E-POST“ gibt es verschiedene Möglichkeiten, Briefsendungen zur weiteren Verarbeitung an die Deutsche Post zu geben. Die dafür vorhandenen Lösungen werden Zugangsprodukte genannt.

Die E-POSTBUSINESS API ist eine Webservice-Schnittstelle (REST-API) zum Versand von hybriden Briefen direkt aus einer Software-Anwendung. Man steigert die Attraktivität und den Mehrwert einer individuell entwickelten Softwarelösung durch die API-basierte Integration des hybriden Briefversands und ermöglicht Software-Herstellern und/oder deren Endkunden sowie Eigenversendern die transparente Automatisierung des Postausgangs: einfach, günstig und CO2e-reduziert. Man spart so Zeit, Material und Ressourcen und die Zustellung erfolgt wie gewohnt zuverlässig mit der Deutschen Post.

Jeder Kunde der Deutschen Post erhält eine eindeutige Nummer, die sogenannte EKP. Diese wird im Rahmen eines Vertragsabschlusses mit der Deutschen Post, z.B. bei einer Produktregistrierung, automatisch generiert.

Die EKP dient der eindeutigen Zuordnung von Leistungen und Services und findet sich daher auch wieder auf unseren Verträgen, Rechnungen oder sonstiger Kommunikation mit der Deutschen Post.

Sollte die EKP nicht mehr bekannt sein, kann man unter Angabe der relevanten Kundenstammdaten diese beim Kundenservice der Deutschen Post (service@deutschepost.de) erfragen.

Jeder Anwender der über einen der E-POST-Kanäle Briefsendungen verschickt, unabhängig von dem Zugangsprodukt, ist ein E-POST Nutzer. Die erforderliche Vereinbarung zur Auftragsverarbeitung wird bei der Registrierung online abgeschlossen bzw. bei der API ist sie auch im API-Nutzervertrag bereits enthalten.

Jeder Endkunde/Versender, der Briefe in der Lösung eines Softwareherstellers über die E-POSTBUSINESS API versendet, schließt vorher durch die Registrierung auch diese E-POST Nutzervereinbarung ab, die die Vereinbarung zur Auftragsverarbeitung beinhaltet.

• Link zur API-Registrierung für Endkunden

Bitte beachten Sie, dass wir aus Sicherheitsgründen eine Registrierung mit eMail-Adressen allgemeiner Provider wie Gmail, GMX, etc. systemisch ablehnen, um unerlaubte Informationsabrufe über bestehende Kundenaccounts zu verhindern.

API-Nutzer sind Anwender, die die E-POSTBUSINESS API in eine vorhandene Softwarelösung implementieren. Dabei ist es unwesentlich, ob man die Lösung als Eigenversender oder als Softwarehersteller für Endkunden umsetzt.

Jeder API-Nutzer schließt mit der Deutschen Post einen API-Nutzervertrag ab. Der API-Nutzervertrag wird digital via DocuSign gezeichnet. Es ist dabei zu beachten, dass Vertragspartner der Deutschen Post immer der Nutzer der E-POSTBUSINESS API ist. Wird die Implementierung der E-POSTBUSINESS API durch einen Dritten, z.B. einen IT-Dienstleister durchgeführt, besteht zwischen diesem und der Deutschen Post kein Vertragsverhältnis.

• Link für Softwarehersteller/Eigenversender

Während der Entwicklungs- und Testphase entstehen keine Kosten für den API-Nutzer. Bei Produktivschaltung wird einmalig eine Anbindungspauschale von 275,- € in Rechnung gestellt und für die Nutzung der Schnittstelle fällt dann eine monatliche Servicepauschale von 59,- € an. Die Schnittstelle selbst kostet nichts. Für die Produktion und Versendung der Briefe über die E-POSTBUSINESS API gelten die öffentlich zugänglichen All-Inclusive-Preise - Preislisten.

Zur Verwendung der E-POSTBUSINESS API (Entwicklungs-/Testumgebung) werden die Zugangsdaten vom API-Support der Deutschen Post nach Vertragszeichnung bereitgestellt. Eine Entwicklung gegen die API wird zunächst immer im Testmodus durchgeführt. Ein physischer Versand ist in der Testumgebung grundsätzlich nicht möglich. Um in den Produktivmodus zu wechseln ist eine aktive Anforderung durch den API-Nutzer beim API-Support erforderlich.

Als Softwarehersteller/Eigenversender (API-Nutzer) benötigt man neben der eigenen Kundennummer (EKP), eine sogenannte [vendorID], die der API-Support nach Abschluss des API-Nutzervertrages zur Verfügung stellt.

Für die Freischaltung der Testumgebung sowie die Kommunikation wird eine eMail-Adresse hinterlegt. Die Adresse wird im System hinterlegt und ist gültig, bis z.B. eine Änderung über den Client Controller erfolgt.

Aus Datenschutzgründen wird für die Freischaltung der Entwicklungsumgebung zusätzlich der Freischaltcode per SMS (TAN) versendet. Diese TAN wird im System hinterlegt und ist gültig, bis z.B. eine Änderung über den Client Controller erfolgt.

Softwarehersteller/Eigenversender schließen einen API-Nutzervertrag mit der Deutschen Post ab. Dazu werden vorab die relevanten Vertragsdaten des Softwareherstellers/Eigenversenders per eMail abgefragt, um den Vertrag aufsetzen zu können.

Die erforderliche Zeichnung des Vertrages erfolgt elektronisch über DocuSign. Nach Zeichnung des Vertrages durch alle Beteiligten, wird der API-Support dem Softwarehersteller/Eigenversender die [vendorID] per eMail zur Verfügung stellen.

Für die Nutzung der E-POSTBUSINESS API während der Entwicklungs- und Testphase werden keine Kosten aufgerufen und man ist nicht zeitlich limitiert. Erst wenn man uns aktiv auffordert die Testumgebung produktiv zu schalten, beginnen die buchhalterischen Prozesse. Es ist auch technisch gewährleistet, dass in der Entwicklungs- und Testumgebung zu keinem Zeitpunkt Sendungen in die Produktion gehen können, so dass auch hier keine Kosten entstehen.

Bei einem bestehenden, aktiven API-Nutzervertrag kann man, um parallel zum Produktivbetrieb eine Testumgebung zu nutzen, beim technischen API-Support einen weiteren Vendor-Zugang anfordern. Dieser Zugang jedoch verbleibt immer im Testmodus, eine nachträgliche Produktivschaltung mit Ausleitung ins Druckzentrum ist nie möglich. Ansonsten stehen auch hier alle Funktionen der Entwicklungsumgebung zur Verfügung.

Nach einem erfolgreichen Login kann man über den Client Controller [SetMobile] die hinterlegte Mobilrufnummer ändern.

Um die hinterlegte Rufnummer zu ändern, muss man sich erfolgreich einloggen und Zugriff auf die bisher hinterlegte eMail-Adresse haben.

Per Client Controller wird ein Sicherheitscode über [MobileRequest] unter Angabe der neuen Mobilrufnummer an die hinterlegte eMail-Adresse gesendet. Dieser Code ist dann zusammen mit der neuen Rufnummer für die Aktualisierung über [SetMobile] zu übergeben. Zur Bestätigung der erfolgreichen Änderung wird automatisch eine SMS-Nachricht an die neue Rufnummer versendet.

Um die hinterlegte eMail-Adresse zu ändern, muss man sich erfolgreich einloggen und Zugriff auf die hinterlegte Mobilrufnummer haben.

Per Client Controller wird ein Sicherheitscode über [EMailRequest] unter Angabe der neuen eMail-Adresse an die hinterlegte Mobilrufnummer gesendet. Dieser Code ist dann zusammen mit der neuen eMail-Adresse für die Aktualisierung über [SetMail] zu übergeben. Zur Bestätigung der erfolgreichen Änderung wird automatisch eine eMail an die neue eMail-Adresse versendet.

Nach einem erfolgreichen Login kann man über den Client Controller [TestEMail] eine eMail an die hinterlegte eMail-Adresse zur Prüfung versenden.

Unabhängig von den technischen Zugangsdaten zur Verwendung der E-POSTBUSINESS API ist es erforderlich, die zentralen Kontaktdaten über [/api/Vendor/SetContactInformations] zu pflegen.

Gesetzt werden hierbei Daten wie der technische Ansprechpartner/Kontakt für Wartungsinformationen und Supportthemen. Der geschäftliche Ansprechpartner/Kontakt wird für die Kommunikation zu wichtigen Systemanpassungen und vertraglich/rechtlichen Themen verwendet.

Als Entwickler benötigt man für die Anmeldung an der E-POSTBUSINESS API die [vendorID], die der API-Support zur Verfügung stellt, die Kundennummer (EKP) der Deutschen Post, ein persönliches Kennwort und einen Sicherheitsschlüssel [secret]. Mit diesen Daten loggt man sich bei der API ein und erhält ein Laufzeittoken.

Um das [secret] zu erhalten, gehen Sie in der swagger Umgebung (Swagger UI) wie folgt vor:

• SMS-Code anfordern über die Route [/api/Login/smsRequest] (Verifizierung über die hinterlegte Mobilfunknummer)
  
• Passwort vergeben über die Route [/api/Login/setPassword] (hierfür wird der SMS-Code benötigt).
  
• Hier erhalten sie als Antwort das [secret].
• Ab jetzt können sie über die Route
  [/api/Login] einen Token für ihre Requests anfordern.

Das über die Route [/api/Login] angeforderte Token ist 24 Std. lang gültig und kann für mehrere Anfragen/Aufträge verwendet werden.

Zu Beginn der Entwicklung arbeitet man im Entwicklungsmodus der E-POSTBUSINESS API und kann alle Funktionen der API ohne Zeitlimit oder Kosten implementieren und nutzen. Im Entwicklungsmodus ist gewährleistet, dass keine versehentliche Dokumenteneinlieferung erfolgt und kostenpflichtige Briefsendungen produziert werden.

Der Wechsel vom Entwicklungsmodus zum Produktivmodus wird durch den API-Support vorgenommen. Wenn die Implementierung der E-POSTBUSINESS API abgeschlossen ist, kontaktiert man unter Angabe von

• Kunde/Unternehmen
• vendorID und
• EKP

den API-Support über EpostApiSupport@docuguide.com .

Nach Prüfung der Angaben schaltet der API-Support die Produktivumgebung frei und gibt dazu eine Rückmeldung. Jetzt können die Dokumente in das Druckzentrum übermittelt werden, um am Monatsende abgerechnet zu werden.

Erforderlich für die Aktivierung sind die Kundenummer (EKP) des Endkunden bei der Deutschen Post, die [vendorID] des Softwareherstellers (i.d.R. bereits in der Anwendung hinterlegt) und der Zugriff auf das Mobiltelefon, dessen Nummer der Endkunde bei der E-POST Online-Registrierung hinterlegt hat.

Durch die EKP des Endkunden wird an die in diesem E-POST Account hinterlegte Mobilnummer zeitnah per SMS eine TAN gesendet, die 10 Minuten gültig ist (siehe swagger Doku: [Login: smsRequest]).

Mit der erhaltenen SMS-TAN, der Kundenummer (EKP) des Endkunden und der [vendorID] des Softwarherstellers vergibt der Endkunde ein persönliches Kennwort (siehe swagger Doku: [Login: setPassword]) und er erhält einen Sicherheitsschlüssel [secret]. Dieser Sicherheitsschlüssel wird zusammen mit dem Kennwort für das Login benötigt.

Bei wiederholter oder fehlerhafter Registrierung wird der Bestellprozess für 3 Tage gesperrt, um Doppelregistrierungen zu vermeiden. In der Regel wird dann der folgende Fehler angezeigt:

Voraussetzung für den Erhalt einer SMS-TAN zur Aktivierung der E-POSTBUSINESS API ist der Abschluss der erforderlichen Verträge mit der Deutschen Post sowie die Hinterlegung einer Mobilrufnummer.

Ein Softwarehersteller/Eigenversender benötigt verpflichtend einen API-Nutzervertrag. Ein Endkunde benötigt eine E-POST Online-Registrierung.

Wurde die SMS-TAN im Rahmen der Aktivierung eines Endkunden angefordert und man erhält innerhalb weniger Minuten keine Rückmeldung, muss man davon ausgehen, dass die Anforderung nicht richtig abgeschlossen wurde. Gegebenenfalls sind die ursprünglich erfassten Daten nicht mehr korrekt.

Um das Problem zu beheben, muss der Endkunde sich an den Softwarehersteller/Entwickler der Softwarelösung wenden, der die erforderlichen Daten im swagger Portal ändern kann.

Alternativ ist eine Änderung über den Kundenservice der Deutschen Post möglich. Man wendet sich dafür an e-post@deutschepost.de.

Innerhalb der Servicezeiten kann der Kundenservice die Daten korrigieren. Nach Ablauf der 3-tägigen Sperrfrist kann die SMS-TAN erneut angefordert werden.

Nach erfolgreicher Anmeldung versendet man PDF/A-1b Dateien (base64 Daten) sowie die zugehörigen Metadaten. Die verwendeten Dateinamen der PDF/A-1b Dateien müssen dabei eindeutig sein.

Man kann sowohl einzelne Einlieferungen in einem Aufruf ausführen als auch mehrere Aufrufe über eine [batchID] gruppieren. Die erfolgreiche Einlieferung wird jeweils mit einer eindeutigen [letterID] für jeden eindeutigen Dateinamen quittiert. Die [letterID] ist übergreifend ein-eindeutig.

ACHTUNG: Es gilt zu beachten, dass Einlieferungen direkt in den Verarbeitungsmodus übergehen. Ein Rückruf nach Einlieferung ist nicht mehr möglich. Zur Prüfung vor finaler Übertragung in das Druckzentrum kann die Versendung mit dem Plugin [UploadManagement] verzögert werden.

Im Druckzentrum werden die Einlieferungen automatisiert validiert, aufbereitet und im fehlerfreien Falle in den Produktions- und Versandprozess überführt.

Fehlerhafte Schreiben in einer Einzeleinlieferung werden aussortiert, so dass der Rest der Einlieferung weiterverarbeitet werden kann. Dies gilt nicht für Sammeleinlieferungen (Batch-Einlieferung). Bei Fehlern durch Sendungen, die gesammelt eingeliefert werden, müssen alle Sendungen neu eingeliefert werden.

Die API quittiert die Einlieferungen mit einer eindeutigen [letterID]. Wenn man eine Fehlermeldung der API erhält (siehe Response Codes in swagger Schema), wird die Einlieferung abgebrochen. Die betroffenen Sendungen müssen neu eingeliefert werden.

Für Sendungen, bei denen eine versehentliche Doppeleinlieferung verhindert werden soll, kann die Dublettenprüfung aktiviert werden. Diese Funktion prüft, ob innerhalb der letzten Stunde bereits eine identische Sendung (basierend auf dem PDF-Inhalt) eingeliefert wurde.

Die Dublettenprüfung wird über das Flag [ActivateDuplicateFailsafe] im Letter-Objekt aktiviert. Wenn dieses auf true gesetzt wird, erfolgt eine Prüfung gegen alle Einlieferungen der letzten Stunde.

Wichtig zu beachten:

Es werden nur Einlieferungen untereinander geprüft, die ebenfalls das Flag [ActivateDuplicateFailsafe = true] gesetzt haben.

Sendungen ohne aktiviertes Flag werden weder geprüft noch bei der Dublettenerkennung berücksichtigt.

Wird eine Dublette erkannt (identischer PDF-Inhalt innerhalb der letzten Stunde), wird die Einlieferung mit dem Fehlercode E324 abgelehnt.

Die Prüfung erfolgt nur bei Sendungen, die zum Zeitpunkt der Prüfung einen LetterStatus ungleich 99 haben.

Das Zeitfenster der Dublettenprüfung beträgt 60 Minuten ab der ursprünglichen Einlieferung.

Diese Funktion ist besonders nützlich, wenn bei Verbindungsabbrüchen oder Timeouts nicht sichergestellt werden kann, ob eine Sendung bereits erfolgreich eingeliefert wurde. So wird verhindert, dass dieselbe Sendung versehentlich mehrfach versendet und berechnet wird.

Die verschlüsselten Eingangsdaten werden nach 90 Tagen gelöscht.

Um ein Schreiben zu einem bestimmten Termin zu versenden, nutzt man das Plugin [UploadManagement]. Sobald man das in der API beinhaltete Plugin mit den jeweiligen Optionen anspricht, kann der Anwender die Funktionen Terminversand (Sammelkorb). Eine Aktivierung des Plugins oder ein Upgrade der Schnittstelle ist nicht notwendig.

Um ein Schreiben an einem Stichtag zu versenden, muss man im Plugin [UploadManagement] die Option [useMinimumQuantity = false] setzen und einen entsprechenden Stichtag (bspw. [dueDays]) angeben. Der Stichtag kann maximal 31 Tage in der Zukunft liegen.

Sendungen mit [testFlag = true] können nicht zum Testen des Terminversandes genutzt werden.

Man kann beim Stichtag die Anzahl der Tage bis zum Versand [dueDays] angeben, wobei dies immer die Standardeinstellung mit einem Tag ist.

Alternativ kann man ein festes Datum mit Uhrzeit [dueDate] angeben. Die angegebene Uhrzeit wird berücksichtigt, jedoch muss der Produktionsstichtag um 14:00 Uhr beachtet werden. Eine weitere Alternative ist der Wochentag [dueDayofWeek], mit den möglichen Werten: Mo oder Di oder ...So, wobei hier dann bis 14:00 der aktuelle Wochentag betrachtet wird und nach 14:00 der kommende Wochentag.

Wichtiger Hinweis: Der Zählungszeitpunkt 14:00 berücksichtigt ausschließlich die zu diesem Zeitpunkt erfolgreich verarbeiteten Schreiben (LetterStatus 2). Dies muss man in der zeitlichen Kalkulation des Versandes berücksichtigen, so dass dieser entsprechend vorher stattfinden muss. Der Zeitpunkt kann grundsätzlich maximal 31 Tage in der Zukunft liegen.

Im Terminversand („Sammelkorb“) befindliche Sendungen kann man durch die Angabe der betroffenen LetterIDs löschen (siehe /api/Letter/CancelQueued).

Die Sendungen werden dann mit dem Status 99 versehen und können nicht mehr übertragen werden. Die bereits in Übertragung befindlichen Sendungen kann man nicht löschen, hier erhält man eine Fehlermeldung.

Im Terminversand („Sammelkorb“) befindliche Sendungen kann man durch die Angabe der betroffenen LetterIDs vorziehen und für die nächstmögliche Übertragung freigeben (siehe /api/Letter/ReleaseQueued).

Die bereits in Übertragung befindlichen Sendungen kann man nicht verändern, hier erhält man eine Fehlermeldung.

Es werden nur Sendungen im LetterStatus 4 berechnet. Sendungen, die einen LetterStatus 99 melden, werden abgebrochen und müssen erneut eingeliefert werden. Diese erreichen nicht den LetterStatus 4 und werden daher auch nicht abgerechnet.

Im Produktivbetrieb kann man bei Sendungen ein Test-Flag [testFlag] setzen. Dadurch wird die Sendung nur bis zur Prüfung (Status 2) verarbeitet. Eine Weiterleitung in das Druckzentrum erfolgt nicht.

Die Sendungen kann man als Anhang in einer eMail [testEMail] erhalten, wenn ein Test-Flag gesetzt wurde. Will man auf dem PDF-Dokument im Anhang Sperrflächenverletzungen anhand einer hervorgehobenen Schablone anzeigen lassen, setzt man ein Flag zur Aktivierung des Sperrflächenmodus [testShowRestrictedArea].

Hinweis: Die Testverarbeitung ist nur für eine administrative Vorabprüfung vorgesehen. Eine Einbindung in den Produktivversand ist nicht vorgesehen. Für die Einhaltung der jeweiligen Datenschutzrichtlinien bspw. der DSGVO bei Sendungen ist immer der Versender verantwortlich.

Es gibt für die E-POSTBUSINESS API kein Kundenportal der Deutschen Post, über das man die versendeten Briefe oder aufgelaufenen Kosten online prüfen kann. Die relevanten Informationen stehen aus der API zur Verfügung und als Software-Hersteller kann man diese Daten individuell aufbereiten. Dadurch lassen sich Reports oder ähnliches an die eigenen Prozesse oder Darstellungen anpassen.

Die von der API bereitgestellten Verarbeitungsschritte mit Zeitstempel dokumentieren, welchen Bearbeitungsstand die Sendungen zu welchem Zeitpunkt erreicht haben.

Folgende Statusmeldungen [LetterStatus] werden bereitgestellt:

Status	Verfügbarkeit des Status	Bedeutung
1	Direkt nach dem erfolgreichen Upload der Sendung durch die Software	Annahme der Sendung: Sendung wurde erfolgreich übermittelt und es wurden keine grundsätzlichen Schema- und Inhaltsverletzungen festgestellt.
2	Je nach aktueller Auslastung der API, maximal jedoch wenige Minuten nach Annahme der Sendung	Verarbeitung der Sendung: Sendung wurde auf E-Post-Konformität geprüft und ist für den Versand an das Druckzentrum freigegeben.
3	Je nach aktueller Auslastung der API innerhalb der nächsten Stunden nach Verarbeitung der Sendung, in der Regel jedoch nach ca. 30 min..	Einlieferung ins Druckzentrum: Übertragung der erfolgreich geprüften Daten in das Druckzentrum. Beispiel: Status 3 | Zeitstempel: Mo 11:00 Übertragung ins Druckzentrum: Montag 11:00 Uhr Hinweis: Sollten bei Einlieferung nachträglich technische Fehler in den PDF-Dokumenten festgestellt werden, führt dies im Druckzentrum zu einem Abbruch. Dies wird zeitnah über den Status 99 und einer entsprechenden Fehlerinformation dokumentiert. Der Status 4 wird nicht erreicht und die Sendungen müssen erneut eingeliefert werden.
4	Meldung ist in der Regel verfügbar 1-2 Tage nach Erreichen von Status 3	Verarbeitung im Druckzentrum: Die Sendung wird als "versendet" vom Druckzentrum an die API zurückgemeldet. Man erhält eine Produktionsquittung mit dem Zeitstempel der Verarbeitung im Druckzentrum. (ACHTUNG: Zeitversatz bei der Meldung!) Beispiel: Status 4 | Mi 14:00 | Zeitstempel: Mo 17:30 Am Mittwoch um 14:00 Uhr meldet die API den Status 4 unter Angabe des Zeitstempels Montag 17:30 Uhr. D.h., die Sendung wurde am Montag 17:30 Uhr produziert und ist dann direkt in den Versandprozess der Deutschen Post AG übergeben worden. Gemeldet wird diese Information in der API in diesem Beispiel jedoch mit einem Versatz von 2 Tagen am Mittwoch um 14:00 Uhr.
99	Zeitnah nach Feststellung des Fehlers/Problems	Verarbeitungsfehler: Die Verarbeitung wurde abgebrochen. Der Fehler ist vom Softwarehersteller bzw. Kunden zu prüfen und zu korrigieren. (Siehe auch Liste [Error]) ACHTUNG: Der Versand muss erneut angestoßen werden.

Hinweis: In Ausnahmenfällen kann es bei „Status 4“ Rückmeldung zu Verzögerungen kommen. Wenn man nach Erreichen von „Status 3“ aus dem Druckzentrum nicht innerhalb von 2 Stunden eine Fehlerrückmeldung zurückbekommt, kann von einer erfolgreichen und zeitnahen Produktion ausgegangen werden, selbst wenn die Produktionsquittung verzögert an die API geliefert wird.

Diese Information wird zusätzlich zu den durch die Schnittstelle selbst generierten Status 1-4 durch den Service "Verfolgen Brief (BZE-Tracking)" der Deutsche Post AG zur Verfügung gestellt und dokumentiert den Bearbeitungsstatus der Sendungen im Ziel-Briefzentrum (Briefzentrum Eingang (BZE)).

Diese Informationen dokumentieren, dass die Sendungen in der Region der Zieladresse (d.h. im Zielgebiet) eingetroffen sind und bearbeitet werden. Der nächste und abschließende Schritt ist der Weitertransport an den lokalen Zustellstützpunkt und die Zustellung an den Empfänger.

Dabei wird der Bearbeitungsstatus auf Basis des ersten BZE-Scans (Briefzentrum Eingang = Briefzentrum in Empfängerregion) übermittelt. Zu diesem Status wird das entsprechende Datum des Bearbeitungstags mitgeliefert. Der Bearbeitungstag beschreibt den Zeitraum von 7.00 Uhr bis 6.59 Uhr am Folgetag und gibt den Tag des Scannens im Zielbriefzentrum an.

Neben dem Bearbeitungstag mit der Information "im Zielgebiet angekommen" bzw. "Ziel-Briefzentrum" enthält der Datensatz zu einer Sendung auch die FrankierID der Sendung. Zudem wird bei Sendungen, die aufgrund eines Nachsendeauftrags im Rahmen der Bearbeitung im BZE weitergesandt werden, der Status "Nachsendung erfolgt" bzw. "Nachsendung" jeweils mit dem entsprechenden Datum angezeigt.

Der Service "Verfolgen Brief (BZE-Tracking)" umfasst alle inländischen hybriden Briefsendungen, die über die E-POSTBUSINESS API versendet werden (ausgenommen Einschreiben). Internationale Briefe, die an ausländische Empfangsadressen geschickt werden, sind von diesem Service ausgenommen.

Wichtig: Es wird nicht die Zustellung an den Empfänger durch den Zusteller dokumentiert!

Der Briefstatus [LetterStatus] wurde im Einzelnen um die Felder erweitert:

• <frankierID> Frankier-ID
• <destinationAreaStatus> BZE / REDIRECTED / keine Information
• <destinationAreaStatusDate> Datum der Bearbeitung im Briefzentrum / keine Information

Die konkreten Benennungen in der jeweiligen eingesetzten Software können davon abweichen.

Die E-POSTBUSINESS API stellt technisch die aktuellen Informationen aus der Sendungsverfolgung im Briefstatus [LetterStatus] bereit. Zusätzlich befinden sich diese und mögliche vergangene Meldungen (bspw. das Ereignis einer Nachsendung) als Informationshinweis im Fehler-Container [Error Object]. Die Bereitstellung und Darstellung dieser Daten ist jedoch von der jeweiligen Umsetzung in der eingesetzten Software abhängig und obliegt somit dem jeweiligen Softwareanbieter.

Den Status jeder einzelnen Einlieferung kann man über die [letterID] für 400 Tage abrufen. Diesen kann man gezielt

• auf eine [letterID], bzw. dedizierte letterID’s
• mengenbasiert über eine [batchID],
• einen Zeitraum abfragen.

Mengenabfragen können auf die fehlerhaften Einlieferungen eingeschränkt werden. Die einzelnen Status IDs sind in der API beschrieben, wobei der Status 4 die Überführung in den Produktionsprozess darstellt.

Im Falle des Status 99 fand ein Abbruch statt. Zusammen mit den jeweiligen Zeitpunkten (Sendungsannahme, Verarbeitung im Rechenzentrum, Einlieferung Druckzentrum, Rückmeldung Druckzentrum) ist der jeweilige Statusübergang ersichtlich. Fehler werden genauer über Fehlerobjekte beschrieben.

Die bereitgestellte Eingrenzung des Zeitraumes bezieht sich auf den Zeitpunkt der Sendungsannahme [createdDate] der Dokumente. Da zum einen der Rückmeldezeitpunkt des Produktionsdatums [
printFeedbackDate] i.d.R. einen Zeitversatz von 1-2 Tagen hat und somit vom Tag der Sendungsannahme [createdDate] abweicht, ist für eine Prüfungen auf Produktionszeiträume ein entsprechendes größeres Zeitfenster zur Abfrage vorzusehen und zusammen mit der korrekten Statusbetrachtung eine Filterung auf das Produktionsdatum [printFeedbackDate] vorzunehmen.

Die Statusabfragen bieten auch die Möglichkeit, nur die noch in Bearbeitung befindlichen Sendungen (Status 1-3) abzufragen.

Verweilen Sendungen über einen längeren Zeitraum im Status 2, nutzen sie in der Regel den Terminversand (Sammelkorb). Dies kann man durch Abfrage des [LetterStatus] und der Auswertung des Feedbacks aus dem Terminversand Plugin [UploadManagementFeedback] überprüfen.

Für den dringenden Fall der Anpassung, kann man ausschließlich Sendungen im Terminversand (Sammelkorb) beeinflussen. Hierbei kann man den Status von Sendungen verändern. Sie werden in den Fehlerfall überführt (Status 99) oder vorgezogen, so dass sie Teil des nächsten Uploads zum Druckzentrum werden.

Sollte jedoch bereits die Übertragung in das Druckzentrum begonnen haben, ist dies nicht mehr möglich. Dies gilt auch für Sendungen, die bereits ins Druckzentrum übertragen wurden.

Siehe auch entsprechende Abschnitte im Kapitel „Einlieferung der E-POST Sendungen“.

Mögliche Optionen: Einwurf Einschreiben | Einschreiben | Einschreiben Rückschein. Einschreiben können simplex/duplex versendet werden. Über die E-POSTBUSINESS API sind internationale Einschreiben nicht möglich.

Die Inhalte der „Track And Trace“-Statusmeldungen werden aus dem Elektronischen Auftragsmanagement der Deutschen Post bereitgestellt. Die ausführlichen Dokumentationen und Code Tabellen sind dort unter Download einsehbar. Detailliertere Erklärungen zur Bedeutung der Statusinformationen werden auch hier bereitgestellt.

Über die Statusabfrage für Einschreiben [get /api/Letter/Registered] erhält man über einen definierten Zeitraum den Status der Einschreiben, wobei man dies auf die offenen Rückmeldungen einschränken kann.

Der letzte Status und der Zeitstempel sind als eigene Attribute gelistet [registeredLetterStatus], [registeredLetterStatusDate]. Die Historie findet sich in der [errorList] als InfoObjekt (I701) in der ermittelten Reihenfolge.

Über die [EinschreibenID] der Sendung wird zusätzlich regelmäßig der aktuelle Status ermittelt. Eine dedizierte EinschreibenID kann nicht übergeben werden. Die über die API zurückgemeldeten möglichen Inhalte des Status sind unter Sendungsstatus Einschreiben (JSON) gelistet. Dort sind auch die Statuscodes hervorgehoben, die einen finalen Endzustand darstellen.

Im API Developer Portal der Deutschen Post/DHL findet man auch die Sendungsverfolgungs-APIs „Shipment Tracking – Unified“ sowie „Shipment Tracking - Unified – Push“. Die Shipment Tracking – Unified API kann auch innerhalb kürzester Zeit in Ihre eigene Anwendung integriert werden. Der Status wird Ihnen in einem einheitlichen Schema zur Verfügung gestellt und bietet minutengenaue Sendungsstatusberichte.

Über ein Testflag kann man eine Verarbeitung (Validierung, Aufbereitung, etc.) ohne eine Überführung in das Druckzentrum auslösen. Der jeweilige Status mit den Fehlerobjekten gibt Auskunft über die Verarbeitungsmöglichkeit oder Ablehnungen.

Zusätzlich kann zur Qualitätskontrolle für 48h via [letterID] das erzeugte PDF über die API-Funktion [get /api/Letter/TestResult] abfragt werden. Alternativ kann man das aufbereitete Dokument an eine individuelle eMail-Adresse senden.

Auf der swagger-Seite unter [Schema/Error] sind die Fehlercodes und Details gelistet, die über die API zurück gemeldet werden können.

Man kann die Funktionsbereitschaft [GET /api/Login/HealthCheck] der API jederzeit über den Login Controller abfragen, eine Anmeldung ist hierfür nicht notwendig. Mögliche Wartungsfenster werden hierüber ebenfalls bekannt gegeben.

Für größere API-Partner mit entsprechenden Client-Servern oder Eigensender mit festen IT-Infrastrukturen besteht die Möglichkeit, den Zugriff auf die E-POSTBUSINESS API auf bestimmte IP-Adressen oder IP-Adressbereiche einzuschränken. Diese zusätzliche Sicherheitsmaßnahme wird als IP-Whitelisting bezeichnet.

Wichtig: Das IP-Whitelisting ist eine Einrichtungsmaßnahme, die vom technischen API Support durchgeführt wird. Es handelt sich hierbei nicht um einen Selbstservice über die API.

Wenn Sie Interesse an der Einrichtung eines IP-Whitelistings haben, wenden Sie sich bitte an den technischen API Support unter EpostApiSupport@docuguide.com .

Folgende Informationen werden für die Einrichtung benötigt:
• Ihre Kundennummer (EKP)
• Ihre VendorID
• Die IP-Adresse(n) oder IP-Adressbereiche, von denen aus auf die API zugegriffen werden soll

Eine kurze Beschreibung der IP-Adressen (z. B. „Office-Netzwerk“, „Produktionsserver“)

Nach der Einrichtung können API-Anfragen nur noch von den hinterlegten IP-Adressen aus durchgeführt werden. Anfragen von anderen IP-Adressen werden mit einem entsprechenden Fehlercode (E006 – Kein Zugriff über diese IP-Adresse) abgelehnt.

Mit Hilfe des [Vendor] Controllers kann man sowohl die Anzahl der erfolgreichen Sendungen, bezogen auf einen Zeitraum, als auch die Anzahl der fehlerhaften Sendungen ermitteln, gruppiert nach Sendungsdetails pro Tag.

Die erfolgreich produzierten Schreiben [LetterDetailsByDay] werden gruppiert und im Schema [LetterDetailsPrintedByDay] für einen begrenzten Zeitraum bereitgestellt. Hierbei bezieht sich die Eingrenzung des Zeitraumes auf das Produktionsdatum [printFeedbackDate] im [LetterStatus].

Für die fehlerhaften Schreiben [LettersWithError] wird der [LetterStatus] verwendet, wobei dessen Inhalt reduziert wird, und auf die Fehler fokussiert ist. Hierbei bezieht sich die Eingrenzung des Zeitraumes auf den Zeitpunkt der Sendungsannahme [createdDate] im [LetterStatus].

Die [letterID] kann für die weitere Recherche genutzt werden, [fileName], [testMail], [registeredLetterID] und [custom1-5] werden leer zurückgeliefert.

Optional kann durch Ausschalten des Parameters [hideEKP] in [custom5] die für das Dokument verwendete EKP hinterlegt werden. Die [errorList] beinhaltet, analog zu den Ergebnissen der Statusabfragen, die ursächlichen Fehler und Informationen.

Zusätzlich zu [LetterDetailsByDay] kann man mit [LetterDetailsByDayAsCsv] die Daten als CSV erhalten.

Mit dem Zeitpunkt der Sendungsannahme [createdDate] können alle Dokumente abgefragt und deren Status ermittelt werden, unabhängig davon, ob sie produziert wurden oder Fehler aufweisen. Dieser Zeitstempel wird zum Zeitpunkt der Sendungsannahme vergeben.

Der Zeitpunkt der Verarbeitung [processedDate] zeigt, wann das jeweilige Dokument den Systemprüfungen unterzogen wurde und ggf. Fehler erzeugt hat. Dieser Zeitstempel wird nach der Verarbeitung vergeben.

Der Übergang in den Produktionsprozess wird über den Einlieferungszeitpunkt Druckzentrum
[printUploadDate] dokumentiert. Dieser Zeitstempel wird nach der erfolgreichen Bereitstellung vergeben.

Die Rückmeldung der Verarbeitung im Druckzentrum [printFeedbackDate] stellt den Produktionszeitpunkt des Dokumentes dar. Dieser Zeitstempel wird i.d.R. erst nach 1-2 Tagen aus dem Druckzentrum zurückgemeldet. Zur Validierung von Produktionsmengen auf der Rechnung sollte dieser Zeitstempel genutzt werden.

Der Umschlag ergibt sich aus der Kombination von Anzahl Blätter und Gewicht, wobei das maximale Gewicht sich aus der Blätteranzahl schon ergibt.

Geht man von unserem Papier mit 80g/m² aus, dann wiegt ein Blatt knapp 5g, ein Umschlag mehr oder weniger auch. Tinte ist dabei vernachlässigbar bzw. wird bei der Berechnung z.B. beim Großbrief mit 94 Blatt berücksichtigt.

Nachfolgend die Beispiele:

Standard bis 20g (inkl. 1 Blatt) 1 bis max. 3 Blatt   => 3 x 5g = 15g + Umschlag = 20g

Kompakt bis 50g (inkl. 4 Blatt) 4 bis max. 9 Blatt   => 9 x 5g = 45g + Umschlag = 50g

Groß bis 500g (inkl. 10 Blatt) 10 bis max. 94 Blatt => 94 x 5g = 470g + Umschlag und
Toner = 500g

Es gibt eine Mindestmenge an Metadaten, die jedes Dokument für eine ordnungsgemäße Verarbeitung bereitstellen muss. Sind diese Metadaten fehlerhaft oder weichen diese von den aufgedruckten Daten ab, führt dies in der Regel zu Verarbeitungsfehlern im Druck- oder Zustellprozess. Die Folge ist dann ggf. eine Unzustellbarkeit der Sendung und zusätzliche Kosten

Hinweis: Für eine vereinfachte Verarbeitung wird ein leerer Ländercode als „Deutschland“ interpretiert. Für Auslandssendungen muss man jedoch zwingend, neben der korrekten Anschrift, zusätzlich den korrekten Ländercode befüllen. Siehe JSON Ländercodes für Auslandssendungen

Wenn ein Dokument versendet wird, müssen immer die vollständigen Anschriftendaten mitgegeben werden, um die korrekte Zustellung zu gewährleisten.

Die Anschrift setzt sich immer aus einer gültigen (deutschen) Absenderadresse sowie einer Empfängerbezeichnung (bspw. Anrede, Vorname und Nachname, Firma, etc.) und der Adresse, bestehend aus Straße, Hausnummer, Adresszusatz, alternativ Postfach sowie PLZ und Ort, zusammen.

Für Auslandssendungen muss auch der Ländercode angegeben werden. Diese Kombination wird in den Metadaten gespiegelt. Hat man eine Empfängerbezeichnung, die sich nur über eine Zeile erstreckt, dann ist [adressLine1] bspw. für Anrede und Namen oder Firmenbezeichnungen vorgesehen.

Die [adressLine2] würde bspw. hierbei schon die Straße und die Hausnummer oder das Postfach beinhalten. Bei mehrzeiligen Empfängerbezeichnungen verschiebt sich dann der Inhalt der [adressLine2] entsprechend bis maximal zur letzten Zeile [adressLine5].

Diese Metadaten werden auch für ein Deckblatt herangezogen, wobei man zusätzlich noch die Metadaten des Versenders (bspw. [senderAdressLine1], [senderStreet], etc.) befüllen muss.

Die in der E-POSTBUSINESS API erforderlichen Sendungs-Metadaten (insbesondere PLZ, Ort und Land) dienen der optimierten, weiteren Verarbeitung im Versandprozess. Abweichungen zwischen diesen Metadaten und den aufgebrachten Empfängeranschriften führen im weiteren Prozess zu Verzögerungen in der Zustellung bis hin zur Ablehnung und Rückführung der Sendungen.

In der Regel werden Sendungen, bei denen die Metadaten von den Informationen auf der Empfängeranschrift abweichen, jedoch abgelehnt und nicht produziert. Diese Sendungen müssen korrigiert und erneut eingeliefert werden.

Es stehen bis zu fünf individuelle Felder [custom1-5] zur Verfügung, die man in der Einlieferung belegen kann und in der Statusabfrage zurückgeliefert werden.

Es gibt für die Absenderzeile kein eigenes Feld für ein Postfach, dafür kann das Feld [senderStreet] genutzt werden. Optional kann man die komplette Versenderadresse in einer Zeile übergeben
[senderAdressLineComplete], anstelle der einzelnen Versenderfelder und so das Postfach hinterlegen.

Wenn man keine Anschriften-Metadaten bereitstellen kann, bietet das PlugIn „Automover“ eine Möglichkeit, dennoch diese nationalen Schreiben zu versenden.

Siehe hierzu „Wie kann man automatisch nationale Anschriften mit „Automover“ repositionieren?“).

Das Einschreiben [registeredLetter] ist in Bezug auf das zu versendende Dokument eine Briefzusatzleistung. Nur im Falle des Rückscheins (bspw. [registeredLetter] = „Einschreiben Rückschein“) benötigt man die Daten zur Rücksendeadresse. Diese wird jedoch seit dem 01.10.2022 nicht mehr aus den Metadaten entnommen, sondern automatisch aus der Absenderzeile extrahiert. Die ursprünglich für den Rückschein erforderlichen Metadaten-Felder mit den Empfängerdaten Einschreiben
[registeredLetterAdressLine1 bis registeredLetterCity] werden daher nicht mehr ausgelesen und sollten leer gelassen werden.

WICHTIG: Es ist zwingend notwendig, immer eine Absenderzeile anzugeben, aus der im Falle des „Einschreibens mit Rückschein“ automatisch der Rückschein mit den Empfängerdaten befüllt wird.

Es steht ein eigenes Feld für die Hinterlegung einer Kostenstelle zur Verfügung [costCenter]. Der Eintrag muss alphanummerisch sein. Die hier hinterlegten Kostenstellen werden in der Monatsrechnung berücksichtigt. Die Umsätze/Kosten werden entsprechend auf der Monatsrechnung aufgeschlüsselt.

Die Metadaten zu den eingelieferten Sendungen, die vom Versender über die API abgerufen werden können, werden nach 400 Tagen gelöscht. In diesem Zeitraum kann man sich die Informationen wie folgt aus der API ziehen, wie z.B. über den Vendor Controller [GET LetterDetailsByDay] die erfolgreich versendeten Schreiben der letzten 400 Tage.

Dokumente, die an die E-POSTBUSINESS API übergeben werden, müssen dem Format

• PDF/A-1b und
• DINA4 Hoch entsprechen.

Abweichungen vom DINA4 Hoch-Format können nicht verarbeitet werden und führen zu Fehlern.

PDF-Dokumente, die nicht dem PDF/A-1b-Format entsprechen, werden, soweit möglich, durch einen Konverter systemisch aufbereitet. Sie sind daher vorab im Testmodus der E-POSTBUSINESS API zu prüfen, da in der Aufbereitung beispielweise fehlende Fonts durch Standards ersetzt werden oder Transparenzen in Bildern nicht die erwartete Briefdarstellung liefern. Diese Punkte können sonst eine einwandfreie Verarbeitung einschränken und sogar zur Ablehnung in der Verarbeitung führen.

Im Produktivbetrieb sollte man zum Testen bei den zu prüfenden Sendungen das Test-Flag setzen und sich den Brief an eine hinterlegte Test-eMail senden lassen. So ist eine Prüfung des Druckergebnisses im Vorfeld der finalen Versendung möglich und man vermeidet Probleme bei der Produktion.

Bei der Einlieferung von einzelnen PDF-Dateien dürfen diese pro Sendung 20 MB bzw. bei Einlieferung von mehrere PDF-Dateien als Batch 300 MB nicht überschreiten.

Hochauflösende Grafiken und/oder Dokumentenscans führen in der Regel zu einer übergroßen Datei, so dass hier die Auflösung (maximal 300 dpi) zu prüfen und ggf. zu reduzieren ist.

Die maximale Seitenanzahl pro Sendung beträgt 94 Seiten für Simplex und 188 Seiten für Duplex, so dass maximal 94 Blätter nicht überschritten werden dürfen.

Hinweis: Unter Umständen (z.B. Sonderschriften, sehr voll bedruckte Seiten und/oder komplexe, unkomprimierte Grafiken) überschreiten PDF-Dokumente, die bei der Einlieferung nicht im PDF/A-1b Format eingeliefert werden, erst nach der Konvertierung die maximal erlaubte Größe von 20 MB pro Sendung und werden daher abgelehnt!

Die API verwendet für die automatisiert auf der ersten Seite oder Deckblatt aufgebrachten Anschriftendaten die Schriftart Arial in Schwarz und die Fontgröße 8 für die Absenderadresse sowie die Fontgröße 9 für die Empfängeradresse.

PDF-Dokumente, die nicht als PDF/A-1b bereitgestellt wurden, werden überarbeitetet und fehlende Fonts nach Möglichkeit durch Standards ersetzt. Für die von der API automatisiert genutzten Schriftarten sind die Lizenzbestimmungen erfüllt. Grundsätzlich ist man als Versender für die Lizensierung der verwendeten Schriftarten/Fonts im Dokument selbst verantwortlich.

Man kann ein Standard-Deckblatt erzeugen, das den Absender und Empfänger aus den Metadaten der Einlieferung zieht. Darüber hinaus kann man alternativ ein eigenes Deckblatt als base64 PDF/A bereitstellen, dass dann mit den Metadaten der Einlieferung befüllt wird.

Grundsätzlich hat ein Blatt immer zwei Seiten, Vorder- und Rückseite. Abhängig von der Druckoption (Simplex/Duplex) kann die Anzahl der Blätter aus der rückgemeldeten Seitenzahl ermittelt werden.

Im Falle von Simplex ist die Blattzahl identisch der Seitenzahl, für Duplex muss dies dann entsprechend halbiert und aufgerundet werden.

Bei Nutzung der Deckblattoption wird das Deckblatt bei der gemeldeten Seitenanzahl berücksichtigt.

Sowohl für nationale als auch internationale Sendungen muss eine einzeilige Absenderzeile mit Adresse im Inland (Deutschland) an der vorgeschriebenen Position (siehe Briefschablone V3) aufgebracht werden.

Details findet man auch in den „Allgemeinen Geschäftsbedingungen und Datenschutzhinweisen der Deutsche Post AG für Geschäftskunden (AGB E-POST)“. Das Fehlen einer Absenderzeile führt zu einer Ablehnung der Sendung. Eine Produktion findet nicht statt.

Die Absenderzeile muss den Absender vollständig beinhalten und sollte nicht aus dem Sichtfenster herauslaufen. Dies lässt sich mittels der API-Testfunktion und dem Einblenden der Sperrflächen-Schablone überprüfen.

Wegen der erforderlichen Maschinenlesbarkeit ist die Absenderzeile einzeilig anzugeben und das Fehlen eine Absenderzeile ist nicht erlaubt. Weicht man davon ab, wird der Brief nicht verarbeitet.

Kann man die Vorgaben nicht einhalten, kann man ggf. die Absenderdaten abkürzen, die Schrift (mind. Font 6) verkleinern oder den Text über den rechten Fensterrand hinausgehen lassen. Der Brief wird dann zwar nicht abgelehnt, ist der Brief jedoch nicht zustellbar, ergeben sich ggf. Probleme, auf jeden Fall Verzögerungen, beim Rückversand an den Absender.

Hinweis: Bei „Einschreiben mit Rückschein“ sollte man auf jeden Fall die Vorgaben einhalten, denn die Rücksendeadresse des Rückscheins wird aus der Absenderzeile gelesen.

Eine Verletzung der Sperrflächen im Anschriftenfeld (gemäß Briefschablone V3) führt zu einem Fehler und somit zur Ablehnung der Sendung. Die Fläche für die DV-Freimachung sowie die Lesbarkeit der Absender- und Empfängerdaten sind ein wesentlicher Aspekt für die Produktionsfähigkeit der Sendungen.

Hinweis: Auch eine transparente Grafik, die in ein Sperrfeld ragt, wird als Fehler gewertet.

Eine Verletzung der Sperrflächen am linken Rand wird nur per Warnung angemerkt. Eine sonst E-POST konforme Sendung wird zwar produziert, doch Inhalte in dieser Randfläche vor der Produktion geweißt.

Mit Hilfe der Funktionen des Plugins „Automover“ kann man das vorhandene Anschriftenfeld (Sender- und Empfängeradresse) durch die bereitgestellten Metadaten überblenden.

Hierzu muss man zum einen „Automover“ aktiveren [useAutomover = true] und zum anderen im JSON-Container die Metadaten ([senderAdressLine1], [senderStreet], [senderZipCode], [senderCity], [addressLine1-5], [zipCode], [city]) bereitstellen.

Hinweis: Auf der ersten Seite der PDF wird der gesamte Sperrbereich des Absender- und Empfängerbereichs aus der Sperrflächenschablone V3 (Briefschablone) geweißt und dann mit den mitgegebenen Daten überschrieben.

Eine Kombination mit der Deckblatt-Funktion [coverLetter = true] erzeugt zwar ein Deckblatt, führt diese Funktion jedoch nicht aus und wird als Info im Error Objekt dokumentiert.

Man kann mit der Testfunktion der API das Ergebnis des Plugins „Automover“ prüfen.

Mit Hilfe der Funktionen des Plugins „Automover“ kann man das vorhandene, nationale Anschriftenfeld (Sender- und Empfängeradresse) automatisch repositionieren. Die Anwendung auf internationale Adressen wird nicht empfohlen, weil es aufgrund von abweichenden Feldinhalten zu Fehlern führt.

Hierzu muss man zum einen „Automover“ aktiveren [useAutomover = true] und zum anderen im JSON-Container die Metadaten [addressLine1], [zipCode] und [city] mit definierten Werten (siehe auch: Schema swagger Dokumentation „Automover“) befüllen.

Voraussetzung zur Repositionierung ist, dass Adressdaten des Senders und Empfängers in einem Bereich als erkennbarer Text auf der ersten Seite vorhanden sind. Dort werden diese Daten ermittelt, wobei dieser Bereich vorgegeben ist, aber auch über entsprechende Koordinaten angepasst werden kann.

Kann keine Empfängeradresse ermittelt werden, führt dies zu einem Fehler. Vorhandene Anschriften-Metadaten werden für die Suche nicht berücksichtigt.

Standardmäßig werden die ermittelten Adressdaten auf dem geweißten Sperrbereich aus der Sperrflächenschablone V3 (Briefschablone) der ersten Seite des PDF aufgebracht. Mögliche Inhalte werden somit überblendet. Die Adress-Metadaten [zipCode]und [city] werden mit den ermittelten Werten belegt und sind im LetterStatus-Objekt zu finden.

Hinweis: Man kann mit der Testfunktion der API das Ergebnis des Plugins „Automover“ prüfen.

Eine Kombination mit Einschreiben [registeredLetter] und/oder der automatischen Erzeugung eines Deckblattes werden nicht unterstützt, da hierfür die notwendigen Metadaten explizit vorliegen müssen.

Die meisten Auslandssendungen benötigen im Empfängerland eine Postleitzahl. Für Länder, die keine Postleitzahlen benötigen, ist das Pflichtfeld der Postleitzahl [zipCode] mit einer Mindestlänge von drei Leerzeichen zu befüllen.

Die Verantwortung zur korrekten Befüllung der Postleitzahl liegt beim Versender. Für Inlandssendungen ist die korrekte Postleitzahl anzugeben, die Befüllung mit Leerzeichen ist daher nicht zulässig.

Das Plugin „Automover” bietet verschiedene Funktionen zur automatischen (Re-)Positionierung von Adressdaten im Adressbereich:

• bestehenden Adressbereich im PDF automatisch repositionieren
• Adressbereich mit individuellen Metadaten überschreiben

Siehe dazu die weiteren Informationen zum „Automover“ in dieser Dokumentation sowie Schema „Automover“ in der openAPI-Dokumentation der Schnittstelle.

Das Plugin [UploadManagement] bietet verschiedene Optionen zur Versand-Steuerung (Terminversand/Sammelkorb) von Briefen.

• DueDays: Angabe, in wieviel Tagen ab Status 2 der Stichtag erreicht ist.
• DueDate: Angabe, zu welchem Datum der Stichtag für diese Sendung erreicht ist.
• DueDayofWeek: Angabe, an welchem Wochentag der Stichtag für diese Sendung erreicht ist.

Siehe dazu die Informationen zum [UploadManagement] in dieser Dokumentation sowie Schema „UploadManagement“ in der openAPI-Dokumentation der Schnittstelle.

Mit dem Plugin [PremiumAdress] erfahren Sie, welche Ihrer Sendungen nicht zugestellt werden konnten und erhalten Informationen über Umzüge und Gründe der Unzustellbarkeit.

Die Zusatzleistung PREMIUMADRESS steht in der E-POSTBUSINESS API in den Varianten Basis und Report zur Verfügung. Diese bieten folgende Informationen:

• Umzugsadresse, Umzugsinformation
• Unzustellbarkeitsinformation
• „Verstorben“-Information

Die E-POSTBUSINESS API bietet eine sehr einfache, standardisierte Möglichkeit der Nutzung von PREMIUMADRESS Leistungen an. Diese ist in ihrem Umfang begrenzt, so dass ausdrücklich nicht das gesamte Leistungsspektrum von PREMIUMADRESS zur Verfügung steht. Insbesondere ist die Nutzung weiterer optionaler Leistungen (Unzustellbarkeitsinformation mit Datenbankbestätigung, Adressrecherche) nicht möglich.

Die für diese Leistungen im Einzelnen ggf. erhobenen Kosten sind auf der PREMIUMADRESS Produktseite, auf der Seite „Leistungen“, unter „Leistungen und Preise“ aufgeführt.

PREMIUMADRESS kann für nationale Briefsendungen, ausgenommen Einschreiben, beauftragt werden. Für Dialogpost-Sendungen ist eine Nutzung nicht möglich.

Nicht zustellbare Sendungen werden vernichtet. Eine Rückführung der Sendung an den Absender ist ausgeschlossen. Sendungen, deren Empfänger einen Nachsendeauftrag gestellt haben (bspw. im Umzugsfall), werden an die angegebene neue Adresse nachgesendet.

Die Leistungen müssen über das Plugin [PremiumAdress] für jede Sendung einzeln beauftragt werden. Die Rückmeldungen erfolgen zeitversetzt und müssen aktiv in der API abgerufen werden.

PREMIUMADRESS verursacht keine fixen Kosten. Zu zahlen sind nur bereitgestellte Adressinformationen (je Datensatz), sofern sie kostenpflichtig sind. Die ggf. anfallenden Kosten fließen in die monatliche Abrechnung der E-POST Leistung ein. Auf der Rechnung werden alle erbrachten PREMIUMADRESS-Leistungen ausgewiesen, sowohl kostenfreie als auch kostenpflichtige. Eine gesonderte Rechnung für PREMIUMADRESS wird nicht erstellt.

Eine detaillierte Aufstellung der kostenpflichtigen und kostenfreien Leistungen ist auf der PREMIUMADRESS Produktseite, auf der Seite „Leistungen“, unter „Leistungen und Preise“ aufgeführt.

Sobald das Plugin [PremiumAdress] mit der jeweiligen Option (Basis oder Report) einer Sendung mitgegeben wird, ist die Leistung beauftragt und dementsprechend wird ein PREMIUMADRESS Label auf die Sendung aufgebracht.

Da alle Leistungen der API immer sendungsbasiert sind, kann man in einem Upload unterschiedlichste Sendungen mit unterschiedlichen Zusatzleistungen beauftragen. Diese Leistung kann nur für nationale Briefsendungen, ausgenommen Einschreiben, beauftragt werden (nicht für Dialogpost). Ein zusätzlicher Vertrag ist nicht notwendig.

Die Sendungsinformationen von PREMIUMADRESS werden durch [PremiumAdressFeedback] zeitversetzt sowohl im [LetterStatus] als auch als eigenständige Abfrage bereitgestellt. Der Aufbau und der Inhalt der PREMIUMADRESS Rückmeldung entsprechen den Beschreibungen im PREMIUMADRESS Handbuch (PREMIUMADRESS Download-Seite).

Die Rückmeldungen zu Ergebnissen von PREMIUMADRESS werden zeitversetzt bereitgestellt. Sie unterliegen den Bearbeitungszeiten von PREMIUMADRESS und sind dann sowohl im [LetterStatus] als auch als eigenständige Abfrage (siehe [/api/Letter/PremiumAdressFeedback]) verfügbar.

PREMIUMADRESS in der E-POSTBUSINESS API ist ein Ableger der allgemeinen Dienstleistung, die auch grundsätzlich mit wesentlich mehr Ausprägungen von der Deutschen Post angeboten wird. Dort gibt es die Möglichkeit die Funktionalität mit simulierten Daten zu testen.

In der API-Entwicklungsumgebung ist das leider nicht möglich, weil die Daten erst dann generiert werden bzw. abgerufen werden können, wenn der Brief den Status 4 erreicht und in die Zustellung geht. Das ist jedoch in der Entwicklungsumgebung der E-POSTBUSINESS API nicht möglich, weil diese bei Status 2 gesperrt wird.

PREMIUMADRESS kann nur bei nationalen Sendungen eingesetzt werden, weil die E-POSTBUSINESS API auf diesem Wege keinen Zugriff auf Zustellinformationen von Postunternehmen im Ausland hat.

Man kann als API-Nutzer auch ausschließlich den hybriden Briefversand der E-POST nutzen, ohne die Dialogpost zu implementieren.

Die E-POSTBUSINESS API stellt sowohl als Kernleistung den hybriden Briefversand der E-POST als auch alle anderen notwendigen Funktionen für den ordnungsgemäßen Betrieb in der Software bereit. Eine ausschließliche Implementierung der Dialogpost, ohne die Kernfunktionen der E-POSTBUSINESS API zu implementieren, ist nicht möglich.

Die Methoden der Dialogpost unterliegen, neben dem grundsätzlichen Entwicklungsmodus der E-POSTBUSINESS API, einem eigenen Entwicklungsmodus.

Der Wechsel vom Entwicklungsmodus zum Produktivmodus für die Dialogpost-Methoden wird durch den API-Support vorgenommen. Wenn die Dialogpost-Entwicklung der API abgeschlossen ist, wendet man sich zur Produktivschaltung an den Kontakt des API-Supports.

Man meldet die API-Nutzerdaten

• Unternehmen,
• vendorID und
• EKP

Nach Prüfung der Angaben und einer erfolgreichen Sichtung der Benutzerinteraktionen (gemäß der vertraglichen Regelung), schaltet der API-Support die Dialogpost in den Produktivmodus. Erst dann können die Kampagnen finalisiert und übermittelt werden. Der API-Support gibt über diese Produktivschaltung eine Rückmeldung.

Die Dialogpost ist ein additiver Teil der E-POSTBUSINESS API. Nur eine produktive Schnittstelle ermöglicht den Zugang zu den additiven Dialogpostmethoden und deren Produktivschaltung.

Jeder aktive E-POST Nutzer kann Dialogpost Sendungen versenden. Eine zusätzliche Freischaltung/Aktivierung ist nicht notwendig.

Wenn ein E-POST Nutzer sich in seiner Software aktiviert hat, wird keine weitere Aktivierung für die Nutzung der Dialogpost benötigt.

Neben dem ordnungsgemäßen Werbemittel werden die Zielanschriften in ausreichender Zahl, die Kundennummer (EKP) der E-POST Nutzers, die Auftraggeber-/Rechnungsanschrift, der Absender, das Zieldatum sowie die Kontaktdaten des Auftraggebers benötigt.

Damit entsprechende Konditionen optimal bereitgestellt werden können, benötigt ein Versand von Dialogpostsendungen entsprechenden Vorlauf (siehe hierzu das Schema [Campaign palDate]). Die dort angegebene Vorlaufzeit beschreibt das Datum der Postauflieferung, nicht das Zustelldatum.

Die Dialogpost Erweiterung bietet Vorab-Prüfungen für das Werbemittel mit den zugehörigen Anschriften [/api/Campaign/SampleRequest] und [/api/Campaign/SampleData] als auch eine Kostenprüfung [/api/Campaign/CostEstimate]. Diese Daten stehen teilweise nur begrenzte Zeit zur Verfügung und sind von den Kampagnen getrennt.

Unabhängig der Vorab-Prüfung oder im Rahmen einer Kampagne wird das bereitgestellt Werbemittel auf die Einhaltung der Formatvorgaben geprüft. Hierbei wird ein Auszug (siehe [/api/Campaign/SampleRequest] oder [/api/Campaign/{id}/ConfirmRequest]) aus den jeweils bereitgestellten Anschriften in das Werbemittel aufgebracht, so dass anschriftenabhängige Formatverletzungen oder andere Effekte im möglichen Druckbild des Werbemittels vom E-POST Nutzer validiert werden können.

Die Vorab-Kalkulation bietet eine einfache Möglichkeit, in Abhängigkeit der Sendungsmenge den Kostenrahmen zu evaluieren. Die Preisberechnung im Rahmen der Kampagne basiert auf den final bereitgestellten Auftragsdaten (bspw. Anschriften und deren Anzahl, Farbwahl als Produktionsvorgaben, etc.) und stellt die für den E-POST Nutzer zu erwartenden Kosten für eine Beauftragung gemäß den AGB Dialogpost dar.

Eine Kampagne besteht aus ihrer ID, dem freiwählbaren Namen aus dem Werbemittel, den zugehörigen Empfängeradressen, den Rechnungsempfänger- und Absenderdaten, der EKP des E-POST Nutzers sowie aus dem Auflieferungsdatum. Die Kampagne selbst wird durch eine eindeutige ID [campaignID] referenziert und ihr unterschiedlicher Status kann geprüft werden (siehe [CampaignStatus]).

Die finale Beauftragung beinhaltet aus den Kampagne-Daten die ID und den Namen, die Rechnungsempfängerdaten und das Absenderdatum, Kontaktdaten, die Produktionsdaten (bspw. Anzahl Seite, Farbewahl, Anzahl Schreiben, etc.), Geschäftsbedingungen, Preise und einen Zeitstempel.

Neben den Vorabprüfungen, welche explizit zur Evaluierung von Werbemitteln und Kosten zu verwenden sind, ist ein definierter Prozessablauf für die Beauftragung einer Kampagne einzuhalten.

Die eröffnete Kampagne kann bis zur Beauftragung noch jederzeit verworfen werden [/api/Campaign/{id}/Cancel]. Die Kampagne muss man mit ihren Daten öffnen [/api/Campaign/Open].

Danach muss man die Generierung der Werbemittel [/api/Campaign/{id}/ConfirmRequest] zur Validierung anstoßen. Im vorgegebenen Zeitfenster ist dann das generierte Werbemittel abzurufen [/api/Campaign/{id}/ConfirmData] und dem E-POST Nutzer zur Validierung zuzuführen.

Wenn alle grundlegenden Daten für eine Preiskalkulation und spätere Beauftragung vorliegen, wird die Kalkulation [/api/Campaign/{id}/FinalizeInfo] mit den finalen Auftragsdaten angestoßen und man erhält die Informationen [CampaignFinalizeInfo] zur finalen Beauftragung.

In einem Benutzerdialog lässt man über OptIn-Verfahren die Validität der generierten (Beispiel-) Werbemittel, die sichtbar präsentierten finalen Auftragsdaten, die Akzeptanz der Geschäftsbedingungen (URL Bestandteil der finalen Auftragsdaten und über bspw. externen Browser ansteuerbar) explizit als kostenpflichtige Leistung bestätigen und beauftragen.

Diese finale Beauftragung [/api/Campaign/{id}/Finalize] ist im angegebenen Zeitfenster mit Hilfe der bereitgestellten finalen Beauftragung [CampaignFinalizeInfo] durchzuführen.

Eine Kampagne kann nach der Eröffnung nicht mehr geändert werden. Solange Sie nicht beauftragt [/api/Campaign/{id}/Finalize] wurde, kann sie jedoch verworfen [/api/Campaign/{id}/Cancel] und somit neu erzeugt werden [/api/Campaign/Open].

Solang man nicht die Kampagne beauftragt oder abgebrochen hat, bzw. sie zeitbedingt abgebrochen wurde, kann man jederzeit die Werbemittel auch mit jeweils anderen Adresspositionen generieren [/api/Campaign/{id}/ConfirmRequest]. Dabei werden mögliche bisherige Dokumente überschrieben.

Solange man nicht die Kampagne beauftragt oder abgebrochen hat, bzw. sie zeitbedingt abgebrochen wurde, kann man jederzeit die Werbemittel abrufen [/api/Campaign/{id}/ConfirmData].

Dabei werden die Dokumente des letzten Generierungsaufrufes für Werbemittel bereitgestellt [/api/Campaign/{id}/ConfirmRequest].

Solang man nicht die Kampagne beauftragt oder abgebrochen habe, bzw. sie zeitbedingt abgebrochen wurde, kann man jederzeit die Beauftragungsdaten [CampaignFinalizeInfo] einer Kampagne abrufen.

Nur mit dem letzten Aufruf kann auch die Beauftragung [/api/Campaign/{id}/Finalize] durchgeführt werden.

Der Status einer Kampagne kann dediziert [/api/Campaign/{id}/Status] oder über einen Zeitraum [/api/Campaign/Date] abgerufen werden, wobei die abrufbaren Daten unterschiedlich lange verfügbar sind. Man erhält somit einen genauen Überblick über den aktuellen Verarbeitungsstatus.

Solange man die Kampagne nicht beauftragt oder abgebrochen hat, bzw. sie zeitbedingt abgebrochen wurde, kann man sie abbrechen.

Mit dem zurückgelieferten Status der Kampagne sowie der oder den Fehlermeldungen (Error Objekten) führt man den Benutzer in der Software, damit man zwischen der Problemlösung Software und Produktionsproblem unterscheiden kann.

Im Falle, dass man zur Schnittstelle oder der E-POST Nutzer zum Druck bzw. der Zustellung Unterstützung durch den Support benötigt, ist hierzu die Kundennummer (EKP) des E-POST Nutzers, der Ansprechpartner, die konkrete [campaignID] und der Status der Kampagne aus dem Status (siehe [/api/Campaign/{id}/Status] oder [/api/Campaign/Date]) bereitzuhalten.

Mit Hilfe des [Vendor] Controllers kann man sowohl die Anzahl der erfolgreichen Dialogpost Sendungen bezogen auf einen Zeitraum als auch mögliche fehlerhafte Sendungen ermitteln.

Der Status der produzierten Dialogpost Schreiben wird gruppiert in reduzierter Form als [CampaignDetails] für einen begrenzten Zeitraum bereitgestellt. Die fehlerhaften Kampagnen sind über ihren Status und der entsprechenden [errorList] ersichtlich.

Die Eingrenzung des Zeitraumes bezieht sich auf das Erstelldatum einer Kampagne [CampaignStatus: 1 – initalized].

Man kann zu jeder Kampagne Informationen [vendorSystemInformation] hinterlegen, in denen man z.B. die Software-Version ablegt. Diese abgelegte Information erhält man im [CampaignStatus] zurück.

+49 7161 65159-90
Mo-Fr 09:00 - 12:00 Uhr und 13:00-17:00 Uhr
eMail: EPostApiSupport@docuguide.com

Der zurückgelieferte Status des Dokumentes und ggf. die Fehlermeldungen (Error Objekte) geben klare Hinweise zum Fehlerbild, so dass zwischen Softwareproblemen und Druck-/Zustellproblemen unterschieden werden kann.

Wendet man sich als Softwarehersteller/Eigenversender aufgrund auftretender Fehler beim Briefversand an den API-Support, sind hierzu die eigene EKP, der Name des Kontaktes nebst vendorID, die konkrete letterID und der Status des Dokumentes mit den Zeitstempeln aus dem Status (siehe [LetterStatus]) bereitzuhalten.

Bitte wenden Sie sich direkt an den Shop der Deutschen Post AG über den Kontakt-Link in der Auftragsbestätigung. Eine vorherige Registrierung der Schnittstelle ist nur für Endkunden der Partner erforderlich. Bei Partnern und Eigenversendern wird die Registrierung (und damit die Vereinbarung zur Auftragsverarbeitung) im Rahmen des Abschlusses des API-Nutzervertrages durchgeführt.

Kundenservice der E-POST

Tel.: +49 228 4333 1100 (Mo-Fr 08:00-20:00 Uhr) außer an bundeseinheitlichen Feiertagen
eMail: e-post@deutschepost.de

Bitte wenden Sie sich bei Fragen zur Abrechnung an die auf Ihrer Rechnung angegebene eMail-Adresse.
In der Regel ist das DPEPS.Abrechnung@deutschepost.de. Nennen Sie uns in Ihrer eMail Ihre Kundennummer (EKP) und die entsprechende Nummer der betroffenen Rechnung.

Bitte wenden Sie sich bei Laufzeit- und Qualitätsproblemen Ihrer Sendungen an unseren Kundenservice unter e-post@deutschepost.de . Geben Sie hierbei möglichst die Frankier-IDs bzw. die letterIDs der betroffenen Sendungen an, die für eine nähere Recherche, insbesondere in Hinblick auf die Laufzeit, benötigt werden.

Alternativ können Sie sich als API-Partner oder Eigenversender auch mit unserem Service Delivery Team (sdm.dpeps@deutschepost.de) in Verbindung setzen, wenn es um die Nachverfolgung von Sendungen geht.

Mit dem Abruf [/api/Login/HealthCheck] lassen neben dem Verfügbarkeitsstatus der API auch die Bereitstellung von Wartungsfenstern, sowie mögliche Störungen abfragen. Ein Login ist hierfür nicht notwendig.

Alternativ kann man diesen Status auch über den folgenden Link abfragen:

https://api.epost.docuguide.com/health

Hinweis: Sendungen mit Fehler sind finale Zustände und werden nie produziert. Diese müssen per Upload nochmals hochgeladen werden, unabhängig wer den Fehler verursacht hat.