Serienbrief erzeugen

IO Factory – Brief – HTTP Schnittstelle - V3.0 Release 3
HTTP Schnittstelle - Brief
Soll ein Brief versendet werden, muss folgende URL
https://poststelle.deltra.de/messaging/letter
mit den im weiteren Verlauf der Dokumentation beschriebenen Parametern mittels eines multipart/form-data kodierten
HTTP-Post aufgerufen werden.
Feld
account
password
mandant
test
color
duplex
document
Beschreibung
Benutzername
Passwort
Mandant
Testmodus
Farbdruck
Duplexdruck
Zu versendender Brief
Hinweis
Pflicht
Der Standard ist ‚orgaMAX’
Es erfolgt kein Versand eines Briefes
[on|off], der Standard ist ‚off’
[on|off], der Standard ist ‚off’
Muss vom Typ application/pdf sein
ja
ja
ja
Sollen Briefe europa- oder weltweit verschickt werden, muss das entsprechende Porto durch den Parameter destination
ausgewählt werden.
Feld
destination
Beschreibung
Porto
Hinweis
Mögliche Werte sind: national, european, world
Die möglichen Werte sind hierbei:
national
: deutschlandweiter Versand - Standard
european
: europaweiter Versand
world
: weltweiter Versand
Sollen Briefe mit Zusatzleistungen wie 'Einschreiben' versehen werden, so muss der Parameter registered gesetzt werden:
Feld
registered
Beschreibung
Versand als Einschreiben
Hinweis
Mögliche Werte sind: R, RI, RE, RR, RRE
Die möglichen Werte sind hierbei:
R
: Für den Versand als Einschreiben
RI
: Für den Versand als Einwurfeinschreiben
RE
: Für den Versand als Einschreiben mit Vermerk ‘Eigenhändig’
RR
: Für den Versand als Einschreiben mit Rückschein
RRE
: Für den Versand als Einschreiben mit Rückschein und dem Vermerk ‘Eigenhändig’
Temporär gespeicherte oder konvertierte Briefe können unter Angabe des Parameter session anstelle von document
versendet werden:
Feld
session
Beschreibung
Hinweis
Temporär gespeicherter Brief
Eindeutige Id des temporär gespeicherten oder konvertierten Briefes
Die Schnittstelle zum temporären Speichern von Briefen und deren Anwendung wird im folgenden beschrieben.
Das Format der Rückgabe der Briefschnittstelle ist wie folgt:
Code : Fehlerbeschreibung : [Id des Briefes]
Über die Id des Briefes kann der Status einzelner Briefe abgefragt werden. Die Schnittstelle zum Abfragen der Stati wird
im weiteren Verlauf der Dokumentation beschrieben.
IO Factory Ltd. • Flughafenstraße 52a (Haus C) Airport Center • 22335 Hamburg
Tel. +49 40 532 99 271 • Fax +49 40 532 99 100 • E-Mail [email protected] • Web http://www.iofactory.de
IO Factory – Brief – HTTP Schnittstelle - V3.0 Release 3
HTTP Schnittstelle – Temporärer Brief
Zu versendende Briefe können vor dem eigentlichen Versand temporär auf dem Server gespeichert werden. Hierfür muss
folgende URL
https://poststelle.deltra.de/messaging/store
mit den im Anschluss beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden. Im Anschluss kann beispielsweise ein Vorschaubild des zu versendenden Dokumentes erstellt werden.
Feld
account
password
mandant
mimeType
destination
document
name
Beschreibung
Benutzername
Passwort
Mandant
Mime Typ
Mime Typ
Dokument
Name des Dokumentes
Hinweis
Der Standard ist ‚orgaMAX’
Mime-Typ des hochzuladenen Dokumentes
Ziel Mime-Typ des hochzuladenen Dokumentes
Pflicht
ja
ja
ja
ja
ja
ja
ja
Der Briefdienst erwartet ein Dokument vom Typ application/pdf. Dokumente von einem anderen Typ können mittels
Angabe des Mime-Typs application/pdf im Parameter destination in ein PDF konvertiert werden.
Die Rückgabe erfolgt in folgender Form:
Code : Fehlerbeschreibung [[: Session] : Id]
Der Parameter Id gibt bei mehreren Dokumenten pro Session einen eindeutigen Identifikator pro Dokument zurück. Der
Parameter Session wird für die Erzeugung eines Vorschaubildes oder den Abruf von Historien benötigt.
Um ein Vorschaubild von einem Dokument zu erzeugen, muss folgende URL
https://poststelle.deltra.de/messaging/thumbnail
mit den im folgenden beschriebenen Parametern mittels eines HTTP -POST oder GET aufgerufen werden.
Feld
account
password
mandant
session
height
width
Beschreibung
Benutzername
Passwort
Mandant
Session
Höhe in Pixel
Breite in Pixel
Hinweis
Der Standard ist ‚orgaMAX’
Mittels 'Hochladen' von Dokumenten erzeugte Session
Pflicht
ja
ja
ja
ja
ja
Ja
Der Bereich des Briefes in dem sich die Angaben zum Empfänger befinden müssen, so dass diese korrekt durch den
Briefzusteller gelesen werden können, kann durch Angabe des Parameters overlay grafisch hervorgehoben werden.
Feld
overlay
Beschreibung
Adressfeldmarkierung
Hinweis
Durch Angabe von window wird das Adressfeld hervorgehoben
Die Rückgabe erfolgt in Form eines PNG Bildes in der angeforderten Größe.
IO Factory Ltd. • Flughafenstraße 52a (Haus C) Airport Center • 22335 Hamburg
Tel. +49 40 532 99 271 • Fax +49 40 532 99 100 • E-Mail [email protected] • Web http://www.iofactory.de
IO Factory – Brief – HTTP Schnittstelle - V3.0 Release 3
HTTP Schnittstelle – Brief Versand Historie
Um eine Historie der versendeten Briefe abzurufen, muss folgende URL
https://poststelle.deltra.de/messaging/letter/outbound/history
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
account
password
mandant
since
Beschreibung
Hinweis
Benutzername
Passwort
Mandant
Anzeigen der Liste ab einem Zeitpunkt
Der Standard ist ‚orgaMAX’
Format dd.MM.yyyy HH:mm:ss
Pflicht
ja
ja
ja
Die Rückgabe der Brief Versand Historie erfolgt in Form eines XML Dokumentes. Das XML Schema kann unter folgender URL
bezogen werden:
https://poststelle.deltra.de/docs/letter_outbound_history.dtd
Der Status des Versandes wird im Feld PostalMessageStatusTypeId dokumentiert. Mögliche Werte hierfür sind:
1:
2:
3:
4:
5:
6:
Der Brief wurde vom Server entgegengenommen und gespeichert
Der Brief befindet sich gerade im Druck
Der eingeschriebene Brief befindet sich gerade im Druck
Der Brief wurde erfolgreich gedruckt und an die Post übergeben
Beim Versand trat ein Fehler auf
Der Brief wurde im Testmodus verarbeitet
Der Typ des Briefes wird im Feld PostalMessageTypeId dokumentiert. Mögliche Werte hierfür sind:
1:
2:
3:
Brief
Eingeschriebener Brief
Serienbrief
Um einen einzelnen Eintrag der Brief Versand Historie abzurufen, muss folgende URL
https://poststelle.deltra.de/messaging/letter/outbound
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
Beschreibung
account
password
mandant
session
Benutzername
Passwort
Mandant
Id des versandten Briefes
Hinweis
Der Standard ist ‚orgaMAX’
Aus der Historie oder als Rückgabe des Versandes
Pflicht
ja
ja
ja
ja
Die Rückgabe des Eintrags in der Brief Versand Historie erfolgt in Form eines XML Dokumentes. Das XML Schema kann unter
folgender URL bezogen werden:
https://poststelle.deltra.de/docs/letter_outbound_history.dtd
IO Factory Ltd. • Flughafenstraße 52a (Haus C) Airport Center • 22335 Hamburg
Tel. +49 40 532 99 271 • Fax +49 40 532 99 100 • E-Mail [email protected] • Web http://www.iofactory.de
IO Factory – Brief – HTTP Schnittstelle - V3.0 Release 3
Serienbrief erzeugen
Um einen Serienbrief zu erzeugen, muss zusätzlich zum Dokument eine Datenquelle an den Server übermittelt werden.
Feld
Beschreibung
document
csv
store
Zu versendender Serienbrief
CSV oder Tabellenformat
Speichern des Serienbriefs
Hinweis
Pflicht
Muss ein Office Format wie MS Word, OpenOffice oder RTF sein
Muss ein CSV oder Tabellen Format wie Excel sein
[on|off], der Standard ist ‚off’
ja
Ja
Die im Feld document übermittelte Vorlage muss im Gegensatz zum normalen Briefversand aus einem gängigen Office Format
wie zum Beispiel MS Word, OpenOffice oder RTF bestehen. In dieser Vorlage werden Platzhalter wie beispielsweise „[name]“
definiert. Diese Platzhalter werden mit Werten aus der Datenquelle ersetzt. Diese muss aus einem gängigen Office Format wie
MS Excel, OpenOffice oder CSV bestehen. In der ersten Zeile der Datenquelle muss die Definition der Platzhalter stehen. Jede
weitere Zeile definiert einen Brief. Beispiele für eine Serienbriefvorlage oder eine Datenquelle können unter folgender URL
bezogen werden:
OpenOffice Serienbrief https://poststelle.deltra.de/docs/Serienbrief.odt
OpenOffice Datenquelle https://poststelle.deltra.de/docs/Serienbrief.ods
CSV Datenquelle https://poststelle.deltra.de/docs/Serienbrief.csv
Eine detaillierte Anleitung zur Erstellung eines Serienbriefes können Sie unter folgender URL finden:
Serienbrief Howto: https://poststelle.deltra.de/docs/Serienbrief-HowTo.pdf
Entspricht der zu versendende Serienbrief gewissen Vorgaben, so kann eine Portooptimierung vorgenommen werden. Hierbei
werden Teile des Serienbriefes als Infobrief oder -post versendet, so dass sich eine Einsparung im Bereich der Portokosten
erzielen lässt. Um die Portooptimierung nutzen zu können, muss sich die Postleitzahl des Empfängers in der ersten Spalte der
Datenquelle befinden.
Feld
optimization
Beschreibung
Portooptimierung
Hinweis
[on|off], der Standard ist ‚off’
Wird der Parameter store gesetzt, so wird der zu erzeugende Serienbrief temporär auf dem Server gespeichert und kann zu
einem späteren Zeitpunkt unter Angabe der session versendet werden. Der Parameter store kann in Verbindung mit dem
Parameter optimization dazu genutzt werden, um das Ergebnis einer eventuellen Portooptimierung zu erfahren. Das Format
der Rückgabe ist wie folgt:
Code : Fehlerbeschreibung [: session [: # Briefe : # Infobriefe : # Infopost]]
Der Parameter session gibt die Session des (gespeicherten) Serienbriefes an. Der Parameter # Briefe gibt die Anzahl als
normaler Brief mit € 0,55 Porto, der Parameter # Infobriefe gibt die Anzahl als Infobrief mit € 0,35 Porto, der Parameter #
Infopost gibt die Anzahl als Infopost mit € 0,25 Porto versandten Briefe an. Die Angabe der Anzahl der unterschiedlichen
Brieftypen erfolgt nur wenn eine Portooptimierung eine Ersparnis erbringt.
Eine Übersicht über die Anforderungen der Deutschen Post AG an Info- und Postbriefe können aus folgender Dokumentation
der Deutschen Post AG entnommen werden. Sollte sich ein Serienbrief nicht an die Anforderungen halten, kann es passieren,
dass die Deutschen Post AG Nachforderungen gegenüber dem Absender geltend macht.
Anforderungen an einen Serienbrief: https://poststelle.deltra.de/docs/dp_handling_03_08.pdf
IO Factory Ltd. • Flughafenstraße 52a (Haus C) Airport Center • 22335 Hamburg
Tel. +49 40 532 99 271 • Fax +49 40 532 99 100 • E-Mail [email protected] • Web http://www.iofactory.de
IO Factory – Brief – HTTP Schnittstelle - V3.0 Release 3
HTTP Schnittstelle – Serienbrief Historie
Um eine Historie der Serienbriefe abzurufen, muss folgende URL
https://poststelle.deltra.de/messaging/mailmerge/history
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
account
password
mandant
type
Beschreibung
Benutzername
Passwort
Mandant
Typ der Liste
Hinweis
Der Standard ist ‚orgaMAX’
Mögliche zugelassene Werte sind: 1
Pflicht
ja
ja
ja
ja
Die Rückgabe der Serienbrief Historie erfolgt in Form eines XML Dokumentes. Das XML Schema kann unter folgender URL
bezogen werden:
https://poststelle.deltra.de/docs/mailmerge_history.dtd
Der Typ des Eintrages in der Historie wird über das Feld MailMergeTypeId dokumentiert. Mögliche Werte hierfür sind:
1:
2:
3:
Serienbrief
Serienfax
Serien-SMS
Der Status eines Serienbriefes wird über das Feld MailMergeStatusTypeId dokumentiert. Mögliche Werte hierfür sind:
1:
2:
3:
4:
Der Serienbrief wurde erzeugt und gespeichert
Der Serienbrief wurde in den Druck gegeben
Der Serienbrief wurde erfolgreich gedruckt und an die Post übergeben
Bei der Verarbeitung des Serienbriefes trat ein Fehler auf
Um einen einzelnen Eintrag der Serienbrief Historie abzurufen, muss folgende URL
https://poststelle.deltra.de/messaging/mailmerge
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
account
password
mandant
session
Beschreibung
Benutzername
Passwort
Mandant
Eindeutige Id des Serienbriefes
Hinweis
Der Standard ist ‚orgaMAX’
Aus der Historie oder als Rückgabe des Versandes
Pflicht
ja
ja
ja
ja
Die Rückgabe des Eintrags in der Serienbrief Historie erfolgt in Form eines XML Dokumentes. Das XML Schema kann unter
folgender URL bezogen werden:
https://poststelle.deltra.de/docs/mailmerge_history.dtd
Um die zur Erzeugung eines Serienbriefes genutzten Dokumente (Vorlage, CSV) zu beziehen, muss folgende URL
https://poststelle.deltra.de/messaging/mailmerge/documents
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
account
password
mandant
session
Beschreibung
Benutzername
Passwort
Mandant
Eindeutige Id des Serienbriefes
Hinweis
Der Standard ist ‚orgaMAX’
Aus der Historie oder als Rückgabe des Versandes
Pflicht
ja
ja
ja
ja
Die Rückgabe der Dokumente erfolgt in Form eines XML Dokumentes. Das XML Schema kann unter folgender URL bezogen
werden:
https://poststelle.deltra.de/docs/mailmerge_documents.dtd
IO Factory Ltd. • Flughafenstraße 52a (Haus C) Airport Center • 22335 Hamburg
Tel. +49 40 532 99 271 • Fax +49 40 532 99 100 • E-Mail [email protected] • Web http://www.iofactory.de
IO Factory – Brief – HTTP Schnittstelle - V3.0 Release 3
Um die einzelnen Einträge eines Serienbriefes zu beziehen, muss folgende URL
https://poststelle.deltra.de/messaging/mailmerge/entries
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
account
password
mandant
session
Beschreibung
Benutzername
Passwort
Mandant
Eindeutige Id des Serienbriefes
Hinweis
Der Standard ist ‚orgaMAX’
Aus der Historie oder als Rückgabe des Versandes
Pflicht
ja
ja
ja
ja
Die Rückgabe der Einträge erfolgt in Form eines XML Dokumentes. Das XML Schema kann unter folgender URL bezogen
werden:
https://poststelle.deltra.de/docs/mailmerge_entries.dtd
Der Status eines einzelnen Eintrags eines Serienbriefes wird im Feld MailMergeEntryStatusTypeId dokumentiert. Mögliche
Werte hierbei sind:
1:
2:
3:
4:
5:
Der Brief wurde erzeugt und gespeichert
Der Brief wurde in den Druck gegeben
Der Brief wurde erfolgreich gedruckt und an die Post übergeben
Beim Versandt des Briefes trat ein Fehler auf
Der Brief wurde im Testmodus verarbeitet
Um einen einzelnen Eintrag eines Serienbriefes zu beziehen, muss folgende URL
https://poststelle.deltra.de/messaging/mailmerge/entry
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
Beschreibung
Hinweis
Pflicht
account
Benutzername
ja
password
Passwort
ja
mandant
Mandant
Der Standard ist ‚orgaMAX’
ja
session
Eindeutige Id des Eintrages
Aus der Historie
ja
Die Rückgabe des Eintrags erfolgt in Form eines XML Dokumentes. Das XML Schema kann unter folgender URL bezogen
werden:
https://poststelle.deltra.de/docs/mailmerge_entries.dtd
Um das erzeugte Dokument eines einzelnen Eintrags eines Serienbriefes zu beziehen, muss folgende URL
https://poststelle.deltra.de/messaging/mailmerge/entry/document
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
Beschreibung
Hinweis
account
Benutzername
password
Passwort
mandant
Mandant
Der Standard ist ‚orgaMAX’
session
Eindeutige Id des Eintrags
Aus der Historie
Die Rückgabe der Eintrags erfolgt in Form einer PDF Datei.
Pflicht
ja
ja
ja
ja
Um das erzeugte Dokument eines einzelnen Eintrags eines Serienbriefes als Vorschaubild zu beziehen, muss folgende URL
https://poststelle.deltra.de/messaging/mailmerge/entry/thumbnail
mit den im folgenden beschriebenen Parametern mittels eines multipart/form-data kodierten HTTP POST aufgerufen
werden.
Feld
account
password
mandant
session
height
width
Beschreibung
Benutzername
Passwort
Mandant
Eindeutige Id des Eintrags
Höhe in Pixel
Breite in Pixel
Hinweis
Der Standard ist ‚orgaMAX’
Aus der Historie
Pflicht
ja
ja
ja
ja
ja
ja
Die Rückgabe erfolgt in Form eines PNG Bildes in der angeforderten Größe.
IO Factory Ltd. • Flughafenstraße 52a (Haus C) Airport Center • 22335 Hamburg
Tel. +49 40 532 99 271 • Fax +49 40 532 99 100 • E-Mail [email protected] • Web http://www.iofactory.de
IO Factory – Brief – HTTP Schnittstelle - V3.0 Release 3
HTTP Schnittstelle - Rückgabewerte
Die HTTP Schnittstelle gibt bei Aufruf folgende Rückgabewerte zurück.
Code
0
10
30
70
100
200
220
999
Fehlerbeschreibung
OK
Keine Nutzerrechte
Parameter fehlt
Objekt wurde nicht gefunden
Parameter ist von einem ungültigem Typ
Nicht unterstütze Anforderung
Kontingent aufgebraucht
Interner Fehler
Das Format der Rückgabe ist wie folgt:
Code : Fehlerbeschreibung : optionale Parameter
IO Factory Ltd. • Flughafenstraße 52a (Haus C) Airport Center • 22335 Hamburg
Tel. +49 40 532 99 271 • Fax +49 40 532 99 100 • E-Mail [email protected] • Web http://www.iofactory.de