Die E-POSTBUSINESS API (API) bietet einfache Methoden für den Versand von Dialogpostsendungen im Inland gemäß den technisch dokumentierten Rahmenparametern (bspw. Anzahl Seite, Simplex/Duplex, Farbe/SW, etc.)
und die Dialogpost Implementierungsrichtlinien.
Zusätzlich sind die Formatvorlagen und Hinweise für die Werbemittel zu beachten (siehe Formatvorlagen Dialogpost).
Das entsprechende Werbemittel im DIN A4 Hochformat ohne Anschnittkanten sowie ohne Schnittmarken ist als PDF (base64 String) bereitzustellen, wobei die PDF Version PDF/X-3:2002 erwartet wird. Andere PDF Versionen (bspw. PDF/X-1a, PDF/X-3 und PDF/X-4) können von Abweichungen im Druckbild bis zur fehlenden Unterstützung in der Produktion reichen.
Für eine Kampagne sind neben dem Werbemittel die zugehörigen Empfängeradressen als auch die Rechnungsempfänger- und Absenderdaten sowie das Auflieferungsdatum bereitzustellen.
Eine vorherige eingeschränkte Werbemittel Prüfung und Vorab-Kalkulation ermöglicht die Validierung des Werbemittels und Anschriften sowie eine Kosteneinschätzung ohne eine Kampagne anzulegen.
Der Dialogpost Versand wir mit der Eröffnung einer Kampagne und ihren Daten gestartet. Nach der Validierung des Werbemittels mit ausgewählten Anschriften sind neben der Kostenkalkulation die rechtlichen Rahmenbedingungen vom E-POST Nutzer zu bestätigen, damit dieser die kostenpflichtige final Auftragsausführung bestätigt.
Der Status der jeweiligen Kampagne kann dediziert oder über einen Zeitraum abgerufen werden, wobei die abrufbaren Daten unterschiedlich lange verfügbar sind.
Aus den Rückmeldungen des Status sind dann die entsprechenden Benutzerinteraktionen und Supportanfragen vertragsgemäß abzuleiten. Die Implementierung der API setzt einen gültigen API Nutzervertrag voraus.
Formatvorlagen Dialogpost:
Vorlage Brief A4 - 1 Blatt Einseitig bedruckt
Vorlage Brief A4 - 1 Blatt Beidseitig bedruckt
Vorlage Brief A4 - 2 Blatt Einseitig bedruckt
Vorlage Brief A4 - 2 Blatt Beidseitig bedruckt
Vorlage Brief A4 - 3 Blatt Einseitig bedruckt
Vorlage Brief A4 - 3 Blatt Beidseitig bedruckt
Muss ich als API Nutzer Dialogpost implementieren?
Ich kann als API Nutzer auch ausschließlich den hybriden Briefversand der E-POST nutzen, ohne die Dialogpost zu implementieren.
Kann ich als API Nutzer ausschließlich Dialogpost 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 meiner Software bereit. Eine ausschließliche Implementierung der Dialogpost ist nicht möglich, ohne die Kernfunktionen der E-POSTBUSINESS API zu implementieren.
Gibt es einen separaten Entwicklungsmodus für Dialogpost?
Neben dem grundsätzlichen Entwicklungsmodus der E-POSTBUSINESS API unterliegen die Methoden der Dialogpost einem eigenen Entwicklungsmodus.
Wie wechsle ich als API-Nutzer für Dialogpost vom Entwicklungsmodus in den Produktivmodus?
Der Wechsel vom Entwicklungsmodus zum Produktivmodus für die Dialogpostmethoden wird durch den API Support vorgenommen. Wenn ich die Dialogpost-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. Nach Prüfung der Angaben und einer erfolgreichen Sichtung der Benutzerinteraktionen (gemäß der vertraglichen Regelung), schaltet der Support in den Dialogpost Produktivmodus. Erst dann können die Kampagnen finalisiert und übermittelt werden. Der API Support gibt mir über diese Produktivschaltung eine Rückmeldung.
Benötige ich den Produktivmodus der API für Dialogpost ?
Die Dialogpost ist ein additiver Teil der E-POSTBUSINESS API. Nur eine produktive E-POSTBUSINESS API ermöglicht mir den Zugang zu den additiven Dialogpostmethoden und deren Produktivschaltung.
Wer kann Dialogpost über die E-POSTBUSINESS API versenden?
Jeder meiner aktiven E-POST Nutzer kann Dialogpost Sendungen versenden. Eine zusätzliche Freischaltung/Aktivierung ist nicht notwendig.
Muss der E-POST Nutzer sich für die Dialogpost aktivieren?
Wenn mein E-POST Nutzer sich mit meiner Software aktiviert hat, wird keine weitere Aktivierung für die Nutzung der Dialogpost benötigt.
Was wird für einen Dialogpost Versand 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.
Benötigt ein Dialogpost Versand Vorlauf?
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.
Kann ich Daten zur Dialogpost vorab prüfen?
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.
Was wird beim Werbemittel überprüft?
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.
Gibt es einen Unterschied von der Vorab Kalkulation und der Preisberechnung im Rahmen der Kampagne?
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.
Was gehört zu einer Kampagne?
Eine Kampagne besteht neben ihrer ID, dem freiwählbaren Namen aus dem Werbemittel und den zugehörigen Empfängeradressen, aus 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).
Was gehört zu einer finalen Beauftragung?
Die finale Beauftragung beinhaltet aus den Kampagne Daten deren ID und Name, die Rechnungsempfängerdaten und das Absenderdatum, Kontaktdaten, die Produktionsdaten (bspw. Anzahl Seite, Farbewahl, Anzahl Schreiben, etc.), Geschäftsbedingungen, Preise und einen Zeitstempel.
Was muss ich bei meiner Implementierung für Dialogpost beachten?
Neben den Vorabprüfungen, welche explizit zur Evaluierung von Werbemitteln und Kosten zu verwenden sind, ist ein leichtgewichtiger Prozessablauf für die Beauftragung einer Kampagne einzuhalten. Die eröffnete Kampagne kann bis zur Beauftragung noch jederzeit verworfen werden (/api/Campaign/{id}/Cancel siehe auch FAQ: Kann ich eine Kampagne abbrechen?). Die Kampagne muss ich mit ihren Daten öffnen (/api/Campaign/Open). Danach muss ich die Generierung der Werbemittel (/api/Campaign/{id}/ConfirmRequest) zur Validierung anstoßen. Im vorgegebene Zeitfenster ist dann das generierte Werbemittel abzurufen (/api/Campaign/{id}/ConfirmData) und dem E-POST Nutzer zur Validierung zuzuführen. Da nun alle grundlegenden Daten für eine Preiskalkulation und spätere Beauftragung vorliegen, stoße ich die Kalkulation (/api/Campaign/{id}/FinalizeInfo) mit den finalen Auftragsdaten an. Ich erhalte die Informationen (CampaignFinalizeInfo) zur finalen Beauftragung. In einem modalen Benutzerdialog für meinen E-POST Nutzer lasse ich ü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) führe ich im angegebenen Zeitfenster mit Hilfe der bereitgestellten finalen Beauftragung (CampaignFinalizeInfo) durch.
Kann ich eine Kampagne nachträglich ändern?
Eine Kampagne kann nach der Eröffnung nicht mehr geändert werden. Solange Sie nicht beauftragt (/api/Campaign/{id}/Finalize) wurde, kann sie jedoch jederzeit verworfen (/api/Campaign/{id}/Cancel) und somit neue erzeugt werden (/api/Campaign/Open ).
Wie oft kann ich Werbemittel für eine Kampagne generieren?
Solang ich nicht die Kampagne beauftragt oder abgebrochen habe, bzw. sie zeitbedingt abgebrochen wurde, kann ich jederzeit die Werbemittel auch mit jeweils anderen Adresspositionen generieren (/api/Campaign/{id}/ConfirmRequest). Dabei werden mögliche bisherige Dokumente überschrieben.
Wie oft kann ich die Werbemittel einer Kampagne abrufen?
Solange ich nicht die Kampagne beauftragt oder abgebrochen habe, bzw. sie zeitbedingt abgebrochen wurde, kann ich jederzeit die Werbemittel abrufen (/api/Campaign/{id}/ConfirmData). Dabei werden die Dokumente des letzten Generierungsaufrufes für Werbemittel (/api/Campaign/{id}/ConfirmRequest) bereitgestellt.
Wie oft kann ich die Beauftragungsdaten für eine Kampagne abrufen?
Solang ich nicht die Kampagne beauftragt oder abgebrochen habe, bzw. sie zeitbedingt abgebrochen wurde, kann ich jederzeit die Beauftragungsdaten (CampaignFinalizeInfo) einer Kampagne abrufen. Nur mit dem letzten Aufruf kann auch die Beauftragung ((/api/Campaign/{id}/Finalize) durchgeführt werden.
Welchen Status hat meine Kampagne?
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. Ich erhalte somit einen genauen Überblick über den aktuellen Verarbeitungsstatus.
Kann ich eine Kampagne abbrechen?
Solange ich nicht die Kampagne beauftragt oder abgebrochen habe, bzw. sie zeitbedingt abgebrochen wurde, kann ich sie abbrechen.
Wie gehe ich mit Fehlermeldungen um?
Mit dem zurückgelieferten Status der Kampagne 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 Produktionsproblem unterscheiden kann. Im Falle, dass ich zur Schnittstelle oder der E-POST Nutzer zur Druck/Zustellung eines Supports bedienen muss, ist hierzu die Kundennummer der Deutschen Post (EKP) des E-POST Nutzers, mein Name, die konkrete campaignID und der Status der Kampagne aus dem Status (siehe /api/Campaign/{id}/Status oder /api/Campaign/Date) bereitzustellen.
Wie kann ich die Dialogpost Mengen meiner Software prüfen?
Mit Hilfe des Vendor Controllers kann ich 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).
Wie kann ich als Vendor Software spezifische Informationen hinterlegen?
Ich kann zu jeder Kampagne eine vendorSystemInformation hinterlegen, in der ich bspw. die Software Version ablege. Diese abgelegte vendorSystemInformation erhalte ich im CampaignStatus zurück.