FAQ

Was ist die Kundenummer der Deutschen Post (EKP) und wo finde ich diese?

Als Kunde der Deutschen Post erhalte ich eine Kundenummer (EKP). Diese erhalte ich im Rahmen meines Vertragsschlusses mit der Deutschen Post (bspw. Registrierungen) und finde sie anschließend auf meinen Rechnungen (unter Kundennummer bzw. EKP). Sollte ich die EKP, die Kundennummer der Deutschen Post, weder in meinem Vertrag noch in den Rechnungen finden, benötige ich meine Firmendaten (bspw. Firma, Anschrift, Ansprechpartner), die ich im Rahmen der Registrierung angegeben habe und wende ich an den Kundenservice der Deutschen Post. Dieser kann mir, nach Validierung meiner Daten, diese Kundennummer nennen.

Was ist ein API Nutzer und was ist ein E-POST Nutzer?

Als API Nutzer implementiere ich die API Schnittstelle und durch meinen API Nutzer Vertrag erhalte ich eine Kundenummer der Deutsche Post (EKP), sowie im Rahmen der Anbindung zur E-POSTBUSINESS API meine vendorID durch den API Support.
Als E-POST Nutzer bin ich der Versender und versende meine Dokumente mit Hilfe der in meiner Software implementierten API. Damit ich als API Nutzer auch Schreiben versenden kann, benötige ich somit zusätzlich einen E-POST Nutzer Vertrag. Ich erhalte diesen mit der Registrierung für den E-POST Nutzer Vertrag zur E-POSTBUSINESS API (E-POST Nutzervertrag zur E-POSTBUSINESS API) Der E-POST Nutzer repräsentiert das gesamte Unternehmen. Hierzu schließe ich (als neuer E-POST Nutzer) einen E-POST Nutzervertrag ab und erhalte hier auch meine Kundenummer der Deutsche Post (EKP). In der Regel sind die E-POST Nutzer die (End)Kunden des API Nutzers. Im Rahmen des Vertragsschlusses zum E-POST Nutzervertrag wurde ein Kontaktperson nebst (i.d.R.) Mobilnummer benannt, welche dann zur Aktivierung der Schnittstelle herangezogen wird.
Wenn ich über meine eigene implementierte Software versende, bin ich sowohl ein API Nutzer als auch ein E-POST Nutzer und habe beide Verträge abgeschlossen, wobei dann die Kundenummer der Deutsche Post (EKP) identisch ist.

Was benötige ich als API-Nutzer zur Aktivierung der API?

Als API-Nutzer benötige ich meine Kundenummer der Deutsche Post (EKP), meine vendorID und Zugriff auf mein Mobiltelefon, das ich beim Registrierungsprozess für Software Partner angegeben habe, zwecks Mobil-TAN Verfahren via SMS.
Zur Aktivierung meines Zugangs nutze ich mit meinen Daten ebenso die Methoden der API zur Anfrage der Mobil-TAN, wie auch zum Setzen des Kennworts, analog eines E-POST Nutzers (Endkunde).
Zu Beginn meiner Entwicklung bin ich im Entwicklungsmodus der API, so dass ich keine Dokumente versehentlich in das Druckzentrum einliefern kann, jedoch alle Funktionen der API implementieren und nutzen kann. Zum Wechsel in den Produktivmodus, siehe Wie wechsle ich als API-Nutzer vom Entwicklungsmodus in den Produktivmodus?.

Was sind die Schritte für einen Versand über die API?

Als API Nutzer habe in der Regle ich in meiner Software einen administrativen Bereich eingerichtet, in dem initiale Maßnahmen (bspw. Aktivierung von Schnittstellen) oder Zugangsdaten (Login) abgebildet werden. Die Initialmaßnahme für den E-POST Nutzer setzt sich aus der Anfrage eines SMS Codes und der anschließenden Vergabe des Kennworts zusammen (siehe auch Loginmethoden smsRequest und setPassword). Der Benutzer oder Administrator der Software muss dies für den konkreten E-POST Nutzer einmalig durchlaufen.
Als E-POST Nutzer muss ich für den Versand initial die API Schnittstelle meiner Kundenummer der Deutsche Post (EKP) aktivieren (siehe Wie aktiviere ich meinen E-POST Nutzer für die API Schnittstelle?).
Je nach Implementierung der API durch den API Nutzer erfolgt dann der Login mit den Zugangsdaten des jeweiligen E-POST Nutzers (in der Regel Kunden des API Nutzers) ggf. automatisiert. Die Versandfunktionen und Statusabfragen der API stehen dann zur Verfügung.

Welche Zugangsdaten benötige ich als API Nutzer zur Implementierung der API?

Ich benötige als API-Nutzer meine Kundenummer der Deutsche Post (EKP), die ich im Rahmen meines API Nutzer Vertrags erhalten habe und meine vendorID,die ich vom API Support erhalte.

Woher bekomme ich meine Kundenummer der Deutsche Post (EKP) und meine vendorID?

Mein vertrieblicher Kontakt hat mich an der E-POSTBUSINESS API registriert. Der E-POSTBUSINESS API Support nimmt dann den Kontakt zur mir auf, so dass ich über meinen Vertrag meine Kundennummer der Deutschen Post (EKP) erhalte und meine vendorID durch den API Support.

Wie erhalte ich Zugang für den API Versand?

Wenn ich über den API Support freigeschaltet wurde, benötige ich einen gültigen E-POST Nutzer Vertrag, die dort hinterlegte Kundenummer der Deutschen Post (EKP), sowie die Aktivierung meines Logins der E-POSTBUSINESS API über die API Schnittstelle.

Was benötigt mein E-POST Nutzer (mein Endkunde) zur Aktivierung der API?

Als E-POST Nutzer benötige ich meine eigene Kundenummer der Deutsche Post (EKP), die vendorID meines Software Partners (i.d.R. bereits in der Applikation hinterlegt) und Zugriff auf mein Mobiltelefon, das ich als E-POST Nutzer bei der E-POST Registrierung zur E-POSTBUSINESS API angegeben habe, zwecks Mobil-TAN Verfahren via SMS.

Was mach ich, wenn ich während der Aktivierung der API keine SMS erhalte?

Damit ich eine SMS erhalten kann, benötige ich einen Vertrag mit der Deutschen Post, als API-Nutzer einen API-Nutzer Vertrag, als Versender einen E-POST Nutzer Vertrag. Im Rahmen dieser Vertragsschlüsse habe ich eine Mobilfunknummer hinterlegt.
Habe ich die die SMS Anfrage abgesetzt und erhalte nicht innerhalb weniger Minuten eine SMS, konnte die SMS Anfrage nicht korrekt abgesetzt werden. Gegebenenfalls sind die damalig erfassten Daten nicht ordnungsgemäß oder veraltet. Das zur Korrektur notwendige Verfahren und der Kontakt für den Kundenservice der Deutschen Post liegt meinem Software Hersteller zusammen mit den von mir bereitzuhaltenden Daten vor.
Ich wende mich mit meinen bereitgehaltenen Daten an den Kundenservice der Deutschen Post und dort wird innerhalb kurzer Zeit (bitte die Servicezeiten beachten) die Korrektur durchgeführt.
Hiernach kann ich die SMS Anfrage erneut durchführen.

Wie wechsle ich als API-Nutzer vom Entwicklungsmodus in den Produktivmodus?

Der Wechsel vom Entwicklungsmodus zum Produktivmodus wird durch den API Support vorgenommen. Wenn ich die Entwicklung der API abgeschlossen habe, wende ich mich zur Produktivschaltung über den mir bekannten Kontakt des API Supports an diesen. Ich teile ihm meine API-Nutzerdaten (Unternehmen, vendorID und EKP) mit und dieser schaltet mich dann, nach Prüfung der Angaben, in den Produktivmodus. Erst dann können die Dokumente in das Druckzentrum übermittelt werden. Der API Support gibt mir über diese Produktivschaltung eine Rückmeldung.

Wie aktiviere ich meinen E-POST Nutzer (meinen Endkunden) für die API Schnittstelle?

In der Regel ist der E-POST Nutzer mein Endkunde und dieser Endkunde muss die Schnittstelle aktivieren. Der E-POST Nutzer benötigt hierzu zuerst einen SMS Code, mit dessen Hilfe er so dann sein Kennwort setzen kann und somit die Schnittstelle für sich aktiviert. Durch die Angabe der Kundenummer der Deutschen Post (EKP) dieses aktiven E-POST Nutzers wird an die in diesem E-POST Account hinterlegte Rufnummer zeitnah ein SMS Zugangscode gesendet, der mehrere Minuten gültig ist (siehe Loginmethoden smsRequest).
Zusammen mit diesem Code, der Kundenummer (EKP) des E-POST Nutzers und meiner vendorID vergibt der E-POST Nutzer ein neues Kennwort (siehe Loginmethoden setPassword) und er erhält einen Sicherheitsschlüssel (secret). Diesen Sicherheitsschlüssel benötigt er später zusammen mit seinem Kennwort für den Login (siehe: Wie melde ich mich an die API an).

Wie melde ich mich an die API an?

Für meine Entwicklung nutze ich als API Nutzer die vendorID (die ich über den API Support erhalten habe), meine Kundenummer der Deutschen Post (EKP), mein Kennwort und meinen Sicherheitsschlüssel (secret) und melde ich mit über den Login der API an und erhalte ein Laufzeittoken, dass ich in den weiteren Anfragen nutze.
Für meinen Endkunden (E-POST Nutzer) hinterlege ich in meiner Software meine vendorID, so dass mein Endkunde sich mit seiner Kundenummer der Deutschen Post (EKP), seinem Kennwort und seinem Sicherheitsschlüssel (secret) anmelden kann und somit die Software für den Versand nutzen kann.

Kann ich Laufzeittoken einschränken?

Ich kann die Laufzeittoken zum einen zeitlich einschränken oder zum anderen auch für verteilte Anwendungen über eine mit dem API Support abgestimmten vendorSubID individualisierte Laufzeittoken zentral erzeugen und dann selber zur Nutzung in meinen Anwendungen zu verteilen.

Wie versende ich über die API?

Wenn ich ein gültiges Laufzeittoken habe, stelle ich die entsprechenden base64 Daten (PDF/A Dateien) sowie die Metadaten zusammen und führe die Einlieferungsmethode der API aus. Die genutzten Dateinamen der PDF/A Dateien müssen im Aufruf eindeutig sein.
Ich kann mehrere Einlieferungen in einem Aufruf ausführen und mehre Aufrufe über eine batchID gruppieren. Die erfolgreiche Einlieferung quittiert dies mit einer eindeutigen letterID zu dem eindeutigen Dateinamen. Die letterID ist über die Zeit eindeutig.
Die Einlieferungen gehen direkt in den Verarbeitungsmodus über.

Was muss ich bei den PDF Dokumenten beachten?

Die der API übergebenen PDF Dokumente müssen dem DIN A4 Hoch-Format entsprechen. Abweichungen vom DIN A4 Hoch-Format können nicht verarbeitet werden. Insbesondere die PDF Dokumente, die nicht dem PDF/A-1b (siehe Abweichungen für Dialogpost) Format entsprechen, werden systemisch aufbereitet und sind daher in vorgehenden Tests (Testmodus der E-POSTBUSINESS API) zu prüfen, da in der Aufbereitung beispielweise fehlende Fonts durch Standards ersetzt werden oder Transparenzen in Bildern nicht das gewünschte Ergebnis spiegeln. Diese Umständen können eine einwandfreie Verarbeitung einschränken oder zur Ablehnung in der Verarbeitung führen. Zudem kann durch sich durch die Aufbereitung die maximale PDF-Dateigröße erhöhen. Die maximale PDF-Dateigröße ist auf 20 MB limitiert. 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. Mögliche OCR Verfahren, die auf Einlieferseite bei Dokumentenscans erfolgt sind, sind zu hinterfragen und auf mögliche Font Verletzungen (bspw. fehlende Einbettung) zu prüfen. Die maximale Seitenanzahl sind 94 Seiten für Simplex und 188 Seiten für Duplex, so dass maximal 94 Blätter nicht überschritten werden.

Werden die Metadaten des Dokumentes benötigt?

Es gibt eine Mindestmenge an Metadaten eines jeden Dokumentes, die ich für seine ordnungsgemäße Verarbeitung bereitstellen muss. Sind diese Metadaten fehlerhaft oder weichen diese von der im Dokument digital lesbaren Empfängeranschrift ab, führt dies zu einer Ablehnung in der Verarbeitung. Diesen Umstand muss ich dann in meiner Software und meinen Prozessen berücksichtigen. Für eine vereinfachte Verarbeitung wird ein leerer Ländercode als Deutschland interpretiert. Für Auslandssendungen muss ich jedoch zwingend, neben der korrekten Anschrift, zusätzlich den korrekten Ländercode befüllen.

Welche Anschriften-Metadaten benötige ich für den Standard-Briefversand?

Wenn ich ein Dokument versende, muss ich immer die gesamten Anschriftendaten mitgeben, die eine Zustellung erlauben. Die Anschrift selber setzt sich immer aus 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 beigesteuert werden. Diese Kombination wird in den Metadaten gespiegelt. Habe ich eine Empfängerbezeichnung, die sich nur über eine Zeile erstreckt, dann ist dies adressLine1 und für bspw. 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 adressLine5.
Abweichungen in den Metadaten zu der im Dokument aufgebrachten digital auslesbaren Empfängeranschrift führen zur Ablehnung in der Verarbeitung.
Diese Metadaten werden auch für das Deckblatt herangezogen, wobei ich zusätzlich noch die Metadaten des Versenders (bspw. senderAdressLineComplete) befüllen muss.

Wie kann ich ohne Anschriften-Metadaten mit der API national versenden?

Wenn ich keine Anschriften-Metadaten bereitstellen kann, bietet mir der Automover eine Möglichkeit, dennoch diese nationalen Schreiben zu versenden, siehe hierzu „Wie kann ich automatisch nationale Anschriften repositionieren?“.
Zur Nutzung des Automover ist ggf. ein Upgrade erforderlich, weitere Informationen erhalte ich über meinen vertrieblichen Ansprechpartner.

Wie kann ich das Anschriftenfeld überschreiben lassen?

Mit Hilfe der Automover Funktion kann ich das vorhandene Anschriftenfeld (Sender- und Empfängeradresse) durch die bereitgestellten Metadaten überblenden. Diese erweiterte Funktion wird als PlugIn Automover bereitgestellt. Hierzu muss ich zum einen den Automover aktiveren (useAutomover = true) und zum anderen im JSON die Metadaten (senderAdressLine1, senderStreet, senderZipCode, senderCity, addressLine1-5, zipCode, city) bereitstellen. Ich muss beachten, dass auf der ersten Seite des PDF der gesamte Sperrbereich aus der Sperrflächenschablone V3 geweißt und dann mit den mitgegebenen Daten überschrieben wird. Eine Kombination mit der Deckblatt-Funktion (coverLetter = true) erzeugt ein Deckblatt, führt diese Funktion jedoch nicht aus und wird als Info im Error Objekt dokumentiert. Ich kann mit der Testfunktion der API (siehe „Wie weiß ich, ob mein Brief versandt werden kann?“) das Ergebnis des Automover prüfen.
Zur Nutzung des Automover ist ggf. ein Upgrade erforderlich, weitere Informationen erhalte ich über meinen vertrieblichen Ansprechpartner.

Wie kann ich automatisch nationale Anschriften repositionieren?

Mit Hilfe der Automover Funktion kann ich das vorhandene nationale Anschriftenfelder (Sender- und Empfängeradresse) automatisch repositionieren. Diese erweiterte Funktion wird als PlugIn Automover bereitgestellt. Hierzu muss ich zum einen den Automover aktiveren (useAutomover = true) und zum anderen im JSON die Metadaten addressLine1, zipCode und city mit definierten Werten (siehe Schema 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 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.
Ich kann mit der Testfunktion der API (siehe „Wie weiß ich, ob mein Brief versandt werden kann?“) das Ergebnis des 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.
Zur Nutzung des Automover ist ggf. ein Upgrade erforderlich, weitere Informationen erhalte ich über meinen vertrieblichen Ansprechpartner.

Was muss ich bei der Absenderzeile beachten?

Sowohl für nationale als auch internationale Sendungen muss ich eine einzeilige Absenderangabe mit Adresse im Inland (Deutschland) an der vorgeschriebenen Position (siehe Sperrflächenschablone V3) aufbringen. Details sind den AGB E-POST, Ziffer 6.8, zu entnehmen. Die Absenderzeile muss den Absender vollständig beinhalten und darf nicht aus dem Fenster herauslaufen. Dies kann ich mittels der API Testfunktion und dem Einblenden der Schablone überprüfen.

Welche Schriftarten nutzt die API?

Die API verwendet für die automatisiert auf der ersten Seite oder Deckblatt aufgebrachten Anschriftendaten die Schriftart Arial in Schwarz und die Fontgröße 6 für die Senderadresse sowie die Fontgröße 9 für die Empfängeradresse. Für PDF Dokumente, die nicht als PDF/A bereitgestellt werden, werden überarbeitetet und nach Möglichkeit werden fehlende Fonts durch Standards ersetzt. Für die von der API automatisiert genutzten Schriftarten sind die Lizenzbestimmungen erfüllt. Grundsätzlich bin jedoch ich als Versender für die verwendeten Schriftarten/Fonts meines Dokumentes verantwortlich.

Was muss ich für PREMIUMADRESS beachten?

Die Zusatzleistung PREMIUMADRESS steht in den Varianten Basis und Report zur Verfügung. Die für diese Zusatzleistungen ggf. erhobenen Kosten sind auf der PREMIUMADRESS Produktseite, dort auf der Seite „Leistungen“ und dort unter „Leistungen und Preise“ aufgeführt. Diese Leistung kann nur für nationale Sendungen, ausgenommen Einschreiben, beauftragt werden.
Es ist zu beachten, dass nicht zustellbare Sendungen vernichtet werden. Eine Rückführung der Sendung an den Absender ist ausgeschlossen.
Die Leistung muss über das PremiumAdress PlugIn für jede Sendung einzeln beauftragt werden. Die Rückmeldungen erfolgen zeitversetzt und müssen aktiv an der API abgerufen werden.

Wie wird PREMIUMADRESS abgerechnet?

Die ggf. anfallenden Kosten fließen in die monatliche Abrechnung der E-POST Leistung ein. Eine gesonderte Rechnung wird nicht erstellt. Eine Aufstellung der kostenpflichtigen und kostenfreien Leistungen werden auf der PREMIUMADRESS Produktseite, dort auf der Seite „Leistungen“ und dort unter „Leistungen und Preise“ aufgeführt.

Wie kann ich PREMIUMADRESS beauftragen?

Sobald ich das PlugIn für PremiumAdress mit der jeweiligen Option (Basis oder Report) der jeweiligen Sendung mitgebe, wird die Leistung beauftragt und dementsprechend PREMIUMADRESS Label auf die Sendung aufgebracht. Da alle Leistungen der API immer sendungsbasiert sind, kann ich in einem Upload unterschiedlichste Sendungen mit unterschiedlichen Zusatzleistungen beauftragen. Diese Leistung kann nur für nationale Sendungen, ausgenommen Einschreiben, beauftragt werden. Ein zusätzlicher Vertrag ist nicht notwendig.

Wie erhalte ich die Rückmeldungen von PREMIUMADRESS?

Die Ergebnisse von PREMIUMADRESS werden durch das PlugIn PremiumAdressFeedback zeitversetzt im LetterStatus bereitgestellt. Der Aufbau und der Inhalt der PREMIUMADRESS Rückmeldung entsprechen den Beschreibungen im PREMIUMADRESS Handbuch (ab Seite 54 detaillierte Feldbeschreibungen)

Wann erhalte ich die Rückmeldungen von PREMIUMADRESS?

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

Wird eine Postleitzahl für eine Auslandssendung benötigt?

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 (3) Leerzeichen (Blanks) zu befüllen. Die Entscheidung zur korrekten Befüllung der Postleitzahl liegt beim Versender. Für Inlandssendungen ist die korrekte Postleitzahl anzugeben, die Befüllung mit Leerzeichen nicht zulässig.

Welche Anschriften-Metadaten benötige ich für ein Einschreiben Versand?

Das Einschreiben (registeredLetter) ist eine Briefzusatzleistung auf das eigentlich Dokument. Neben der korrekten relevanten Empfängeranschrift ist auch eine gut lesbare Absenderzeile für eine erfolgreiche Verarbeitung wichtig. Im Falle des Rückscheins (bspw. registeredLetter = "Einschreiben Rückschein") wird in den weiteren Systemprozessen der Deutschen Post aus der Absenderzeile automatisch der Rückschein mit den Belegdaten gebildet und dem auf dem Schreiben aufgebrachten Absender zugestellt. Von der Absenderzeile abweichende Empfängeranschriften des Rückscheins werden nicht unterstützt. Kann die Absenderzeile techn. nicht verwendet werden (bspw. nicht lesbar, nicht vorhanden, nicht sichtbar, etc.), kann kein Rückschein automatisch erzeugt werden. In diesem Fall kann der Empfängerbeleg in der Sendungsverfolgung für Geschäftskunden der Deutschen Post recherchiert werden (siehe: Was ist bei der Track And Trace Statusmeldung für Einschreiben zu beachten?).
Die bisherigen gesonderten Metadaten für den Rückschein (registeredLetterAdressLine1 bis registeredLetterCity) sind überholt und sind nicht mehr zu verwenden.

Was passiert bei einem Abbruch in der Einlieferung?

Die API quittiert die Einlieferungen mit einer eindeutigen letterID. Wenn ich eine Fehlermeldung der API erhalte (siehe Response Codes), wird die gesamte Einlieferung verworfen. Für den Fall, dass ich die Quittierung nicht mehr erhalte, habe ich zusätzlich die Möglichkeit, im ersten Feld der individuellen Dokumentenmerkmalen (custom1) eine eigene ID zu hinterlegen, die ich auch über eine eigene Abfrage abrufen kann.

Was passiert mit den Einlieferungen?

Die eingelieferten Daten werden validiert, aufbereitet und im fehlerfreien Falle in den Produktions- und Versandprozess überführt. Fehlerhafte Schreiben in einer Masseneinlieferung werden aussortiert, sodass der Rest der Einlieferung weiter verarbeitet wird.

Welchen Status haben meine eingelieferten Daten?

Den Status jeder einzelnen Einlieferung kann über die letterID für 400 Tage abgerufen werden.
Den Status kann ich gezielt auf eine letterID, mengenbasiert über eine batchID, einen Zeitraum oder dedizierte letterID’s abfragen. Mengenabfragen können auf die fehlerhafte Einlieferungen eingeschränkt werden. Die einzelnen Status ID’s 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 in docuguide, 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 entweder den Sammelkorb oder einen Terminversand. Dies kann ich durch Abfrage des LetterStatus und der Auswertung des Feedbacks aus dem Sammelkorb PlugIn (UploadManagementFeedback) überprüfen.

Wie kann ich das UploadManagement (Sammelkorb/Terminversand) nutzen?

Sobald ich das PlugIn zum UploadManagement mit den jeweiligen Optionen anspreche, kann ich die entsprechenden Funktionen zum Sammelkorb oder Terminversand nutzen. Eine Aktivierung oder ein Upgrade ist nicht notwendig.

Wie kann ich bis zu 50 Sendungen sammeln (Mindestmenge)?

Damit ich eine Mindestmenge von 50 Sendungen (ohne Einschreiben, Ausland oder Sendungen mit testFlag = true) bis zur festgelegten Einlieferzeit von 14:00 sicherstellen kann, muss ich im Sammelkorb PlugIn (UploadManagement) die Option useMinimumQuantity = true setzen. Die Zählung erfolgt ausschließlich auf die im Status 2 befindlichen Sendungen (Ausnahme s.o.). Wird die Mindestmenge überschritten, werden die wartenden und alle weiteren Sammelkorb-Sendungen bis 14:00 ins Druckzentrum übertragen. Sendungen die den Status 2 nach 14:00 erreichen, werden auf den Folgetag verschoben und gehen dort in die Zählung ein.
Wird der Stichtag erreicht, wird die Sendung unabhängig von der Menge vor 14:00 in das Druckzentrum übertragen, ansonsten zusammen mit der Mindestmenge.
Wichtiger Hinweis: Einschreiben und Auslandssendungen können zwar gesammelt werden, werden aber in der Zählung nicht berücksichtigt. Hier wird nur die angegebene Terminoption berücksichtigt. Sendungen mit testFlag = true werden weder in der Zählung berücksichtig, noch können sie zum Testen des Sammelkorbs genutzt werden.
Wichtiger Hinweis: Der Zählungszeitpunkt 14:00 berücksichtigt ausschließlich die zu diesem Zeitpunkt erfolgreich verarbeiteten Schreiben (Status 2). Dies muss ich in der zeitlichen Kalkulation meines Versandes berücksichtigen, so dass dieser entsprechend vorher stattfinden muss.

Wie kann ich ein Schreiben zu einem Stichtag versenden (Terminversand)?

Damit ich ein Schreiben definitiv an einem Stichtag versenden kann (unabhängig von der Mindestmenge), muss ich im Sammelkorb PlugIn (UploadManagement) die Option useMinimumQuantity = false setzen und ein 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.

Welche Optionen habe ich beim Stichtag (Terminversand)?

Ich kann beim Stichtag entweder die Anzahl der Tage (dueDays) angeben, wobei dies immer die Standardeinstellung mit einem Tag ist.
Alternativ kann ich ein festes Datum (dueDay) angeben, wobei der Zeitanteil ignoriert wird.
Eine andere Alternative ist der Wochentag (dueDayofWeek, mögliche Werte: Mo oder Di oder …So), wobei hier dann bis 14:00 der aktuelle Wochentag betrachtet wird und nach 14:00 der kommende Wochentag der nächsten Woche.
Wichtiger Hinweis: Der Zählungszeitpunkt 14:00 berücksichtigt ausschließlich die zu diesem Zeitpunkt erfolgreich verarbeiteten Schreiben (Status 2). Dies muss ich in der zeitlichen Kalkulation meines Versandes berücksichtigen, so dass dieser entsprechend vorher stattfinden muss.
Der Zeitpunkt kann grundsätzlich maximal 31 Tage in der Zukunft liegen.

Kann ich den Status einer wartenden Sendung verändern??

Für den dringenden Fall der Anpassung, kann ich ausschließlich das Verhalten der Sendungen im Sammelkorb und Terminversand beeinflussen.
Hierbei kann ich wartende Sendungen komplett stoppen, sie werden dann in den Fehlerfall überführt (Status 99) oder vorziehen, so dass sie Teil des nächsten Uploads zum Druckzentrum werden. Sollte jedoch bereits die Übertragung in das Druckzentrum vollzogen werden, ist dies nicht mehr möglich. Dies gilt auch für Sendungen, die bereits ins Druckzentrum übertagen wurden.
Veränderungen in den wartenden Sendungen beeinflussen natürlich die Mindestmenge, so dass diese sich somit ggf. verschieben kann.

Wie kann ich eine wartende Sendung aufhalten?

Nur betreffend der Sendungen im Sammelkorb und Terminversand kann ich durch die Angabe der betroffenen LetterID’s aufhalten (siehe /api/Letter/CancelQueued).
Die Sendung wird dann mit dem Status 99 versehen und kann grundsätzlich nicht mehr übertragen werden. Die bereits in Übertragung befindlichen Sendungen kann ich nicht verändern, hier erhalte ich eine Fehlermeldung.

Wie kann ich eine wartende Sendung vorziehen?

Nur betreffend der Sendungen im Sammelkorb und Terminversand kann ich durch die Angabe der betroffenen LetterID’s vorziehen und für die nächst mögliche Übertragung freigeben (siehe /api/Letter/ReleaseQueued).
Die bereits in Übertragung befindlichen Sendungen kann ich nicht verändern, hier erhalte ich eine Fehlermeldung.

Kann ich den Status einer wartenden Sendung verändern?

Sobald die Mindestmenge im Sammelkorb oder der Stichtag erreicht ist, geht die Sendung im entsprechenden Zeitfenster in das Druckzentrum.
Eine nachträgliche Veränderung ist derzeit nicht vorgesehen.

Was ist bei der Track And Trace Statusmeldung für Einschreiben zu beachten?

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. Tiefere Erklärungen zur Bedeutung der Statusinformationen werden auch unter https://www.deutschepost.de/de/service1/themenseiten/sendungsverfolgung/sendungsstatus.html bereitgestellt.
Über die Statusabfrage für Einschreiben (get /api/Letter/Registered) erhalte ich über einen definierten Zeitraum den Status der Einschreiben, wobei ich 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 dazu 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.
Wichtiger Hinweis: Da der Sendungsstatus aus dem Elektronischen Auftragsmanagement der Deutschen Post bereitgestellt wird, können Fragen zu dem konkreten Einschreiben unter https://www.deutschepost.de/sendung/ bzw. https://www.deutschepost.de/hilfe-zur-sendungsverfolgung beantwortet werden.
Zusätzlich hat der Geschäftskunde auch die Möglichkeit, eigenständig das Einschreiben unter https://www.deutschepost.de/sendung/login.html zu recherchieren.

Was bedeuten die unterschiedlichen Zeitstempel (createdDate, processedDate, printUploadDate und printFeedbackDate)?

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 augenblicklich zum Zeitpunkt der Sendungsannahme vergeben.
Der Zeitpunkt der Verarbeitung (processedDate) zeigt, wann das jeweilige Dokument den Systemprüfungen unterzogen wurde und ggf. Fehler produziert hat. Dieser Zeitstempel wird nach der Verarbeitung vergeben.
Der Übergang in den Produktionsprozess /-systeme wird über den Einlieferzeitpunkt 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 erst nach i.d.R. 1-2 Tagen aus dem Druckzentrum zurückgemeldet. Zur Validierung von Produktionsmengen auf der Rechnung sollte dieser Zeitstempel genutzt werden.

Wie gehe ich mit Fehlermeldungen um?

Mit dem zurückgelieferten Status des Dokumentes zusammen mit der oder den Fehlermeldungen (Error Objekten) führe ich den Benutzer in meiner Software, damit dieser klar zwischen der Problemlösung Software und Druck/Zustellproblem unterscheiden kann. Im Falle, dass ich zur Schnittstelle oder der Benutzer zur Druck/Zustellung eines Supports bedienen muss, ist hierzu die Kundennummer der Deutschen Post (EKP) des E-POST Nutzers, mein Name, die konkrete letterID und der Status des Dokumentes mit den Zeitstempeln aus dem Status (siehe LetterStatus) bereitzustellen.

Wie weiß ich, ob mein Brief versandt werden kann?

Über ein Testflag kann ich eine Verarbeitung (Validierung, Aufbereitung, etc.) ohne eine Überführung in das Druckzentrum auslösen. Der jeweilige Status mit den Fehlerobjekten gibt mir Auskunft über die Verarbeitungsmöglichkeit oder Ablehnungen. Zusätzlich kann ich zur Qualitätskontrolle für 48h via letterID das erzeugte PDF über die API Funktion get /api/Letter/TestResult abfragen. Alternativ kann ich mir an eine individuelle E-Mail Adresse das aufbereitete Dokument zusenden lassen. Für die Einhaltung der jeweiligen Datenschutzrichtlinien bspw. DSGVO der Sendungen ist immer der Versender verantwortlich. Darüber hinaus kann ich auch die für die Dokumente geltenden Sperrflächen in diesen Qualitätstest einarbeiten lassen.
Die Testverarbeitung ist für eine administrative Vorabprüfung vorgesehen, eine Einbindung in den Produktivversand wird nicht unterstützt.

Kann ich den Einlieferungen individuelle Merkmale mitgeben?

Mir stehen bis zu fünf individuelle Felder (custom1-5) zur Verfügung, die ich in der Einlieferung belegen kann und in der Statusabfrage zurück geliefert werden.

Kann ich ein Deckblatt erzeugen?

Ich kann ein Standard Deckblatt erzeugen, dass den Absender und Empfänger aus den Metadaten der Einlieferung enthält. Darüber hinaus kann ich alternativ ein eigenes Deckblatt als base64 PDF/A bereitstellen, dass dann mit den Metadaten der Einlieferung befüllt wird.

Wieviel Blätter hat mein Dokument?

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. Im Falle der Deckblattoption wird dieses in die gemeldete Seitenanzahl eingerechnet.

Welche Rufnummer wurde hinterlegt?

Initial wurde im Rahmen meiner Registrierung zur E-POSTBUSINESS API die Rufnummer abgefragt und im System hinterlegt. Diese wird solange genutzt, wie keine Aktualisierung über den Client Controller erfolgt.

Welche E-Mail Adresse wurde hinterlegt?

Initial wurde im Rahmen meiner Registrierung zur E-POSTBUSINESS API die E-Mail Adresse abgefragt und im System hinterlegt. Diese wird solange genutzt, wie keine Aktualisierung über den Client Controller erfolgt.

Wie kann ich die hinterlegte Rufnummer prüfen?

Nach meinem erfolgreichen Login kann ich über den Client Controller (TestMobile) eine SMS Nachricht an die für mich hinterlegte Rufnummer zur Prüfung versenden lassen.

Wie kann ich die hinterlegte E-Mail Adresse prüfen?

Nach meinem erfolgreichen Login kann ich über den Client Controller (TestMail) eine E-Mail Nachricht an die die für mich hinterlegte E-Mail Adresse zur Prüfung versenden lassen.

Wie kann ich die hinterlegte Rufnummer ändern?

Zur Änderung der hinterlegten Rufnummern für meine Kundennummer (EKP) muss ich angemeldet sein (erfolgreicher Login) und Zugriff auf die für mich hinterlegte E-Mail Adresse haben. Via Client Controller wird eine Sicherheitscode über MobileRequest unter Angabe der neuen Rufnummer an die hinterlegte E-Mail Adresse gesendet. Dieser ist dann zusammen mit der neuen Rufnummer für die Aktualisierung über SetMobile zu übergeben. Es wird zur Bestätigung automatisch eine SMS Nachricht an die neue Rufnummer versendet.

Wie kann ich die hinterlegte E-Mail Adresse ändern?

Zur Änderung der hinterlegten E-Mail Adresse für meine Kundennummer (EKP) muss ich angemeldet sein (erfolgreicher Login) und Zugriff auf die für mich hinterlegte Rufnummer haben. Via Client Controller wird eine Sicherheitscode über MailRequest unter Angabe der neuen E-Mail Adresse an die hinterlegte Rufnummer gesendet. Dieser ist dann zusammen mit der neuen E-Mail Adresse für die Aktualisierung über SetMail zu übergeben. Es wird zur Bestätigung automatisch eine E-Mail Nachricht an die neue E-Mail Adresse versendet.

Wie stelle ich die Funktionsbereitschaft der API fest?

Ich kann die Funktionsbereitschaft (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.

Wann steht ein Wartungsfenster der API an?

Über die Prüfung der Funktionsbereitschaft (HealthCheck) im Login Controller der API werden die möglichen Wartungsfenster bekannt gegeben. Ein Login ist hierfür nicht notwendig.

Wie kann ich die Mengen meiner Software prüfen?

Mit Hilfe des Vendor Controllers kann ich sowohl die Anzahl der erfolgreichen Sendungen bezogen auf einen Zeitraum, als auch mögliche fehlerhafte Sendungen ermitteln. Der Status der erfolgreich produzierten Schreiben wird (LetterDetailsByDay) gruppiert in reduzierter Form als LetterDetailsPrintedByDay für einen begrenzten Zeitraum bereitgestellt. Hierbei bezieht sich die Eingrenzung des Zeitraumes auf das Produktionsdatum (printFeedbackDate). Für die fehlerhaften Schreiben (LettersWithError) wird der LetterStatus verwendet, wobei dessen Inhalt reduziert und auf die Fehler fokussiert ist. Hierbei bezieht sich die Eingrenzung des Zeitraumes auf den Zeitpunkt der Sendungsannahme (createdDate). 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 der Ergebnisse der Statusabfragen, die ursächlichen Fehler und Informationen.

Kann ich die Mengen meiner Software auch als CSV erhalten?

Zusätzlich zu LetterDetailsByDay kann ich mit LetterDetailsByDayAsCsv die Daten als CSV erhalten.

Wie kann ich als Vendor meine Kontaktdaten pflegen?

Unabhängig der technischen Zugangsdaten zur Verwendung der API ist es wichtig, meine zentralen Kontaktdaten über /api/Vendor/SetContactInformations zu pflegen. Hierbei wird der technische Kontakt für Wartungsinformationen und Support Themen eingesetzt.
Der geschäftliche Kontakt wird zur Kommunikation der wichtigen Systemanpassungen und vertraglich/rechtlichen Themen verwendet.
Nach der Initial-Befüllung aus den technischen Zugangsdaten muss ich diese bei Abweichungen entsprechend hier aktualisieren (ausschließlich mit allen Inhalten neu setzen).

Wie kann ich als Vendor Software spezifische Informationen hinterlegen?

Ich kann zu jeder Sendung eine vendorSystemInformation hinterlegen, in der ich bspw. die Software Version ablege. Diese vendorSystemInformation erhalte ich sowohl im LetterStatus als auch bei den fehlerhaften Schreiben (LettersWithError).