Arbeiten mit der E-POSTBUSINESS API

Die E-POSTBUSINESS API der Deutschen Post ermöglicht eine nahtlose Automatisierung des Briefversands über die Dokumentenversand-Plattform. Durch die Integration dieser API wird der gesamte Prozess – von der digitalen Dokumentenerstellung bis zur physischen Briefzustellung – vollständig automatisiert, sodass kein manueller Aufwand erforderlich ist.

Die API übernimmt folgende Schritte:

Drucken – Wandelt digitale Dokumente in physische Briefe um
Kuvertierung – Steckt Dokumente automatisch in Umschläge
Frankierung – Bereitet Briefe für den Postversand vor

Sobald der Brief bereit ist, kümmert sich die Deutsche Post um die Zustellung, wodurch manuelle Eingriffe entfallen. Diese Automatisierung spart Unternehmen Zeit und Kosten und sorgt gleichzeitig für eine zuverlässige und effiziente Versandlösung.

Info

Bevor Sie erfolgreich Briefe versenden können, muss die E-POSTBUSINESS API eingerichtet werden. Detaillierte Anweisungen zur Einrichtung finden Sie hier.

Erstellen und Versenden eines Dokuments über E-POST

Mit der E-POSTBUSINESS API können Benutzer Dokumente direkt aus Business Central als Briefe versenden.

Schritte zum Erstellen und Versenden eines Briefes über die API:

Navigieren Sie zu einem Dokument (z. B. gebuchte Verkaufsrechnung) in Business Central.
Verwenden Sie die Aktion E-Post senden im Document Dispatch-Factbox.
- Stellen Sie sicher, dass Sie ein Versandprofil für die Tabelle haben, aus der ein Dokument gesendet werden soll.
Fügen Sie die gewünschten Dokumente oder Anhänge hinzu und wählen Sie Ihre spezifischen gewünschten Versandoptionen aus. Diese Optionen umfassen:
- Einschreiben
  - Einwurf-Einschreiben (Drop-Off Registered Mail):
    - Der Brief wird direkt in den Briefkasten des Empfängers zugestellt, ohne dass eine Unterschrift erforderlich ist.
    - Diese Option bietet eine grundlegende Nachverfolgung und einen Zustellnachweis, der bestätigt, dass der Brief im Briefkasten abgelegt wurde.
    - Ideal für wichtige, aber nicht kritische Dokumente, bei denen keine Unterschrift erforderlich ist, wie Benachrichtigungen oder allgemeine Korrespondenz.
  - Einschreiben (Registered Mail):
    - Der Brief wird persönlich an den Empfänger oder eine autorisierte Person gegen Unterschrift übergeben.
    - Der Absender erhält eine Bestätigung, dass der Brief zugestellt wurde, jedoch keinen zusätzlichen Nachweis darüber, wer ihn genau erhalten hat.
    - Geeignet für sensible Dokumente, bei denen eine direkte Übergabe erforderlich ist, wie Verträge oder rechtliche Mitteilungen.
  - Einschreiben mit Rückschein (Registered Mail with Return Receipt):
    - Neben der Unterschrift des Empfängers erhält der Absender eine schriftliche Zustellbestätigung (Rückschein).
    - Der Rückschein enthält den Namen und die Unterschrift des Empfängers und dient als rechtlich gültiger Empfangsnachweis.
    - Empfohlen für sehr wichtige oder rechtlich bindende Dokumente, wie Kündigungsschreiben, rechtliche Mitteilungen oder offizielle Kommunikationen.
  - Deckblatt
    - Fügt dem Versand eine Titelseite hinzu, die zusätzliche Informationen enthalten oder als Trennblatt zwischen verschiedenen Dokumentabschnitten dienen kann.
  - Duplex
    - Ermöglicht das doppelseitige (Duplex-) Drucken, um Papier zu sparen und den Versand umweltfreundlicher zu gestalten.
  - Farbe
    - Gibt an, ob das Dokument in Farbe oder Schwarz-Weiß gedruckt werden soll. Dies ist nützlich für Dokumente, die Bilder oder wichtige farbcodierte Informationen enthalten.
Wählen Sie die Aktion OK aus.
Nach der Bestätigung im Dialog sendet die API das Dokument automatisch an die Deutsche Post, wo es gedruckt und versendet wird.

Info

Die Kombination von Duplex und Einschreiben ist nicht möglich. Wenn Sie Duplex auswählen, wird die Option Einschreiben deaktiviert. Diese Funktion erfordert eine aktive API-Verbindung zur Deutschen Post.

Versenden eines Dokuments über E-POST ins Ausland

Die E-POSTBUSINESS API unterstützt auch den internationalen Dokumentenversand. Um ein Dokument ins Ausland zu senden, müssen zunächst die erforderlichen Konfigurationen abgeschlossen werden.

Schritte für den internationalen Versand:

Navigieren Sie zu Ihrem Empfänger, zum Beispiel einem Kunden, der für diese Einrichtung vorgesehen ist.
Wählen Sie den Empfänger aus und öffnen Sie die Karte des Empfängers.
Setzen Sie den Länder-/Regionscode des Empfängers, um eine korrekte Adressierung für den Versand sicherzustellen.
Navigieren Sie im Dropdown-Menü des Feldes Länder-/Regionscode zur vollständigen Länder-/Regionenliste.
- Wenn der Länder-/Regionsname in Deutsch in der vollständigen Länder-/Regionenliste vorhanden ist, aber die ausgewählte Umgebungsprache von Business Central nicht Deutsch ist, fahren Sie mit dem nächsten Schritt fort.
- Andernfalls, wenn sowohl der Name als auch die Umgebung auf Deutsch sind, überprüfen Sie einfach den Ländernamen und passen Sie ihn gegebenenfalls an, wenn er nicht mit ISO 3166‑1 übereinstimmt.
Wenn die Umgebungsprache nicht Deutsch ist, müssen die deutschen Übersetzungen für die Länder-/Regionsnamen manuell gemäß den Anforderungen der Deutschen Post eingegeben werden.
- Diese können über die Aktion Übersetzungen auf derselben Seite hinzugefügt werden.
- Die Ländernamenübersetzungen für den Sprachcode DEU müssen den ISO 3166‑1-Standards entsprechen und im Feld Name eingegeben werden, um einen korrekten Versand sicherzustellen.
Sobald die Übersetzung abgeschlossen und die internationale Adresse konfiguriert ist, können Sie das Dokument wie gewohnt über die Aktion E-Post senden im Dokumenten-Central-FactBox versenden.

Info

Um eine Selbstüberprüfung der Einrichtung durchzuführen, können Sie die Aktion E-Post senden Dialog im Dokumenten-Central-FactBox verwenden. Wenn die Konfiguration korrekt ist, öffnet sich der Dialog und zeigt den Ländernamen in Großbuchstaben im Feld Land an. Andernfalls, wenn es eine Fehlkonfiguration bezüglich der internationalen Versandkonfiguration gibt, wird der Dialog nicht geöffnet und es wird ein Fehler angezeigt.

Wenn der Versand ohne Angabe eines Länder-/Regionscodes durchgeführt wird (d. h. buchstäblich leer gelassen wird), behandelt die Deutsche Post dies als Inlandsversand. Daher ist es notwendig, die Konfiguration des Länder-/Regionscodes vor dem Versand ins Ausland abzuschließen.

Anzeige des Versandstatus in Business Central

Alle Sendungen, einschließlich E-Post-Versand, werden in der Document Dispatch - Warteschlange aufgeführt und protokolliert. Innerhalb dieser Warteschlange gibt es eine spezifische Aktion für E-Post-Einträge namens "E-Post-Informationen".

Durch Auswahl dieser Aktion wird eine Seite geöffnet, die folgende Informationen anzeigt:

Allgemeine Informationen

Eintragsnummer
Quell-Dokument
Testmodus-Indikator
Datum der letzten Statusaktualisierung

Briefinformationen

Brief-ID
Ausgewählte Versandoptionen

Empfängerinformationen

Empfängername
Empfängeradresse

Statusverfolgung

Eine ListPart protokolliert alle abgefragten Status, jeweils mit einer Status-ID und einem Status-Code.

Status-IDs und Erklärungen:

1 - Annahme der Sendung - Die Sendung wurde erfolgreich übermittelt, und es wurden keine Schema- oder Inhaltsverstöße im JSON festgestellt. - Statuszuweisung: Nach erfolgreichem Hochladen der Sendung.

2 - Bearbeitung der Sendung - Das PDF wurde auf E-Post-Konformität überprüft und für den Druck freigegeben. - Hinweis: Trotz gründlicher Überprüfung können technische Fehler im PDF zu Verarbeitungsfehlern im Druckzentrum führen, was zu Status 99 führt. - Statuszuweisung: Wenige Minuten nach der Annahme der Sendung.

3 - Übergabe an das Druckzentrum - Die Sendung wurde an das Druckzentrum zur Produktion übergeben. - Hinweis: Falls technische Fehler eine Verarbeitungsstörung verursachen, wird Status 99 anstelle von Status 4 ausgegeben. - Statuszuweisung: Innerhalb weniger Stunden nach der Bearbeitung.

4 - Verarbeitung im Druckzentrum - Die Sendung wurde vom Druckzentrum als "versendet" markiert. - Statuszuweisung: 1-2 Werktage nach der Übergabe an das Druckzentrum.

99 - Verarbeitungsfehler - Siehe Fehlerliste für Details.

Warteschlangen-Eintrag Status

Der Status eines Warteschlangeneintrags wird gemäß den Prozessschritten aktualisiert. Sobald der Status "4" (Bearbeitung im Druckzentrum) erreicht ist, wird der Eintrag als "gesendet" markiert.

Nach einem erfolgreichen E-Post-Versand erhält der Warteschlangeneintrag den Status "Versand gestartet". Dieser Status zeigt den Beginn des Versandprozesses an. Er wird automatisch mit allen nachfolgenden E-Post-Prozessstatus aktualisiert, vorausgesetzt, dass die Jobwarteschlange "Document Dispatch Automatische E-Post-Briefstatusaktualisierung" läuft.

Statuscodes und Erklärungen:

Fehler: Erfordern Maßnahmen, Verarbeitung abgebrochen

E001 - Ungültige Anmeldeinformationen – Überprüfen Sie die Anmeldedaten
E002 - Ungültige Anmeldeinformationen – VendorSubID inkorrekt
E003 - Zu viele SMS-Anfragen – 15 Minuten gesperrt
E004 - EKP von der Deutschen Post gesperrt
E101 - Ungültiges Token – Abgelaufen
E201 - Ungültige Statusabfrage – Keine Sendung gefunden
E203 - Abweichung der Adressmetadaten festgestellt
E301 - Kein PDF-Format erkannt
E302 - Verletzung des DVF-Einschränkungsbereichs
E303 - Maximale Dateigröße von 20 MB überschritten
E304 - Maximale Seitenanzahl von 94 überschritten
E305 - Ungültiger Länder-/Regionscode
E306 - Ungültiges Empfängeradressformat
E307 - Erste Seite im Querformat
E308 - Nicht-DIN A4-Format erkannt
E309 - Doppelte Dateinamen erkannt
E311 - Ungültige Kombination: Einschreiben und internationaler Versand
E312 - Ungültige Kombination: Duplex + Einschreiben
E313 - Briefschema-Verletzung
E314 - Dateigröße des Deckblatts überschreitet 1 MB
E315 - Verarbeitungsfehler bei der Sendung
E316 - Upload-Fehler
E317 - Ungültiges Einschreiben-Format
E318 - Ablehnung im Druckzentrum
E319 - EKP nicht für das Druckzentrum genehmigt – Live-Versand nicht möglich
E320 - Maximale Anzahl von Testsendungen pro Tag erreicht
E322 - Häufigkeit der Statusanfragen zu hoch – Mindestens 5 Sekunden zwischen Anfragen
E323 - Kein Inhalt im Empfängerbereich erkannt (leere Seite)
E333 - Absenderadresse nicht auf dem Dokument vorhanden.
E399 - Allgemeiner Fehler
E501 - API-Status: Inaktiv
E601 - Plugin-Fehler
E900 - Unbestimmter Fehler

Warnungen: Können Maßnahmen erfordern, aber die Verarbeitung wird fortgesetzt

W101 - PDF/A-Konvertierungswarnungen
W201 - Adressbereich überschritten
W202 - Linker Einschränkungsbereich überschritten (wird weiß gemacht)
W203 - Abweichungen der Adressmetadaten
W220 - Ab dem 01.10.2022 werden die Rückscheinadressdetails automatisch aus dem sichtbaren Absenderbereich des Briefes extrahiert
W301 - Absenderadresse fehlt (ab dem 01.07.2025 wird das Fehlen einer Absenderadresse auf eingereichten Dokumenten als Fehler betrachtet (“E333”)).
W501 - API-Status: Wartungsbenachrichtigung
W601 - Plugin-Warnung

Informationsnachrichten: Keine Maßnahmen erforderlich

I101 - Zusätzliche Option: PDF zu PDF/A-Konvertierung
I501 - API-Status: OK
I601 - Plugin-Info
I701 - Statusaktualisierung zur Sendungsverfolgung
I751 - Statusmeldung für die Zielregion

E-Post API Gesundheitscheck

Document Dispatch bietet eine integrierte Möglichkeit, den Status Ihrer E‑POSTBUSINESS API-Verbindung zu kontrollieren.

Folgen Sie diese Schritten, um den E-POST Business API-Status zu kontrollieren:

Wir beginnen in der Rolle Document Dispatch - Administrator.
Öffnen Sie Moduleinrichtung aus dem Menü Einrichtung in der Menüleiste.
Klicken Sie auf E-Post im Menü Document Dispatch Moduleinrichtung.
Führen Sie die Aktion E-Post API Gesundheitscheck aus.

Sie erhalten Informationen direkt von der Deutschen Post E‑POSTBUSINESS API.

Warteschlangenprotokoll für E-Post-Einträge

Das Dokumentenversand-Warteschlangenprotokoll verfolgt Ereignisse im Zusammenhang mit jedem Versandtyp. Für E-Post-Einträge bietet das Protokoll eine detaillierte Historie der Versandaktionen, einschließlich:

Wann ein E-Post-Brief erfolgreich gesendet wurde.
Ob ein Brief im Testmodus gesendet wurde.
Systemfehler oder Ausfälle während des Versandprozesses.

Benutzer können die Warteschlangenprotokolle innerhalb der Dokumentenversand-Warteschlange mit der Aktion Protokoll anzeigen überprüfen, um Versandaktivitäten zu überwachen und mögliche Probleme zu diagnostizieren.

E-Post Protokoll

Das E-Post Protokoll bietet eine detaillierte Prüfung der Systemaktionen im Zusammenhang mit E-Post, einschließlich:

Anmeldeversuche: Erfolgreiche und fehlgeschlagene Authentifizierungsversuche.
Passwortänderungen: Protokolliert, wann ein Passwort für den E-POSTBUSINESS API-Benutzer geändert wurde.
SMS-Code-Anfrageversuche: Wann ein neuer SMS-Code erfolgreich angefordert und fehlgeschlagen ist.

Das E-Post-Protokoll ermöglicht es Administratoren, Änderungen zu verfolgen und die Sicherheit der E-POSTBUSINESS API zu gewährleisten.

Arbeiten mit dem automatischen Adress-Setzer

Der automatische Adress-Setzer stellt sicher, dass Empfängeradressen korrekt für den E-Post-Briefversand positioniert sind.

Schritte zur Verwendung des automatischen Adress-Setzers:

Öffnen Sie beispielsweise eine gebuchte Verkaufsrechnung in Business Central.
Wählen Sie einen Eintrag und klicken Sie auf die Aktion E-Post senden im Dokumentenversand-Factbox.
Stellen Sie sicher, dass eine Adressüberlagerungskonfiguration eingerichtet und aktiviert wurde.
Beim Erstellen eines Dokuments für den E-Post-Versand wendet das System automatisch die voreingestellte Adressüberlagerung an.
Überprüfen Sie die Dokumentenvorschau im Dialog, um sicherzustellen, dass die Adressüberlagerung korrekt angewendet wurde.
Senden Sie das Dokument durch Bestätigung des Dialogs mit der OK-Aktion.

Durch die Nutzung des automatischen Adress-Setzers können Benutzer die Anforderungen der Deutschen Post einhalten, Fehler reduzieren und den Versand optimieren.

Siehe auch

Einrichten der E-POSTBUSINESS API