ePost (Digitaler Brief)

Die ePost Service AG, eine Tochtergesellschaft der Schweizerischen Post, betreibt die ePost Communication Platform. Über deren öffentliche API wird ein Dokument einmal digital eingeliefert. ePost entscheidet danach pro Empfänger, ob digital in den ePost Digital Letterbox, per E-Mail, SMS, eBill oder physisch als gedruckter Brief zugestellt wird. Ein in primedocs generiertes Dokument lässt sich über das Output Management direkt an diese Schnittstelle übergeben.

Kundenspezifische Konfiguration

Die Anbindung ist eine Vorlagen-Konfiguration. Sie setzt einen Vertrag mit ePost und eine freigeschaltete Ziel-URL voraus.

Funktionsprinzip

1. Die Vorlage wird in primedocs wie gewohnt generiert.
2. Ein Output der Vorlage konvertiert das Dokument nach PDF und sendet es zusammen mit den Empfänger- und Sendungsmetadaten an die ePost-API.
3. ePost führt das Identity Matching durch: Anhand der übergebenen Empfängermerkmale (Adresse, E-Mail, Mobilnummer) wird geprüft, ob die empfangende Person oder Firma einen ePost Digital Letterbox besitzt.
4. Abhängig vom Treffer und den gewünschten Kanälen stellt ePost digital zu oder übergibt die Sendung an einen Druckdienstleister für den physischen Versand.

Zustellkanäle

Ein einziger API-Aufruf bedient alle Kanäle. Welche zulässig sind, steuert das Metadatenfeld deliveryChannelPreferences.

Kanal	Wert	Bemerkung
ePost Digital Letterbox	DIGITAL	Digitale Zustellung in die ePost App bzw. Web App.
E-Mail	EMAIL	Versand über eine ePost-Absenderdomäne.
SMS	SMS	Kurznachricht, nur für reine Textmeldungen ohne PDF.
eBill	EBILL	Rechnungen im E-Banking. Erfordert PDF/A-3 und zusätzliche Metadaten.
Physischer Brief	PHYSICAL	Druck und Versand über einen Druckpartner von ePost.
Automatische Triage	AUTO	ePost wählt den günstigsten verfügbaren Kanal.

tipp

AUTO bevorzugen

ePost empfiehlt AUTO statt einer expliziten Kanalliste. Damit greift die Triage-Logik der Plattform: digital, wenn der Empfänger erreichbar ist, sonst der nächstbeste Kanal.

Die ePost-Schnittstelle

Verbindliche Referenz für Endpunkte, Metadatenfelder und Umgebungen ist die ePost Developer Zone. Für die Konfiguration in primedocs sind nur die folgenden Eckpunkte relevant.

Authentifizierung. Die API verwendet OAuth 2.0 mit dem Resource-Owner-Password-Grant: Benutzername, Passwort, tenant_id und company_id eines technischen Kontos werden am Token-Endpunkt (POST /core/latest/token, application/x-www-form-urlencoded) gegen ein access_token getauscht. Das Token ist zehn Minuten gültig und wird deshalb unmittelbar vor jedem Versand neu geholt statt zwischengespeichert.

Einlieferung. Das Dokument geht als multipart/form-data an POST /epost/v2/synchronous-deliveries. Der Request besteht aus zwei Arten von Parts:

Part	Inhalt
metadata	JSON mit einem Array fileMetadata (ein Eintrag pro Datei).
files	Die PDF-Datei. Der Part heisst auch bei einer einzelnen Datei files (Plural) und kann mehrfach vorkommen.

Die Zuordnung zwischen Metadaten und Dateien erfolgt über fileName: Der Wert muss exakt dem Dateinamen des zugehörigen files-Parts entsprechen.

Anforderungen an die Vorlage

Damit die Sendung verarbeitet werden kann, muss das erzeugte PDF diese Vorgaben erfüllen (sie betreffen das Layout der Vorlage, nicht die Konfiguration):

Anforderung	Details
Seitenformat	Für den physischen Versand alle Seiten in A4 Hochformat. Querformat oder abweichende Formate werden nicht verarbeitet.
Adressposition	Die Empfängeradresse muss an der von ePost vorgegebenen Position stehen. Alternativ lässt sich ein Deckblatt vorschalten.
Adressgleichheit	Die Adresse im PDF muss mit der Adresse in den Metadaten identisch sein, sonst drohen Zustellprobleme oder falsche Frankierung.

Anbindung aus primedocs

Die Einlieferung wird als InvokeUrl-Command im Output Management der Vorlage konfiguriert: Schritt 1 holt das Access-Token, Schritt 2 sendet Metadaten und Dokument als multipart/form-data.

Voraussetzung: Ziel-URL freischalten

InvokeUrl ruft nur freigegebene Adressen auf. In der DataSourceAdminApp unter Connect Settings → InvokeUrl - Configuration die Basis-URL eintragen:

<CommandConfig>
  <Url startsWith="https://api.epost.ch" />
</CommandConfig>

Ohne diesen Eintrag bricht der Command ab.

Output konfigurieren

Dateiname und Metadaten werden in Feldern des Outputs zusammengesetzt. Die <Fields> stehen dabei innerhalb des <DesktopOutput> und nicht in einer eigenen Konfiguration. Lokal deklarierte Felder werden mit blossem Namen angesprochen ($("EPostFileName"), field-Value="EPostMetadata"), globale Felder mit ihrem Präfix (Forms.…, Data.…).

JSON.stringify übernimmt beim Zusammenbauen der Metadaten die korrekte Maskierung. Das ist wichtig, weil Empfängernamen und Adressen Anführungszeichen, Umlaute oder Backslashes enthalten können.

<OutputConfiguration>
  <DesktopOutput Name="Als Digitaler Brief senden"
                 Tooltip="Liefert das Dokument bei ePost ein">

    <Fields>
      <!-- Eindeutiger Dateiname pro Ausführung -->
      <Text Name="EPostFileName">
        <Code><![CDATA[
          function main() {
            return "Brief_" + $.util.generateGuid() + ".pdf";
          }
        ]]></Code>
      </Text>

      <Text Name="EPostMetadata">
        <Code><![CDATA[
          function main() {
            const empfaenger = $("Forms.Empfaenger");
            return JSON.stringify({
              costCenter: "Kundenkorrespondenz",
              fileMetadata: [{
                fileName: $("EPostFileName"),
                documentTitle: $("Forms.Betreff"),
                documentTypes: ["message"],
                documentReferenceDate: new Date().toISOString().substring(0, 10),
                senderName: "Beispiel AG",
                deliveryChannelPreferences: ["AUTO"],
                allCredentialShouldMatch: false,
                senderCaseId: $("Forms.Geschaeftsnummer"),
                recipients: [{
                  senderUserId: empfaenger.KundenNr,
                  unhashedCredentials: {
                    minimumLevelOfTrust: "BRONZE",
                    firstName: empfaenger.Vorname,
                    lastName: empfaenger.Nachname,
                    street: empfaenger.Strasse,
                    streetNumber: empfaenger.Hausnummer,
                    zipCode: empfaenger.Plz,
                    city: empfaenger.Ort,
                    email: empfaenger.Email
                  }
                }]
              }]
            });
          }
        ]]></Code>
      </Text>
    </Fields>

    <Commands>
      <InvokeUrl>
        <!-- Schritt 1: Access-Token holen (Gültigkeit 10 Minuten) -->
        <Step>
          <Request Method="Post">
            <Url>https://api.epost.ch/core/latest/token</Url>
            <Header Name="Content-Type" Value="application/x-www-form-urlencoded" />
            <Body>grant_type=password&amp;username=TECHNISCHES_KONTO&amp;password=PASSWORT&amp;tenant_id=TENANT_ID&amp;company_id=COMPANY_ID</Body>
          </Request>
          <Response>
            <Property Name="AccessToken" JsonPath="$.access_token" />
          </Response>
        </Step>

        <!-- Schritt 2: Dokument und Metadaten einliefern -->
        <Step>
          <MultipartFormDataRequest>
            <Url>https://api.epost.ch/epost/v2/synchronous-deliveries</Url>
            <Header Name="Authorization" Value="Bearer {AccessToken}" />
            <FormData Name="metadata" field-Value="EPostMetadata" />
            <File Name="files"
                  field-FileName="EPostFileName"
                  ContentType="application/pdf">
              <Document Conversion="Pdf" />
            </File>
          </MultipartFormDataRequest>
        </Step>
      </InvokeUrl>
    </Commands>
  </DesktopOutput>
</OutputConfiguration>

Die wichtigsten Punkte der Konfiguration:

Element	Hinweis
<Fields> in <DesktopOutput>	Die Felder des Outputs stehen im Output selbst. Referenziert werden sie ohne Präfix.
<FormData Name="metadata" …>	Der Part heisst metadata. fileMetadata ist nur der Schlüssel innerhalb des JSON, nicht der Formularfeldname.
<File Name="files" …>	Der Datei-Part heisst files (Plural), auch bei einer einzelnen Datei.
field-FileName	Verweist auf dasselbe Feld wie fileName im JSON, damit beide Werte übereinstimmen.
<Document Conversion="Pdf" />	Erzwingt die PDF-Konvertierung der Word-Vorlage. Erzeugt die Vorlage bereits ein PDF, entfällt das Attribut.
{AccessToken}	Wert aus der Response von Schritt 1.

Feldnamen

Die Namen unter Forms.… und die Eigenschaften des Empfängerobjekts hängen von der Datenquelle ab und werden pro Anwendungsfall festgelegt.

Einsatz in Web und über die API

Derselbe InvokeUrl-Block funktioniert unverändert in einem WebOutput für primedocs Web und die Office Web Add-Ins sowie in einem OnSuccess-Block der Connect/Document API für die serverseitige Generierung. InvokeUrl gehört zu den Commands, die in allen drei Kontexten verfügbar sind.

Grenzen

Zugangsdaten im Klartext

ePost verwendet den Resource-Owner-Password-Grant mit einem technischen Konto. Die Connected Services von primedocs unterstützen ausschliesslich den Authorization-Code-Flow mit interaktiver Anmeldung pro Benutzer und kommen dafür nicht in Frage. Benutzername und Passwort stehen deshalb im Klartext in der Vorlagenkonfiguration.

Zugangsdaten im Klartext

Für den produktiven Einsatz ein dediziertes technisches Konto mit minimalen Rechten verwenden, das Passwort regelmässig rotieren und den Zugriff auf die Vorlagenkonfiguration entsprechend einschränken.

PDF/A-3 für eBill

Die PDF-Konvertierung von primedocs erzeugt PDF/A-1B, sowohl serverseitig als auch über Word (Conversion="PdfViaOffice"). Damit ist die PDF/A-Anforderung von ePost für alle Kanäle ausser eBill erfüllt. Der eBill-Kanal verlangt PDF/A-3, wofür die Konvertierung nicht ausreicht.

Onboarding bei ePost

Zugang, Umgebungen und Basis-URLs werden mit ePost vereinbart (support.enterprise@epostservice.ch). Für den physischen Kanal werden Adressposition und Druckprofil gemeinsam mit ePost getestet, bevor produktiv eingeliefert wird.

Weiterführende Links

• ePost Developer Zone: API-Referenz, Metadaten und Beispiele
• Der Digitale Brief: Leistungsumfang und Preise
• Ausgabeverwaltung (Output Management): Outputs in Vorlagen
• Nach der Dokumentgenerierung (Commands): Referenz zu InvokeUrl