MOXIS API Dokumentation
German English

Integrationsmuster der MOXIS REST API: Auswahl und Vergleich von Simple, Webhook, Polling und Middleware

Inhalt

Dieser Abschnitt beschreibt die vier von der MOXIS REST API unterstützten Integrationsmuster. Jedes Muster deckt einen anderen operativen Kontext ab; vom schnellen Prototyping bis zu produktionsreifen, ereignisgesteuerten Architekturen. Wählen Sie das Integrationsmuster, das zu Ihrer Infrastruktur und Ihren Volumenanforderungen passt.


1. Vergleich der Integrationsmuster

Muster

MOXIS Version

Echtzeit?

Komplexität

Geeignet für

Simple

Beliebig

Nein

Niedrig

Prototyping, manuelle Workflows

Webhook

Enterprise Cloud

Ja

Mittel

Produktive, ereignisgesteuerte Integrationen

Polling

Beliebig

Nahezu Echtzeit

Mittel

Produktion ohne Webhooks

Middleware

Beliebig

Abhängig

Hoch

Gemeinsam genutzte Infrastruktur für mehrere Anwendungen

MOXIS Tipp
Enterprise Cloud beinhaltet Webhook-Unterstützung. Business Cloud beinhaltet keine Webhooks, verwenden Sie für diese MOXIS Version das Polling-Muster.

1.1. Auswahl eines Musters

1.1.1. Erstellen eines einfachen Auftrags

Verwenden Sie dieses Integrationsmuster, wenn Sie gerade erst beginnen, einen Proof of Concept erstellen oder Workflows mit geringem Volumen betreiben, bei denen bereits ein Mensch in den Prozess eingebunden ist. Sie benötigen dafür auf Ihrer Seite keine Event-Infrastruktur. Der Nachteil ist, dass Ihre Anwendung den Abschluss aktiv abfragen muss, statt benachrichtigt zu werden. Zudem sind Sie auf die Interaktion der Benutzer mit der MOXIS-Benutzeroberfläche angewiesen.

Siehe Erstellen eines einfachen Auftrags.

1.1.2.Webhook-Integration

Verwenden Sie dieses Integrationsmuster für produktive Integrationen auf Enterprise Cloud, bei denen MOXIS Events aktiv an Ihr System senden soll, sobald sie auftreten. Ihre Anwendung registriert einen HTTPS-Endpunkt, und MOXIS liefert einen Payload, sobald ein Job einen Trigger-Status erreicht. Dies macht Polling vollständig überflüssig und minimiert die Latenz zwischen Signaturabschluss und nachgelagerter Verarbeitung.

Siehe Webhook-Integration.

1.1.3. Polling-Integrationsmuster

Verwenden Sie dieses Integrationsmuster, wenn Webhooks nicht verfügbar sind (zum Beispiel in der MOXIS Business Cloud) oder wenn Ihr Endpunkt von MOXIS aus nicht erreichbar ist (z. B. hinter einer Firewall oder in einer Entwicklungsumgebung). Ein zeitgesteuerter Job fragt MOXIS in regelmäßigen Abständen nach abgeschlossenen Aufträgen ab. Bei sorgfältiger Nutzung des Filters jobFinishedAfter sowie der Paginierung skaliert dieses Muster gut und vermeidet eine erneute Verarbeitung bereits behandelter Jobs.

Siehe Polling-Integration.

1.1.4. Middleware-Integrationsmuster

Verwenden Sie dieses Integrationsmuster, wenn mehrere interne Anwendungen mit MOXIS interagieren müssen und Sie eine einzige, zentral verwaltete Integrationsschicht wünschen. Die Middleware verwaltet die Zugangsdaten, übernimmt Wiederholungsversuche, übersetzt Events aus Webhooks oder Polling und stellt den aufrufenden Anwendungen eine vereinfachte interne API bereit. Dies ist die Option mit der höchsten Komplexität, aber die am besten wartbare bei größerem Maßstab.

Siehe Middleware-Integration.

1.2. Weiterführende Referenzen

  • API-Referenz: Vollständige Methodendokumentation

  • Schnellstartanleitung: Anleitung für den ersten API-Aufruf

  • Authentifizierung: Zugangsdaten und OAuth-Einrichtung

  • Datenmodell der Job-Beschreibung: JSON-Referenz für jobDescription

2. Erstellen eines einfachen Auftrags

Der einfachste Weg, die MOXIS API zu nutzen, besteht darin, ein Dokument hochzuladen, einen Job zu starten und später das signierte Ergebnis abzurufen. Auf Ihrer Seite ist keine Event-Infrastruktur erforderlich. Die Erkennung des Abschlusses erfolgt durch Abfragen des Status eines einzelnen Jobs (Polling) oder durch Abwarten einer Bestätigung des Benutzers außerhalb der API.

2.1. Wann dieses Integrationsmuster verwendet werden sollte

  • Prototyping oder erste Evaluierung der API

  • Workflows mit geringem Volumen, bei denen bereits ein Mensch am Prozess beteiligt ist

  • Szenarien, in denen sich der Benutzer in der MOXIS-Benutzeroberfläche anmeldet, um Dokumente manuell zu signieren und abzurufen

  • Umgebungen, in denen die Einrichtung eines Webhook-Endpunkts oder eines Schedulers noch nicht möglich ist

Das Integrationsmuster ist nicht geeignet für:

  • automatisierte Pipelines,

  • Verarbeitung mit hohem Volumen oder Fälle, in denen eine zeitnahe Benachrichtigung über den Abschluss erforderlich ist.

2.2. Funktionsweise

  1. Ihre Anwendung ruft POST startProcess auf, um einen Signaturjob in MOXIS zu erstellen.

  1. MOXIS sendet eine E-Mail-Benachrichtigung an den/die konfigurierten Signierenden.

  1. Der Signierende öffnet MOXIS, prüft das Dokument und bringt seine Signatur an.

  1. Ihre Anwendung ruft regelmäßig GET getJobState auf, um zu prüfen, ob der Job abgeschlossen ist.

  1. Sobald der Status FINISHED_SUCCESS lautet, ruft Ihre Anwendung GET getDocument auf, um das signierte PDF abzurufen.

2.3. Sequenzdiagramm

image-20260819-084942.png

sequenceDiagram
    participant App as Your App
    participant API as MOXIS API
    participant UI as MOXIS UI
    participant Signer as Signer

    App->>API: POST /startProcess/{processId}
    API-->>App: 201 Created — processInstanceId
    API->>Signer: Email notification

    Signer->>UI: Opens MOXIS, reviews document
    Signer->>UI: Applies signature

    loop Until FINISHED_SUCCESS
        App->>API: GET /getJobState/{processInstanceId}
        API-->>App: JSON — state, endDate
    end

    App->>API: GET /getDocument/{processInstanceId}
    API-->>App: Signed PDF (blob)

2.4. Schritt-für-Schritt-Anleitung

2.4.1. Schritt 1: Job erstellen

Senden Sie eine multipart/form-data-POST-Anfrage mit Ihrem PDF und einem jobDescription-JSON-Body.

POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/{processId}
Authorization: Basic <base64(user:password)>
Content-Type: multipart/form-data

jobDescription (JSON-Teil):

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@example.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Contract review Q2 2026",
    "referenceId": "CONTRACT-00123"
  },
  "positionType": "INVISIBLE",
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.User",
          "classifier": "EMAIL",
          "name": "signer@example.com",
          "roleName": "moxisSigner"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0
    }
  ]
}

Antwort:

HTTP 201 Created
Body: "450123"   ← processInstanceId (speichern Sie diesen Wert)

Speichern Sie die processInstanceId. Sie benötigen diese für alle nachfolgenden Aufrufe zu diesem Job.

2.4.2. Schritt 2: Signierender erhält Benachrichtigung und signiert

MOXIS sendet automatisch eine E-Mail an den/die Signierenden. Der Signer meldet sich in der MOXIS-Benutzeroberfläche an, öffnet den Job und schließt die Signatur ab. In dieser Phase ist von Ihrer Anwendung keine Aktion erforderlich.

2.4.3. Schritt 3: Auf Jobabschluss pollen

Rufen Sie GET getJobState mit der processInstanceId auf, um den aktuellen Status zu prüfen.

GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/{processInstanceId}/{nameClassifier}
Authorization: Basic <base64(user:password)>

Ersetzen Sie {nameClassifier} durch die E-Mail-Adresse oder den UPN des Constituent (Job-Eigentümer).

2.4.4. Beispielantwort (Job noch aktiv):

{
  "state": "ACTIVE",
  "processInstanceId": 450123,
  "endDate": null
}

2.4.5. Beispielantwort (Job abgeschlossen):

{
  "state": "FINISHED_SUCCESS",
  "processInstanceId": 450123,
  "endDate": "2026-04-23T14:30:00Z"
}

Ein Job ist abgeschlossen, wenn beide Bedingungen erfüllt sind: - state ist FINISHED_SUCCESS - endDate ist nicht null

2.4.6. Schritt 4: Signiertes Dokument abrufen

Sobald sich der Job im Status FINISHED_SUCCESS befindet, laden Sie das signierte PDF herunter.

GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/{processInstanceId}
Authorization: Basic <base64(user:password)>

Der Response-Body ist die signierte PDF-Datei (binäres Blob). Speichern Sie diese in Ihrem Speicher.

2.5. Referenz der Job-Status

Status

Beschreibung

DRAFTING

Job ist ein Entwurf, noch nicht gestartet

ACTIVE

Job läuft, wartet auf Signatur(en)

POST_PROCESSING

Signatur abgeschlossen, MOXIS verarbeitet das Ergebnis

FINISHED_SUCCESS

Erfolgreich signiert — Dokument ist bereit

FINISHED_FAILED

Signatur fehlgeschlagen

FINISHED_TIMEOUT

Job vor Abschluss abgelaufen

FINISHED_WF_CANCELLED

Workflow wurde abgebrochen

FINISHED_SIGNATURE_DENIED

Ein Signer hat das Dokument abgelehnt

DRAFT_DISMISSED

Entwurf wurde vor dem Start verworfen

2.6. Einschränkungen

  • Dieses Muster setzt voraus, dass sich Benutzer aktiv bei MOXIS anmelden, um zu signieren. Es gibt keinen Push-Mechanismus zu Ihrer Anwendung, wenn die Signatur erfolgt.

  • Temporäre Objekte (Entwürfe) unterliegen zeitlichen Beschränkungen. Sie werden nach Ablauf ihres Verfallsdatums automatisch gelöscht.

  • Nicht geeignet für automatisierte, unbeaufsichtigte Pipelines. Ziehen Sie für diese Fälle die Muster Webhook oder Polling in Betracht.

  • Wenn Sie die processInstanceId bei der Erstellung nicht speichern und den Job später finden müssen, verwenden Sie GET lookupJobStates mit den entsprechenden Filtern. Details zu Bulk-Abfragen finden Sie im Polling-Muster.

2.7. Weiterführende Referenzen

  • POST startProcess Vollständige Parameterreferenz

  • GET getJobState: Antwortmodell und Statuswerte

  • GET getDocument: Dokumentabruf

  • Datenmodell der Job-Beschreibung: JSON-Referenz für jobDescription

3. Polling-Integrationsmuster

Das Polling-Integrationsmuster verwendet den Bulk-Abfrage-Endpunkt GET lookupJobStates, um periodisch alle Jobs abzurufen, die innerhalb eines Zeitfensters einen gewünschten Status erreicht haben. Dies macht einen Webhook-Endpunkt überflüssig und ermöglicht Ihrer Anwendung trotzdem, ohne manuelles Eingreifen auf abgeschlossene Signaturen zu reagieren.

3.1. Wann dieses Integrationsmuster verwendet werden sollte

  • Sie verfügen über MOXIS Business Cloud, welche keine Webhooks beinhaltet

  • Ihr Anwendungsendpunkt ist von MOXIS aus nicht erreichbar (z. B. hinter einer Firewall, im internen Netzwerk oder in einer Entwicklungsumgebung)

  • Sie bevorzugen aus Sicherheits- oder architektonischen Gründen ein Pull-basiertes Modell gegenüber einem eingehenden Endpunkt

  • Eine nahezu Echtzeit-Benachrichtigung ist akzeptabel (der Abschluss wird im nächsten Polling-Zyklus erkannt)

3.2. Funktionsweise

  1. Ihre Anwendung erstellt einen Job mit POST startProcess und speichert die zurückgegebene processInstanceId (und optional eine eigene referenceId).

  1. Ein zeitgesteuerter Job läuft in regelmäßigen Abständen und ruft GET lookupJobStates gefiltert nach FINISHED_SUCCESS und einem relevanten Zeitfenster auf.

  1. Für jeden zurückgegebenen abgeschlossenen Job ruft Ihre Anwendung GET getDocument auf, um das signierte PDF abzurufen.

  1. Der Zeitstempel der letzten Verarbeitung wird aktualisiert, um eine erneute Verarbeitung von Jobs im nächsten Durchlauf zu vermeiden.

3.3. Sequenzdiagramm

image-20260819-084750.png

sequenceDiagram
    participant App as Your App
    participant Store as Your Data Store
    participant Scheduler as Scheduler
    participant API as MOXIS API

    App->>API: POST /startProcess/{processId}
    API-->>App: 201 Created — processInstanceId
    App->>Store: Save processInstanceId + lastPolledAt

    loop Every polling interval
        Scheduler->>API: GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...&jobFinishedBefore=...
        API-->>Scheduler: JSON array of completed jobs

        loop For each completed job
            Scheduler->>API: GET /getDocument/{processInstanceId}
            API-->>Scheduler: Signed PDF (blob)
            Scheduler->>Store: Save document, update lastPolledAt
        end
    end

3.4. Schritt-für-Schritt-Anleitung

3.4.1. Schritt 1: Job erstellen und ID speichern

POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/{processId}
Authorization: Basic <base64(user:password)>
Content-Type: multipart/form-data

Der Response-Body ist die processInstanceId als reiner String (HTTP 201). Speichern Sie diesen Wert dauerhaft zusammen mit internen Kennungen. Wenn Sie eine referenceId in metaData übergeben, können Sie den Job später auch mit GET lookupJobStates?referenceId=... auffinden.

3.4.2. Schritt 2: Abgeschlossene Jobs abfragen

Verwenden Sie GET lookupJobStates mit einem Zeitfenster, um alle Jobs zu finden, die in einem bestimmten Zeitraum abgeschlossen wurden.

GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=2026-04-23T00:00:00&jobFinishedBefore=2026-04-23T23:59:59
Authorization: Basic <base64(user:password)>

Wichtige Abfrageparameter:

Parameter

Typ

Beschreibung

lookupStates

string

Kommagetrennte Liste von Statuswerten zur Filterung, z. B. FINISHED_SUCCESS oder FINISHED_SUCCESS,FINISHED_FAILED

jobFinishedAfter

string

ISO 8601 — liefert Jobs, die nach diesem Zeitstempel abgeschlossen wurden

jobFinishedBefore

string

ISO 8601 — liefert Jobs, die vor diesem Zeitstempel abgeschlossen wurden

processIds

string

Filterung auf eine bestimmte Prozessvorlagen-ID

referenceId

string

Filterung nach Ihrer eigenen Referenz-ID (MOXIS v4.52+)

offset

integer

Paginierungs-Offset — Beginn des Ergebnisblocks (inklusiv)

pageSize

integer

Anzahl der Ergebnisse pro Seite (Standard: 50)

3.4.3. Beispielantwort:

[
  { "processInstanceId": "450123", "state": "FINISHED_SUCCESS" },
  { "processInstanceId": "450124", "state": "FINISHED_SUCCESS" }
]

lookupJobStates liefert nur processInstanceId und state. Für vollständige Job-Details rufen Sie GET getJobState für einzelne IDs auf.

3.4.4. Schritt 3: Paginierung behandeln

Die Standardseitengröße beträgt 50 Ergebnisse. Wenn Sie mehr abgeschlossene Jobs als das in einem einzelnen Zeitfenster erwarten, iterieren Sie mithilfe von offset und pageSize.

# First page (results 0–49)
GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...&offset=0&pageSize=50
# Second page (results 50–99)
GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...&offset=50&pageSize=50

Fordern Sie weiterhin Seiten an, bis das zurückgegebene Array kleiner als Ihre pageSize ist — das kennzeichnet die letzte Seite.

Um vor der Paginierung eine Gesamtanzahl zu ermitteln, verwenden Sie GET countLookupJobStates mit denselben Parametern:

GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/countLookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...

Liefert eine einzelne Ganzzahl mit der Gesamtzahl der übereinstimmenden Datensätze.

3.4.5. Schritt 4: Jedes signierte Dokument abrufen

Für jede processInstanceId in den Ergebnissen:

GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/{processInstanceId}
Authorization: Basic <base64(user:password)>

Der Response-Body ist das signierte PDF als binäres Blob. Speichern Sie es in Ihrem Dokumentenspeicher.

3.4.6. Schritt 5: Zeitfenster verschieben

Aktualisieren Sie nach jedem Polling-Durchlauf Ihren gespeicherten lastPolledAt-Zeitstempel auf die aktuelle Zeit (oder auf den in diesem Durchlauf verwendeten Wert von jobFinishedBefore). Verwenden Sie diesen Wert im nächsten Durchlauf als jobFinishedAfter.

3.4.7. Beispiel Verschieben des Zeitfensters:

First run:  jobFinishedAfter=2026-04-23T00:00:00  jobFinishedBefore=2026-04-23T01:00:00
Second run: jobFinishedAfter=2026-04-23T01:00:00  jobFinishedBefore=2026-04-23T02:00:00

Dies verhindert, dass dieselben abgeschlossenen Jobs über mehrere Polling-Zyklen hinweg erneut verarbeitet werden.

3.5. Polling für einen bestimmten, bekannten Job

Wenn Sie die processInstanceId bei der Erstellung gespeichert haben und nur einen bestimmten Job prüfen müssen, verwenden Sie direkt GET getJobState:

GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/{processInstanceId}/{nameClassifier}
Authorization: Basic <base64(user:password)>

Dies liefert das vollständige Job-Status-Objekt. Prüfen Sie, ob state == "FINISHED_SUCCESS" und endDate != null sind, bevor Sie das Dokument herunterladen.

Falls Sie bei der Erstellung eine referenceId zugewiesen haben, verwenden Sie alternativ GET getJobStateByReferenceId:

GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobStateByReferenceId/{referenceId}/{nameClassifier}

3.6. Empfehlungen zur Polling-Häufigkeit

  • Mindestintervall:
    Einmal pro Minute ist eine angemessene untere Grenze, um die API nicht zu überlasten und Abschlüsse trotzdem zeitnah zu erkennen.

  • An Ihre SLA anpassen:
    Wenn Ihr Prozess erfordert, dass der Abschluss innerhalb von 5 Minuten verarbeitet wird, pollen Sie alle 1–2 Minuten mit einem entsprechenden Zeitfenster.

  • Überlappende Durchläufe vermeiden:
    Stellen Sie sicher, dass jeder geplante Durchlauf abgeschlossen ist, bevor der nächste beginnt (insbesondere bei der Paginierung großer Ergebnismengen).

  • Enge Zeitfenster verwenden:
    Die Abfrage eines 1-Stunden-Fensters alle 5 Minuten ist effizienter als die Abfrage unbegrenzter Ergebnisse.

3.7. Job-Status

Status

Terminal?

Beschreibung

DRAFTING

Nein

Job ist ein Entwurf

ACTIVE

Nein

Läuft, wartet auf Signatur(en)

POST_PROCESSING

Nein

Signatur abgeschlossen, Nachbearbeitung läuft

FINISHED_SUCCESS

Ja

Alle Signaturen erfolgreich eingeholt

FINISHED_FAILED

Ja

Signatur fehlgeschlagen

FINISHED_TIMEOUT

Ja

Job abgelaufen

FINISHED_WF_CANCELLED

Ja

Workflow abgebrochen

FINISHED_SIGNATURE_DENIED

Ja

Signer hat das Dokument abgelehnt

DRAFT_DISMISSED

Ja

Entwurf verworfen

3.8. Beispiel: vollständiger Polling-Zyklus

# 1. Count completed jobs in window to determine pagination needs
GET /countLookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=2026-04-23T13:00:00&jobFinishedBefore=2026-04-23T14:00:00
→ 3

# 2. Retrieve all completed jobs (3 < 50, no pagination needed)
GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=2026-04-23T13:00:00&jobFinishedBefore=2026-04-23T14:00:00
→ [
    { "processInstanceId": "450123", "state": "FINISHED_SUCCESS" },
    { "processInstanceId": "450124", "state": "FINISHED_SUCCESS" },
    { "processInstanceId": "450125", "state": "FINISHED_SUCCESS" }
  ]

# 3. Download each document
GET /getDocument/450123  →  contract-a.pdf
GET /getDocument/450124  →  contract-b.pdf
GET /getDocument/450125  →  contract-c.pdf

# 4. Store documents, advance lastPolledAt to 2026-04-23T14:00:00

3.9. Weiterführende Referenzen

  • GET lookupJobStates: Vollständige Parameterreferenz und Antwortmodell

  • GET countLookupJobStates: Anzahl vor der Paginierung ermitteln

  • GET getJobState: Detaillierter Status für einen einzelnen Job

  • GET getDocument: Signiertes Dokument abrufen

  • POST createJob: Jobs mit referenceId erstellen

4. Webhook-Integration

MOXIS kann Job-Status-Events an einen von Ihnen kontrollierten HTTPS-Endpunkt senden. Sobald ein Job einen konfigurierten Trigger-Status erreicht, sendet MOXIS eine HTTP-POST-Anfrage an Ihren Endpunkt mit einem JSON-Payload, das den vollständigen Job-Status enthält. Ihre Anwendung reagiert dann auf das Event (üblicherweise durch Aufruf von GET getDocument, um die signierte Datei abzurufen).

4.1. Wann dieses Muster verwendet werden sollte

  • Sie verfügen über MOXIS Enterprise Cloud (Webhooks sind bei Business Cloud nicht verfügbar)

  • Sie möchten Signaturereignisse in Echtzeit benachrichtigt bekommen, ohne zu pollen

  • Ihre Anwendung verfügt über einen öffentlich erreichbaren HTTPS-Endpunkt

  • Sie erstellen eine produktive, ereignisgesteuerte Integration

4.2. Voraussetzungen

  • Ein von MOXIS aus erreichbarer HTTPS-Endpunkt mit einem gültigen SSL-Zertifikat

  • Ein MOXIS-Administrator, der den Webhook pro Prozess in der MOXIS-Administrationsoberfläche konfigurieren kann

  • Zugangsdaten für Ihren Endpunkt (Basic Auth oder OAuth Client Credentials) oder eine bewusste Entscheidung, eine unauthentifizierte Zustellung zu akzeptieren

4.3. Konfiguration

Webhooks werden pro Prozess von einem MOXIS-Administrator im Bereich der Prozesskonfiguration der Administrationsoberfläche eingerichtet. Der Administrator gibt Folgendes an:

  1. Die Ziel-Endpunkt-URL (HTTPS erforderlich)

  1. Die Authentifizierungsmethode: Basic-Auth-Zugangsdaten, OAuth 2.0 client_credentials oder keine Authentifizierung

  1. Den/die Trigger-Ereignistyp(en), die den Webhook auslösen sollen

Umgang mit SSL-Zertifikaten:
Bei der ersten erfolgreichen Verbindung speichert MOXIS das von Ihrem Endpunkt präsentierte SSL-Zertifikat. Nachfolgende Zustellungen werden gegen dieses gespeicherte Zertifikat validiert. Wenn das Zertifikat abläuft oder ersetzt wird, muss der Administrator den Webhook mit dem neuen Zertifikat neu konfigurieren.

4.4. Trigger-Ereignisse

Webhook-Trigger werden als nicht final (der Job wird nach dem Ereignis fortgesetzt) und final (der Job hat einen Endstatus erreicht) klassifiziert.

4.4.1. Nicht finale Trigger

Trigger

Beschreibung

Invited

Ein Signer wurde zum Job eingeladen

Signed

Ein einzelner Signer hat seine Signatur abgeschlossen

Changed Iteration

Der Job ist zur nächsten Iteration übergegangen

Before Signature

Wird unmittelbar vor dem Anbringen einer Signatur ausgelöst

Expiry Date Changed

Das Verfallsdatum des Jobs wurde geändert

4.4.2. Finale Trigger

Trigger

Beschreibung

Finished Successfully

Alle Signaturen sind eingeholt, das Dokument ist bereit.

Declined

Ein Signierender hat die Signatur abgelehnt.

Aborted

Der Job wurde abgebrochen.

Expired

Der Job hat sein Verfallsdatum ohne Abschluss erreicht.

Denied Draft

Ein Entwurf wurde vor Start des Jobs abgelehnt.

MOXIS Tipp
Konfigurieren Sie den Webhook für die meisten Integrationen so, dass er nur bei finalen Ereignistypen auslöst. Dies begrenzt das Zustellvolumen und stellt sicher, dass Sie nur bei einem endgültigen Ergebnis reagieren. Rufen Sie beim Empfang eines Finished Successfully-Events GET getDocument auf, um das signierte PDF abzurufen.

4.5. Feststellen des Jobabschlusses

Ein Job ist endgültig abgeschlossen und das Dokument ist bereit, wenn beide der folgenden Bedingungen im Webhook-Payload erfüllt sind:

  • state ist gleich FINISHED_SUCCESS

  • endDate ist nicht null

Prüfen Sie beide Felder. state allein reicht nicht aus — ein gesetztes endDate bestätigt, dass die serverseitige Nachbearbeitung abgeschlossen ist.

{
  "state": "FINISHED_SUCCESS",
  "endDate": "2026-04-23T14:30:00Z",
  ...
}

4.6. Webhook-Payload-Schema

Das an Ihren Endpunkt gesendete Payload ist ein JSON-Objekt. Alle String-Felder können null sein. Das Schema entspricht der Antwort von GET getJobState.

{
  "type": "object",
  "properties": {
    "state": { "type": "string" },
    "processId": { "type": "string" },
    "processInstanceId": { "type": "integer" },
    "jobMetaData": {
      "type": "object",
      "properties": {
        "description": { "type": "string" },
        "category": {},
        "expirationDate": { "type": "string" },
        "referenceId": {},
        "customMap": { "type": "object", "properties": {} },
        "externalPassword": {}
      }
    },
    "creationDate": { "type": "string" },
    "endDate": { "type": "string" },
    "currentIteration": { "type": "integer" },
    "iterations": {
      "type": "array",
      "items": {},
      "required": [
        "numberOfSignatures",
        "invitees",
        "category",
        "iterationNumber",
        "remark",
        "signerGroup",
        "privateIteration",
        "customMap",
        "groupPositions"
      ]
    },
    "additionalRecipients": { "type": "array" },
    "constituent": { "type": "string" },
    "customMap": { "type": "object", "properties": {} },
    "eventTimestamp": { "type": "string" },
    "eventType": { "type": "string" }
  }
}

4.6.1. Wichtige Felder

Feld

Typ

Beschreibung

state

string

Aktueller Job-Status (siehe Statustabelle unten)

processInstanceId

integer

Eindeutige Kennung dieses Jobs — verwenden Sie diese für nachfolgende API-Methodenaufrufe

endDate

string

ISO-8601-Zeitstempel, der gesetzt wird, wenn der Job einen Endstatus erreicht; null, solange der Job aktiv ist

eventType

string

Das Trigger-Ereignis, das diese Zustellung ausgelöst hat

eventTimestamp

string

Zeitpunkt, zu dem das Ereignis eingetreten ist

iterations

array

Details auf Iterationsebene, einschließlich der Ergebnisse einzelner Eingeladener

4.6.2. Job-Status

Status

Terminal?

Beschreibung

DRAFTING

Nein

Job ist ein Entwurf

ACTIVE

Nein

Läuft, wartet auf Signatur(en)

POST_PROCESSING

Nein

Signatur abgeschlossen, MOXIS-Nachbearbeitung läuft

FINISHED_SUCCESS

Ja

Alle Signaturen erfolgreich eingeholt

FINISHED_FAILED

Ja

Signatur fehlgeschlagen

FINISHED_TIMEOUT

Ja

Job vor Abschluss abgelaufen

FINISHED_WF_CANCELLED

Ja

Workflow abgebrochen

FINISHED_SIGNATURE_DENIED

Ja

Ein Signer hat das Dokument abgelehnt

DRAFT_DISMISSED

Ja

Entwurf wurde verworfen

4.7. Prüfen einzelner Signaturergebnisse

Um festzustellen, welche Aktion ein bestimmter Signer durchgeführt hat, prüfen Sie iterations[].invitees[].action im Payload. Dieses Feld spiegelt das individuelle Ergebnis für jeden Eingeladenen wider.

{
  "iterations": [
    {
      "iterationNumber": 0,
      "invitees": [
        {
          "name": "signer@example.com",
          "action": "SIGNED",
          "actionDate": "2026-04-23T14:28:00Z"
        }
      ]
    }
  ]
}

Häufige Werte für action sind SIGNED, DECLINED und null (noch keine Aktion durchgeführt).

4.8. Integrationsablauf

image-20260819-085207.png

sequenceDiagram
    participant App as Your App
    participant API as MOXIS API
    participant MOXIS as MOXIS
    participant Endpoint as Your Webhook Endpoint

    App->>API: POST /startProcess/{processId}
    API-->>App: 201 Created — processInstanceId

    Note over MOXIS: Signer completes signature in MOXIS UI

    MOXIS->>Endpoint: POST {webhookPayload} (final event)
    Endpoint-->>MOXIS: HTTP 200 OK

    Endpoint->>App: Forward event or trigger downstream logic

    App->>API: GET /getDocument/{processInstanceId}
    API-->>App: Signed PDF (blob)

4.9. Sicherheitsaspekte

4.9.1. Authentifizierung eingehender Webhook-Anfragen

Konfigurieren Sie Basic Auth oder OAuth client_credentials für Ihren Endpunkt. MOXIS übermittelt die Zugangsdaten in jeder Anfrage. Ihr Endpunkt muss diese Zugangsdaten validieren und Anfragen ablehnen, die nicht übereinstimmen.

Wenn Sie sich entscheiden, keine Authentifizierung zu verlangen (möglich, aber nicht empfohlen), stellen Sie sicher, dass andere Kontrollen vorhanden sind — zum Beispiel eine IP-Zulassungsliste für die Egress-Adressen von MOXIS.

4.9.2. SSL-Zertifikatsvertrauen

MOXIS vertraut dem bei der ersten Verbindung beobachteten SSL-Zertifikat. Das bedeutet:

  • Ihr Endpunkt muss von Anfang an ein gültiges Zertifikat präsentieren.

  • Wenn Ihr Zertifikat erneuert oder ersetzt wird, muss der MOXIS-Administrator die Webhook-Konfiguration aktualisieren, damit das neue Zertifikat hinterlegt wird.

  • Abgelaufene Zertifikate führen zu Zustellfehlern, bis die Konfiguration angepasst wird.

4.9.3. Reagieren auf Zustellungen

Geben Sie so schnell wie möglich den HTTP-Status 200 zurück. Führen Sie aufwendige Verarbeitungsschritte asynchron durch, nachdem der Empfang bestätigt wurde. Wenn Ihr Endpunkt einen Nicht-2xx-Status zurückgibt, kann MOXIS die Zustellung wiederholen (das Verhalten hängt von Ihrer MOXIS-Konfiguration ab).

4.10. Beispiel: Empfangen und Verarbeiten eines Webhooks

POST /moxis-webhook HTTP/1.1
Host: your-app.example.com
Authorization: Basic <base64(webhookUser:webhookPassword)>
Content-Type: application/json

{
  "state": "FINISHED_SUCCESS",
  "processInstanceId": 450123,
  "endDate": "2026-04-23T14:30:00Z",
  "eventType": "Finished successfully",
  "eventTimestamp": "2026-04-23T14:30:01Z",
  "jobMetaData": {
    "referenceId": "CONTRACT-00123",
    "description": "Contract review Q2 2026"
  },
  "iterations": [
    {
      "iterationNumber": 0,
      "invitees": [
        {
          "name": "signer@example.com",
          "action": "SIGNED",
          "actionDate": "2026-04-23T14:28:00Z"
        }
      ]
    }
  ]
}

4.10.1. Verarbeitungslogik:

  1. Basic-Auth-Header validieren — bei Ungültigkeit mit 401 ablehnen.

  1. Prüfen, ob state == "FINISHED_SUCCESS" und endDate != null.

  1. processInstanceId extrahieren (oder referenceId aus jobMetaData, falls Sie eigene Referenzen verwenden).

  1. Sofort mit 200 OK antworten.

  1. Asynchron GET /getDocument/{processInstanceId} aufrufen und das Ergebnis speichern.

4.11. Weiterführende Referenzen

  • GET getJobState: Dasselbe Datenmodell wie das Webhook-Payload

  • GET getDocument: Signiertes Dokument abrufen

  • POST createJob: Job erstellen, um den Workflow auszulösen

  • Authentifizierung: Einrichtung der API-Zugangsdaten

5. Middleware-Muster

Wenn mehrere interne Anwendungen mit MOXIS interagieren müssen, ist es unpraktikabel, in jeder von ihnen eine eigene direkte Integration zu implementieren und zu pflegen. Eine Middleware-Schicht (ein dedizierter Integrationsdienst) verwaltet die Verbindung zur MOXIS API und stellt den aufrufenden Anwendungen eine vereinfachte interne API zur Verfügung.

5.1. Wann dieses Muster verwendet werden sollte

  • Mehrere interne Anwendungen (CRM, ERP, DMS, individuelle Anwendungen) müssen Dokumente zur Signatur versenden

  • Sie möchten Zugangsdaten und Änderungen am API-Endpunkt an einer einzigen, zentral verwalteten Stelle pflegen

  • Aufrufende Anwendungen verfügen über eingeschränkte API-Fähigkeiten oder sind standardisierte Produkte ohne Spielraum für individuelle ausgehende HTTP-Logik

  • Sie möchten die fachliche Komplexität entkoppeln: Aufrufende Anwendungen sollen nichts über MOXIS-Job-Status, Prozess-IDs oder Iterationsmodelle wissen müssen

  • Sie benötigen gemeinsame Belange (Logging, Wiederholungslogik, Fehlerbehandlung, Audit-Trails) die konsistent über alle Aufrufer angewendet werden

5.2. Architekturübersicht

image-20260819-085316.png

graph TD
    A[App A<br/>CRM] -->|Internal API call| MW[Middleware<br/>Integration Service]
    B[App B<br/>DMS] -->|Internal API call| MW
    C[App C<br/>ERP] -->|Internal API call| MW
    MW -->|REST API| MOXIS[MOXIS API]
    MOXIS -->|Webhook or polling| MW
    MW -->|Event / callback| A
    MW -->|Event / callback| B
    MW -->|Event / callback| C

Aufrufende Anwendungen interagieren ausschließlich mit der internen API der Middleware. Die Middleware übersetzt diese Aufrufe in MOXIS-API-Anfragen, übernimmt die Authentifizierung, überwacht den Job-Status und liefert die Ergebnisse an die ursprüngliche Anwendung zurück.

5.3. Aufgaben der Middleware

Verwaltung der Zugangsdaten

Die Middleware hält die Zugangsdaten des MOXIS-Webservice-Benutzers (Basic Auth oder OAuth-Tokens) an einer einzigen Stelle. Wenn Zugangsdaten rotiert werden oder sich ein OAuth-Client-Secret ändert, muss nur die Middleware aktualisiert werden — die aufrufenden Anwendungen sind davon nicht betroffen.

Anfrage-Routing

Unterschiedliche Prozesse in MOXIS entsprechen unterschiedlichen Signatur-Workflows. Die Middleware bildet einen internen Anfragetyp (z. B. „Vertragsfreigabe“ oder „HR-Onboarding-Formular“) auf die passende MOXIS-processId ab, erstellt das jobDescription-JSON und ruft POST startProcess auf.

Job-Tracking

Die Middleware speichert die von MOXIS zurückgegebene processInstanceId (und optional eine referenceId) zusammen mit der internen Datensatz-ID der ursprünglichen Anwendung. Dies ist die Verknüpfung zwischen dem externen MOXIS-Job und dem internen fachlichen Kontext.

Event-Zustellung (Webhook-Modus)

Wenn MOXIS auf Enterprise Cloud läuft, registriert die Middleware einen einzigen Webhook-Endpunkt. Beim Empfang eines finalen Events führt die Middleware Folgendes aus:

  1. Validierung der eingehenden Anfrage (Basic Auth oder OAuth)

  1. Nachschlagen des mit der processInstanceId verknüpften internen Datensatzes

  1. Aufruf von GET getDocument zum Abrufen des signierten PDFs

  1. Zustellung des Ergebnisses an die ursprüngliche Anwendung über einen internen Event-Bus, Callback oder direkten API-Aufruf

Event-Zustellung — Polling-Modus

Wenn Webhooks nicht verfügbar sind (z.B. in der MOXIS Business Cloud), betreibt die Middleware einen Scheduler, der in regelmäßigen Abständen GET lookupJobStates aufruft, Paginierung anwendet, Dokumente für abgeschlossene Jobs abruft und Ergebnisse intern verteilt. Die Abfragestrategie ist im Polling-Muster beschrieben.

Wiederholungslogik

Vorübergehende Fehler — Netzwerk-Timeouts, MOXIS-500-Fehler, Nichtverfügbarkeit einer nachgelagerten Anwendung — werden von der Middleware mittels exponentiellem Backoff behandelt. Aufrufende Anwendungen müssen keine eigene Wiederholungslogik implementieren.

Logging und Audit

Alle ausgehenden API-Aufrufe an MOXIS sowie alle eingehenden Events werden zentral protokolliert. Dies liefert einen vollständigen Audit-Trail der Dokumentenlebenszyklus-Ereignisse über alle aufrufenden Anwendungen hinweg.

Fehlerbehandlung

Die Middleware normalisiert MOXIS-Fehlerantworten (400, 404, 500) und übersetzt sie in konsistente Fehlercodes für die aufrufenden Anwendungen.

5.4. Integrationsablauf

Webhook-Variante

image-20260819-085446.png

sequenceDiagram
    participant AppA as App A
    participant MW as Middleware
    participant API as MOXIS API
    participant MOXIS as MOXIS
    participant Endpoint as Middleware Webhook Endpoint

    AppA->>MW: createSigningRequest(docId, signerEmail)
    MW->>API: POST /startProcess/{processId}
    API-->>MW: 201 Created — processInstanceId
    MW->>MW: Store docId → processInstanceId mapping

    Note over MOXIS: Signer completes signature

    MOXIS->>Endpoint: POST webhook payload (FINISHED_SUCCESS)
    Endpoint-->>MOXIS: 200 OK
    MW->>API: GET /getDocument/{processInstanceId}
    API-->>MW: Signed PDF
    MW->>AppA: Deliver signed PDF / fire internal event

Polling-Variante

image-20260819-085549.png

sequenceDiagram
    participant AppA as App A
    participant MW as Middleware
    participant API as MOXIS API
    participant Scheduler as Scheduler

    AppA->>MW: createSigningRequest(docId, signerEmail)
    MW->>API: POST /startProcess/{processId}
    API-->>MW: 201 Created — processInstanceId
    MW->>MW: Store docId → processInstanceId mapping

    loop Every polling interval
        Scheduler->>API: GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...
        API-->>Scheduler: Array of completed jobs

        loop For each completed job
            Scheduler->>API: GET /getDocument/{processInstanceId}
            API-->>Scheduler: Signed PDF
            Scheduler->>AppA: Deliver signed PDF / fire internal event
        end
    end

5.5. Design der internen API

Die Middleware sollte den aufrufenden Anwendungen eine einfachere Schnittstelle bereitstellen. Eine minimale interne API könnte Folgendes umfassen:

Interner Endpunkt

Beschreibung

POST /sign

Dokument zur Signatur einreichen. Akzeptiert ein Dokument-Blob und Metadaten; liefert eine interne Job-ID zurück

GET /sign/{internalJobId}

Status eines Signaturjobs über die interne ID abfragen

GET /sign/{internalJobId}/document

Signiertes Dokument nach Abschluss abrufen

POST /sign/{internalJobId}/cancel

Einen laufenden Job abbrechen

Aufrufende Anwendungen sehen niemals processInstanceId, processId, iterationData oder ein anderes MOXIS-spezifisches Konzept. Sie arbeiten ausschließlich mit dem internen Domänenmodell.

5.6. Vorteile

  • Zentraler Aktualisierungspunkt:
    Rotation von Zugangsdaten, Änderungen der Endpunkt-URL oder API-Versionsupgrades erfolgen an einer einzigen Stelle

  • Vereinfachte Aufrufer:
    App A muss überhaupt nicht wissen, dass die Signatur über MOXIS abgewickelt wird

  • Konsistentes Verhalten:
    Wiederholungslogik, Logging und Fehlerbehandlung werden einheitlich angewendet

  • Flexibles Event-Modell: Die Middleware kann Webhook und Polling gleichzeitig unterstützen. Dies ist nützlich bei der Migration zwischen MOXIS Varianten oder Umgebungen

  • Testbarkeit: Aufrufende Anwendungen können gegen eine simulierte Middleware getestet werden, ohne eine aktive MOXIS-Verbindung

5.7. Hinweise zur Implementierung

Postman-Collection als leichtgewichtige Middleware

MOXIS stellt eine Postman-Collection für die MOXIS API bereit. Für Tests und interne Evaluierungen fungiert die Postman-Collection als minimale Ausprägung dieses Musters. Sie abstrahiert die rohen HTTP-Aufrufe hinter benannten Requests und Umgebungsvariablen. Sie ist nicht für den Produktionseinsatz geeignet, aber ein nützlicher Ausgangspunkt, um die API zu verstehen, bevor eine echte Middleware aufgebaut wird.

Technologieauswahl

Die Middleware kann implementiert werden als: - Ein dedizierter Microservice (Node.js, Java, .NET, Python) - Eine Integrationsplattform (MuleSoft, Azure Logic Apps, Apache Camel) - Eine Sammlung serverloser Funktionen mit einer Warteschlange für das Job-Tracking

Die MOXIS API stellt keine Anforderungen an die Middleware-Technologie. Sie kommuniziert über Standard-HTTPS mit Basic Auth oder OAuth 2.0 (client_credentials).

Idempotenz

Speichern Sie die von MOXIS zurückgegebene processInstanceId sofort nach POST startProcess. Wenn der Aufruf erfolgreich ist, Ihre Middleware jedoch abstürzt, bevor die ID gespeichert wird, müssen Sie den Job möglicherweise mit GET lookupJobStates über eine referenceId oder ein Zeitfenster wiederherstellen. Weisen Sie bei der Job-Erstellung eine referenceId aus Ihrem eigenen System zu, um die Wiederherstellung deterministisch zu gestalten.

5.8. Weiterführende Referenzen

  • Webhook-Integration: Ereignisbasierte Abschlussbenachrichtigung

  • Polling-Muster: Zeitgesteuerte Abschlusserkennung

  • POST createJob: Job-Erstellung mit referenceId

  • GET lookupJobStates: Bulk-Abfragen des Job-Status

  • GET getDocument: Dokumentabruf

  • Authentifizierung: Einrichtung von Basic Auth und OAuth