MOXIS API Dokumentation
German English

Schnellstart-Anleitung für MOXIS-Signatur-Jobs: API-Integration und Dokumentenmanagement

Inhalt

Diese Anleitung führt Sie durch das Senden eines PDFs an MOXIS zur Signatur und das Abrufen des signierten Ergebnisses. Am Ende haben Sie einen echten API-Aufruf durchgeführt, einen Signatur-Job erstellt und ein signiertes Dokument herunterladen. Die Seite enthält zudem Use Cases.


1. Voraussetzungen

Bevor Sie beginnen, benötigen Sie drei Dinge:

  1. MOXIS-Webservice-Benutzeranmeldedaten:
    Einen Benutzernamen und ein Passwort für einen technischen API-Benutzer. Wenden Sie sich an Ihre:n MOXIS Ansprechpartner:in oder Ihre:n MOXIS Administrator:in, um einen solchen anlegen zu lassen. Bitte beachten Sie: Dies ist nicht dasselbe wie ein regulärer MOXIS Login.

  1. Eine processId:
    Die Kennung des Signaturprozesses, den Sie verwenden möchten. Sie finden diese in der MOXIS-Administration. Sie hat die Form einer kurzen Zeichenfolge oder UUID, die Ihrem konfigurierten Prozess zugewiesen ist.

  1. Ein Test-PDF
    Eine beliebige gültige PDF-Datei, die Sie signieren möchten.

2. Schritt-für-Schritt Anleitungen

2.1. Schritt 1: Den Authorization-Header erstellen

Die MOXIS-REST-API verwendet HTTP Basic Authentication. Kodieren Sie Ihre Anmeldedaten wie folgt:

base64(username:password)

Beispiel:
Wenn Ihr Benutzername api-user und Ihr Passwort secret123 lautet:

Bash
echo -n "api-user:secret123" | base64
# Ergebnis: YXBpLXVzZXI6c2VjcmV0MTIz

Verwenden Sie diese kodierte Zeichenfolge in jeder Anfrage:

Authorization: Basic YXBpLXVzZXI6c2VjcmV0MTIz

Bitte beachten Sie: Verwenden Sie stets HTTPS. Über einfaches HTTP übertragene Basic-Anmeldedaten sind nicht sicher.

Die Basis-URL für alle API-Aufrufe lautet:

https://<moxis-base-url>/webservices/rest/api/layer2/v1.0

Ersetzen Sie

<moxis-base-url> 

durch den Hostnamen Ihrer MOXIS-Instanz.


2.2. Schritt 2: Einen unsichtbaren Signatur-Job erstellen

Die unsichtbare Signatur ist der einfachste Integrationspunkt. Das Dokument wird kryptografisch signiert, ohne dass ein visueller Stempel auf den PDF-Seiten hinzugefügt wird. Signaturprüfwerkzeuge erkennen die Signatur trotzdem. Dies erfüllt vollständig die Anforderungen an eine qualifizierte elektronische Signatur (QES) nach eIDAS.

Der API-Aufruf ist ein Multipart-POST an:

POST <base-url>/startProcess/{processId}

Der Multipart-Body enthält zwei Teile:

  • jobDescription: Ein JSON-Objekt, das den Job beschreibt

  • documentToSign: Ihre PDF-Datei


jobDescription JSON:

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "INVISIBLE",
  "metaData": {
    "description": "My first MOXIS signature job"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.User",
          "classifier": "EMAIL",
          "name": "signer@yourdomain.com",
          "roleName": "moxisApprover"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0
    }
  ]
}
  • constituent: Der MOXIS-Benutzer, dem der Job gehört (in der Regel der Systembenutzer oder Dokumenteigentümer)

  • positionType: INVISIBLE; kein visueller Stempel auf dem Dokument

  • iterationData: legt fest, wer in welcher Reihenfolge signiert; iterationNumber beginnt bei 0

  • category: APPROVAL; eine einfache elektronische Signatur (SES); verwenden Sie QSIG für eine qualifizierte Signatur


Vollständiges cURL-Beispiel:

JavaScript
curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    },
    "positionType": "INVISIBLE",
    "metaData": {
      "description": "My first MOXIS signature job"
    },
    "iterationData": [
      {
        "invitees": [
          {
            "@class": "com.xitrust.moxispe.api.User",
            "classifier": "EMAIL",
            "name": "signer@yourdomain.com",
            "roleName": "moxisApprover"
          }
        ],
        "category": "APPROVAL",
        "iterationNumber": 0
      }
    ]
  };type=application/json' \
  -F "documentToSign=@/path/to/your/document.pdf;type=application/pdf"

Eine erfolgreiche Antwort liefert HTTP 201 Created mit der processInstanceId als reinen String im Body. Speichern Sie diesen Wert — Sie benötigen ihn für alle nachfolgenden Aufrufe.

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Bitte beachten Sie: Erhalten Sie eine 404, wurde die processId nicht gefunden. Erhalten Sie eine 401, sind Ihre Anmeldedaten falsch oder es wurde eine Weiterleitung zur Login-Seite ausgelöst.


2.3. Schritt 3: Den Job-Status abfragen

Verwenden Sie die in Schritt 2 zurückgegebene processInstanceId, um den aktuellen Status des Jobs zu prüfen.

GET <base-url>/getJobState/{processInstanceId}/{nameClassifier}
  • nameClassifier: Die E-Mail-Adresse (oder UPN/ID) des Constituent-Benutzers, den Sie beim Erstellen des Jobs verwendet haben.

cURL-Beispiel:

curl -X GET \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/a1b2c3d4-e5f6-7890-abcd-ef1234567890/owner@yourdomain.com" \
  -H "Authorization: Basic <base64-encoded-credentials>"

Die Antwort ist ein JSON-Objekt. Das wichtigste Feld ist state:

Status

Bedeutung

ACTIVE

Der Job läuft; der Signer hat noch nicht gehandelt

POST_PROCESSING

Die Signatur ist abgeschlossen; MOXIS verarbeitet das Dokument

FINISHED_SUCCESS

Die Signatur wurde erfolgreich abgeschlossen; das Dokument ist bereit

FINISHED_FAILED

Der Signaturprozess ist fehlgeschlagen

FINISHED_SIGNATURE_DENIED

Ein Signer hat das Dokument abgelehnt

FINISHED_TIMEOUT

Der Job ist abgelaufen, bevor alle Signaturen eingeholt wurden

FINISHED_WF_CANCELLED

Der Job wurde abgebrochen

DRAFTING

Der Job ist noch ein Entwurf (noch nicht aktiv)

Fragen Sie diesen Endpunkt regelmäßig ab, bis state gleich

FINISHED_SUCCESS

ist, bevor Sie das Dokument herunterladen.

Bitte beachten Sie: Die MOXIS-Enterprise-Cloud unterstützt Webhooks, wodurch das Polling entfällt. Ihr Endpunkt erhält eine Benachrichtigung, sobald sich der Job-Status ändert. Wenden Sie sich an MOXIS, wenn Sie stattdessen Webhooks verwenden möchten.


2.4. Schritt 4: Das signierte Dokument herunterladen

Rufen Sie das signierte PDF auf die folgende Art und Weise ab:

GET <base-url>/getDocument/{processInstanceId}

cURL-Beispiel (speichert in Datei):

JavaScript
curl -X GET \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -o signed-document.pdf

Der Antwortkörper ist die signierte PDF-Binärdatei. Der HTTP-Status ist bei Erfolg 200 OK.

MOXIS Tipp
Starten Sie mit INVISIBLE, bevor Sie die diversen Visualisierungsarten ausprobieren.


Der positionType INVISIBLE verzichtet bewusst auf die Signaturvisualisierung. Dies ist der beste Ausgangspunkt bei der erstmaligen Integration, weil:

  • er die einfachste jobDescription-Struktur hat

  • keine Abhängigkeit von Koordinaten, Platzhalterbildern oder PDF-Formularfeldern besteht

  • er bestätigt, dass Ihre Authentifizierung, processId und Netzwerkanbindung korrekt sind

Sobald Ihr Aufruf für die unsichtbare Signatur funktioniert, wechseln Sie zu den Visualisierungs-Anleitungen, wenn Ihre Integration einen sichtbaren Stempel auf dem Dokument benötigt.


2.5. Nächste Schritte

  • Authentifizierung: Details zu Basic Auth und OAuth 2.0 mit Keycloak

  • Create Job API-Referenz: vollständige Parameterreferenz für startProcess

  • Unsichtbare Signatur: genauere Erläuterung des positionType INVISIBLE

  • Signaturseite: eine visuelle Signaturseite ohne Koordinaten hinzufügen

  • Direkte Position: einen visuellen Stempel an exakten PDF-Koordinaten platzieren

3. Unsichtbare Signatur

Eine unsichtbare Signatur wendet eine kryptografische Signatur auf ein PDF an, ohne einen visuellen Stempel, ein Wasserzeichen oder einen Signaturblock auf den Dokumentseiten hinzuzufügen. Der Dokumentinhalt erscheint unverändert, die eingebettete Signatur ist jedoch von PDF-Prüfwerkzeugen erkennbar und wird nach eIDAS rechtlich als qualifizierte elektronische Signatur (QES) anerkannt.

3.1. Wann sollte man eine unsichtbare Signatur verwenden?

Verwenden Sie die unsichtbare Signatur, wenn:

  • Sie die einfachstmögliche Integration für den Einstieg benötigen

  • ein visueller Nachweis der Signatur keine geschäftliche Anforderung ist, sondern der kryptografische Nachweis ausreicht

  • Ihr Prozess QES-eIDAS-Konformität erfordert und kein sichtbarer Stempel benötigt wird

  • Sie Ihre API-Verbindung validieren möchten, bevor Sie komplexere Visualisierungsoptionen implementieren

Bitte beachten Sie: Dies ist der empfohlene Ausgangspunkt für jede neue MOXIS-Integration. Wenn Sie unsicher sind, welchen positionType Sie verwenden sollen, beginnen Sie hier.


3.2. Struktur der jobDescription

Das zentrale Feld ist "positionType": "INVISIBLE" auf oberster Ebene der Job-Beschreibung. Die Signer-Informationen werden im Array iterationData angegeben.


{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "INVISIBLE",
  "metaData": {
    "description": "Example invisible signature"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.User",
          "classifier": "EMAIL",
          "name": "signer@yourdomain.com",
          "roleName": "moxisApprover"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0
    }
  ]
}

Feldreferenz:

Feld

Beschreibung

constituent.name

E-Mail-Adresse des Benutzers, dem der Job in MOXIS gehört

constituent.@class

Für interne Benutzer immer com.xitrust.moxispe.api.User

positionType

INVISIBLE: keine visuelle Darstellung

metaData.description

Optionale Bezeichnung, die in der MOXIS-Benutzeroberfläche sichtbar ist

iterationData[].invitees

Array der Signer für diese Signaturrunde

invitees[].@class

com.xitrust.moxispe.api.User für interne Signer

invitees[].roleName

Die MOXIS-Rolle, die der Signer benötigt (z. B. moxisApprover, moxisSigner)

category

APPROVAL für einfache/SES-Signatur; QSIG für qualifizierte Signatur

iterationNumber

Index dieser Signaturrunde, beginnend bei 0

Für eine qualifizierte Signatur (QES) ändern Sie category auf "QSIG" und roleName auf “moxisSigner”. So stellen Sie sicher, dass der Signer die Rolle moxisSigner besitzt.


3.3. Vollständiges cURL-Beispiel

JavaScript
curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    },
    "positionType": "INVISIBLE",
    "metaData": {
      "description": "Example invisible signature"
    },
    "iterationData": [
      {
        "invitees": [
          {
            "@class": "com.xitrust.moxispe.api.User",
            "classifier": "EMAIL",
            "name": "signer@yourdomain.com",
            "roleName": "moxisApprover"
          }
        ],
        "category": "APPROVAL",
        "iterationNumber": 0
      }
    ]
  };type=application/json' \
  -F "documentToSign=@/path/to/document.pdf;type=application/pdf"

Eine 201 Created-Antwort liefert die processInstanceId als reinen String:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"


3.4. Was nach dem Absenden passiert

  1. MOXIS erstellt den Job und weist ihn dem Signierenden zu.

  1. Der Signierende erhält von MOXIS eine E-Mail-Benachrichtigung mit einem Link zum Dokument.

  1. Der Signierende öffnet MOXIS (oder MOXIS Guest für externe Signierende) und bringt seine Signatur an.

  1. Der Job durchläuft die Statuswerte: ACTIVE → POST_PROCESSING → FINISHED_SUCCESS.

  1. Das signierte PDF steht zum Download bereit.


3.5. Das signierte Dokument abrufen

Fragen Sie getJobState ab, bis der Status FINISHED_SUCCESS lautet, und rufen Sie anschließend getDocument auf:

# Job-Status prüfen

curl -X GET \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/<processInstanceId>/owner@yourdomain.com" \
  -H "Authorization: Basic <base64-encoded-credentials>"

# Signiertes Dokument herunterladen (nach FINISHED_SUCCESS ausführen)

JavaScript
curl -X GET \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/<processInstanceId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -o signed-document.pdf

3.7. Siehe auch

  • Schnellstart: Durchgängiger Leitfaden inklusive Auth-Einrichtung

  • Signaturseite: Eine visuelles Unterschriftenblatt hinzufügen, ohne Koordinaten anzugeben

  • Create Job API-Referenz: Vollständige Parameterreferenz


4. Unterschriftenblatt

Die Option Unterschriftenblatt fügt dem signierten PDF automatisch eine zusätzliche Seite hinzu. Diese abschließende Seite enthält eine visuelle Darstellung aller während des Prozesses eingeholten Signaturen. Layout und Design dieser Seite werden von einem Administrator in MOXIS vorkonfiguriert.

4.1. Wann verwendet man am Besten ein Unterschriftenblatt?

Verwenden Sie das Unterschriftenblatt, wenn:

  • Sie einen menschenlesbaren visuellen Nachweis darüber wünschen, wer das Dokument signiert hat

  • Sie die genauen Koordinaten innerhalb Ihres PDFs, an denen ein Signaturstempel erscheinen soll, nicht kennen (oder nicht verwalten möchten)

  • Sie ein einheitliches, administrativ gesteuertes Design für die Signaturvisualisierung über alle Dokumente hinweg wünschen

Das Unterschriftenblatt wird nach Abschluss des Signaturprozesses automatisch von MOXIS angehängt. Sie müssen Ihr Quell-PDF in keiner Weise verändern.

Bitte beachten Sie: Das Erscheinungsbild der Signaturseite (einschließlich Branding, Schriftarten und Layout) wird von Ihrer oder Ihrem MOXIS-Administrator:in im MOXIS-Administrationsbereich konfiguriert. Änderungen am Design erfordern Administratorzugriff; über die API können Sie das Design nicht beeinflussen.


4.2. Struktur der jobDescription

Setzen Sie "positionType": "SIGNATURE_PAGE" auf oberster Ebene der Job-Beschreibung. Alles andere folgt derselben Struktur wie bei jedem anderen Job.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "SIGNATURE_PAGE",
  "metaData": {
    "description": "Example Signature Page"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "signer@yourdomain.com",
          "roleName": "moxisApprover"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0
    }
  ]
}


4.2.1. Feldreferenz:

Feld

Beschreibung

positionType

SIGNATURE_PAGE: Löst das automatische Unterschriftenblatt aus

constituent.name

E-Mail-Adresse des Benutzers, dem der Job in MOXIS gehört

invitees[].@class

com.xitrust.moxispe.api.UserForRole für rollenbasierte Zuweisung; verwenden Sie com.xitrust.moxispe.api.User für eine direkte Benutzerreferenz

invitees[].roleName

Die MOXIS-Rolle des Signers (z. B. moxisApprover)

category

APPROVAL für einfache Signatur/SES; QSIG für qualifizierte Signatur

iterationNumber

Index der Signaturrunde, beginnend bei 0

Wenn Sie mehrere Signer in einer bestimmten Reihenfolge haben, fügen Sie iterationData weitere Objekte mit aufsteigenden iterationNumber-Werten hinzu. Jede Iteration muss abgeschlossen sein, bevor die nächste beginnt.

4.3. Vollständiges cURL-Beispiel

JavaScript
curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    },
    "positionType": "SIGNATURE_PAGE",
    "metaData": {
      "description": "Example Signature Page"
    },
    "iterationData": [
      {
        "invitees": [
          {
            "@class": "com.xitrust.moxispe.api.UserForRole",
            "classifier": "EMAIL",
            "name": "signer@yourdomain.com",
            "roleName": "moxisApprover"
          }
        ],
        "category": "APPROVAL",
        "iterationNumber": 0
      }
    ]
  };type=application/json' \
  -F "documentToSign=@/path/to/document.pdf;type=application/pdf"

Bei Erfolg liefert MOXIS HTTP 201 Created mit der processInstanceId als reinen String im Antwortkörper.

4.4. Ergebnis: Wie das signierte PDF aussieht

Nachdem alle Signaturen eingeholt wurden und der Job den Status FINISHED_SUCCESS erreicht:

  • Die ursprünglichen PDF-Seiten bleiben exakt wie eingereicht erhalten

  • Eine neue, abschließende Seite mit der Signaturvisualisierung wird angehängt

  • Die Signaturseite enthält üblicherweise Namen der Signer, Zeitstempel und Signaturbilder, wie vom Administrator konfiguriert

Rufen Sie das fertige Dokument mit Folgendem ab:

JavaScript
curl -X GET \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/<processInstanceId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -o signed-document.pdf


4.5. Siehe auch

  • “Unsichtbare” Signatur: Signieren ohne jegliche visuelle Ausgabe

  • Direkte Position: Einen Stempel an exakten Koordinaten auf einer bestimmten Seite platzieren

  • Create Job API-Referenz: Vollständige Parameterreferenz


5. Einen Entwurf für benutzergesteuerte Signaturplatzierung erstellen

Ein Entwurf ermöglicht es Ihnen, ein Dokument an MOXIS hochzuladen, ohne die Signaturpositionen vorab festzulegen. Nachdem der Entwurf erstellt wurde, öffnet ein MOXIS-Benutzer das Dokument über die MOXIS-Benutzeroberfläche, platziert die Signaturvisualisierung an der gewünschten Stelle und übermittelt das Dokument anschließend, um den eigentlichen Signaturprozess zu starten.


5.1. Wann verwenden Sie am Besten einen Entwurf?

Verwenden Sie den Entwurfs-Workflow, wenn:

  • Sie zum Zeitpunkt des API-Aufrufs nicht wissen, wo im PDF die Signatur erscheinen soll

  • Sie möchten, dass ein Mensch die Platzierung interaktiv in der MOXIS-Benutzeroberfläche festlegt

  • Sie einen Workflow aufbauen, bei dem die Dokumentenprüfung und die Signaturplatzierung in MOXIS erfolgen, bevor der Job an die Signierenden geht


5.2. Was ein Entwurf benötigt

Das Erstellen eines Entwurfs ist einfacher als das Erstellen eines vollständigen Signatur-Jobs. Das einzige erforderliche Feld in der jobDescription ist constituent. Das ist der Benutzer, dem der Entwurf in MOXIS gehört und der ihn verwaltet. Sie müssen zu diesem Zeitpunkt weder iterationData noch Signer angeben.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  }
}


5.3. API-Aufruf: POST createDraft

POST <base-url>/createDraft/{processId}

Vollständiges cURL-Beispiel:

JavaScript
curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/createDraft/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    }
  };type=application/json' \
  -F "documentToSign=@/path/to/document.pdf;type=application/pdf"

Bei Erfolg liefert MOXIS HTTP 201 Created mit der processInstanceId des Entwurfs als reinen String:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Hinweis: Eine 404-Antwort bedeutet, dass die processId nicht gefunden wurde. Überprüfen Sie diese im MOXIS-Prozessadministrationsbereich.


5.4. So zeigen Sie den Entwurf einem Benutzer an

Sobald der Entwurf erstellt ist, erstellen Sie diese URL und teilen Sie sie mit dem Benutzer, der die Signaturposition festlegen soll:

https://<baseurl>/ui/protected/?moxisView=CreateDraftedProcessView/<processInstanceId>

Ersetzen Sie <baseurl> durch den Hostnamen Ihrer MOXIS-Instanz und <processInstanceId> durch den in der API-Antwort zurückgegebenen Wert. Beim Öffnen dieser URL in einem Browser wird das Dokument in der Vollbild-MOXIS-Ansicht angezeigt, in der der Benutzer:

  1. das Dokument prüfen kann

  1. die Signaturvisualisierung an der gewünschten Stelle platzieren kann

  1. Signer-Informationen bei Bedarf hinzufügen oder anpassen kann

  1. den Entwurf übermitteln kann, um ihn in einen aktiven Signatur-Job umzuwandeln


5.5. Lebenszyklus eines Entwurfs

Entwurf erstellt (API-Aufruf)
        |
        v
Benutzer öffnet Entwurfs-URL in MOXIS
        |
        v
Benutzer legt Signaturposition und Signierende fest
        |
        v
Benutzer übermittelt Entwurf → wird zu einem aktiven Signatur-Job
        |
        v
Signatur verläuft normal weiter (ACTIVE → FINISHED_SUCCESS)

Entwürfe werden nicht sofort automatisch gelöscht. Sie werden von MOXIS bereinigt, nachdem ihr konfiguriertes Enddatum abgelaufen ist. Sie können einen Entwurf auch programmatisch über den Endpunkt dismissDraft verwerfen, wenn Sie ihn vor dem Enddatum schließen möchten, ohne ihn dauerhaft zu löschen.


5.6. Externe Benutzer und ON_PLACEHOLDER

Wenn ein Entwurf in einen Job umgewandelt wird, verwendet MOXIS standardmäßig positionType: ON_PLACEHOLDER, falls kein anderer positionType gesetzt wurde. Beachten Sie, dass externe Benutzer (Gäste) in manchen Konfigurationen möglicherweise nicht in der Lage sind, ihre eigene Signaturvisualisierung selbst zu platzieren. Wenn Ihr Workflow externe Signer umfasst, die ihren eigenen Stempel positionieren müssen, prüfen Sie diese Möglichkeit vorab mit Ihrem MOXIS-Administrator.


5.7. Optional: Mehrere Dokumente anhängen

Der Endpunkt createMultiSignDraft funktioniert auf dieselbe Weise, akzeptiert jedoch mehrere Dokumente unter dem Schlüssel documentsToSign (statt documentToSign):

curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/createMultiSignDraft/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    }
  };type=application/json' \
  -F "documentsToSign=@/path/to/document1.pdf;type=application/pdf" \
  -F "documentsToSign=@/path/to/document2.pdf;type=application/pdf"


5.8. Siehe auch

  • Unsichtbare Signatur: Platzierung komplett überspringen, ohne visuelle Ausgabe

  • Unterschriftenblatt: Eine Signaturseite ohne Benutzerinteraktion automatisch anhängen

  • Direkte Position: Exakte Koordinaten programmatisch angeben

  • Create Job API-Referenz: Vollständige Parameterreferenz für startProcess


6. Direkte Position: Platzierung an exakten Koordinaten

Der positionType DIRECT_POSITION ermöglicht es Ihnen, die exakte Stelle anzugeben, an der eine Signaturvisualisierung auf einer PDF-Seite erscheinen soll. Koordinaten, Abmessungen und die Zielseitenzahl werden alle in der jobDescription übergeben. Dieser Ansatz ist vollständig programmatisch; für die Platzierung der Signatur ist keine Benutzerinteraktion erforderlich.


6.1. Wann verwenden Sie die direkte Positionierung am Besten?

Verwenden Sie die direkte Position, wenn:

  • Ihr System die exakte Stelle im PDF kennt, an der die Signatur platziert werden soll (zum Beispiel eine Signaturzeile, die von Ihrer Dokumentvorlage generiert wird)

  • Sie eine durchgängige Automatisierung ohne manuellen Platzierungsschritt wünschen

  • Sie PDFs programmatisch generieren und Koordinaten aus dem Dokumentlayout zuverlässig berechnen können

MOXIS Tipp
Die direkte Position unterstützt keine Mehrfachvisualisierungsszenarien (Platzierung derselben Signatur an mehreren Stellen). Für diesen Anwendungsfall siehe Persönliche Platzhalter oder Mehrere Platzhalter.


6.2. Funktionsweise

Zwei Felder wirken zusammen, um die visuelle Position zu definieren:

  1. "positionType": "DIRECT_POSITION" — auf oberster Ebene der jobDescription gesetzt

  1. directUserPosition — auf jedem Invitee-Objekt innerhalb von iterationData gesetzt; definiert die Begrenzungsbox für den Stempel dieses bestimmten Signers

Das Objekt directUserPosition akzeptiert:

Feld

Typ

Beschreibung

x

float

Horizontaler Abstand vom linken Seitenrand, in PDF-Punkten

y

float

Vertikaler Abstand vom unteren Seitenrand, in PDF-Punkten

width

float

Breite des Signaturstempelbereichs, in PDF-Punkten

height

float

Höhe des Signaturstempelbereichs, in PDF-Punkten

pageNumber

int

Seitenzahl, auf der der Stempel erscheinen soll (beginnend bei 1)

MOXIS Tipp
PDF-Koordinaten werden in Punkten angegeben (1 Punkt = 1/72 Zoll). Der Ursprung (0, 0) liegt in der unteren linken Ecke der Seite. Eine Standard-A4-Seite ist ungefähr 595 × 842 Punkte groß.


6.3. Vollständiges jobDescription-Beispiel

Dieses Beispiel sendet das Dokument an einen externen Signer und platziert dessen Signaturstempel an einer bestimmten Position auf Seite 2 des PDFs.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "DIRECT_POSITION",
  "metaData": {
    "description": "Example coordinates for visualization"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
          "classifier": "EMAIL",
          "name": "external.signer@example.com",
          "externalUserName": "External Signer",
          "phoneNumber": "+43664123456",
          "roleName": "Extern",
          "locale": "de",
          "directUserPosition": {
            "x": "66",
            "y": "510",
            "width": "225",
            "height": "80",
            "pageNumber": 2
          }
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 0
    }
  ]
}

Für interne Signierende verwenden Sie com.xitrust.moxispe.api.User als @class und entfernen Sie die Felder externalUserName und phoneNumber:

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "DIRECT_POSITION",
  "metaData": {
    "description": "Internal signer with coordinates"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.User",
          "classifier": "EMAIL",
          "name": "internal.signer@yourdomain.com",
          "directUserPosition": {
            "x": "66",
            "y": "510",
            "width": "225",
            "height": "80",
            "pageNumber": 1
          }
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0
    }
  ]
}


6.4. Vollständiges cURL-Beispiel

JavaScript
curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    },
    "positionType": "DIRECT_POSITION",
    "metaData": {
      "description": "Example coordinates for visualization"
    },
    "iterationData": [
      {
        "invitees": [
          {
            "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
            "classifier": "EMAIL",
            "name": "external.signer@example.com",
            "externalUserName": "External Signer",
            "phoneNumber": "+43664123456",
            "roleName": "Extern",
            "locale": "de",
            "directUserPosition": {
              "x": "66",
              "y": "510",
              "width": "225",
              "height": "80",
              "pageNumber": 2
            }
          }
        ],
        "category": "EXTERNAL_APPROVAL",
        "iterationNumber": 0
      }
    ]
  };type=application/json' \
  -F "documentToSign=@/path/to/document.pdf;type=application/pdf"

Bei Erfolg liefert MOXIS HTTP 201 Created mit der processInstanceId als reinen String.


6.5. Selbstpositionierung für externe Signierende

Eine Variante von DIRECT_POSITION erlaubt externen Signierenden, ihre eigene Platzierung interaktiv in MOXIS Guest für externe Signierende zu wählen. Um dies zu aktivieren, setzen Sie positionType: DIRECT_POSITION, lassen jedoch directUserPosition beim Invitee weg. Der externe Signer wird beim Öffnen des Dokuments aufgefordert, seinen Signaturstempel per Ziehen zu platzieren.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "DIRECT_POSITION",
  "metaData": {
    "description": "External signer places their own position"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
          "classifier": "EMAIL",
          "name": "external.signer@example.com",
          "externalUserName": "External Signer",
          "phoneNumber": "+43664123456",
          "roleName": "Extern"
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 0
    }
  ]
}


MOXIS Tipp
Die Selbstpositionierung gilt ausschließlich für externe Signierende. Interne Signierende können diesen Modus nicht nutzen.


6.6. Siehe auch

  • Unterschriftenblatt: Visuelle Ausgabe ohne benötigte Koordinaten

  • Persönliche Platzhalter: Positionsdaten direkt im PDF einbetten

  • Entwurf erstellen: Die Signatur interaktiv durch einen Benutzer in MOXIS platzieren lassen

  • Create Job API-Referenz: Vollständige Parameterreferenz


7. Persönliche Platzhalter

Ein persönlicher Platzhalter ist eine Bilddatei, die die Identität einer bestimmten, namentlich genannten Person und deren Signaturiterationsdaten in EXIF-Metadaten und einem eingebetteten QR-Code kodiert. Wird ein PDF mit einem oder mehreren persönlichen Platzhalterbildern an MOXIS übermittelt und ist der Prozess so konfiguriert, dass Platzhalter ausgewertet werden, liest MOXIS die kodierten Informationen automatisch aus und erstellt den Signatur-Workflow, ohne dass eine detaillierte iterationData in der jobDescription erforderlich ist.

7.1. Was persönliche Platzhalter sind

Ein persönlicher Platzhalter wird für eine bestimmte Einzelperson generiert, zum Beispiel max.test@yourdomain.com in Iteration 0. Das Bild enthält:

  • Wer signieren soll (per E-Mail, UPN oder ID)

  • In welcher Iteration diese Person signiert

  • Wo im PDF die Signaturvisualisierung erscheinen soll (die Position des Bildes im Dokument)

  • Die erforderliche Signaturart (APPROVAL, QSIG usw.)

Da all diese Informationen im Bild kodiert sind, benötigt die an die API gesendete jobDescription lediglich das Feld constituent. Keine iterationData ist erforderlich.

7.2. Wesentlicher Unterschied zu Gruppenplatzhaltern


Persönlicher Platzhalter

Gruppenplatzhalter

Wer signieren kann

Eine bestimmte, namentlich genannte Person

Ein beliebiges Mitglied einer konfigurierten Gruppe

iterationData in der jobDescription

Nicht erforderlich

Erforderlich (muss auf die Gruppe verweisen)

Mehrere Instanzen in einem Dokument

Eine Autorisierung signiert alle Positionen gleichzeitig

Jeder Platzhalter erfordert eine separate Signaturaktion

Primärer Anwendungsfall

Individuelle, personenspezifische Signaturpositionen

Rollen- oder gruppenbasierte Signatur

Mehrere persönliche Platzhalter für dieselbe Person im selben Dokument führen dazu, dass die Signatur mit einer einzigen Signaturaktion an allen diesen Positionen visualisiert wird. Dies ist nützlich, um die Signatur an mehreren Stellen anzuzeigen (zum Beispiel einmal auf jeder Seite), ohne dass der Signer mehrfach zustimmen muss.


7.3. Minimale jobDescription

Bei der Übermittlung eines PDFs mit persönlichen Platzhaltern kann die jobDescription so minimal ausfallen:

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  }
}

MOXIS liest die Informationen zu Signer, Iteration und Position aus den in das PDF eingebetteten Platzhalterbildern.


7.4. Ein persönliches Platzhalterbild über die API generieren

Verwenden Sie den Endpunkt getPlaceholder, um einen persönlichen Platzhalter für einen bestimmten Benutzer zu generieren.

7.4.1. Für einen internen Benutzer (identifiziert per E-Mail):

GET <base-url>/getPlaceholder?iteration=0&signer=user.name@domain.com&signerType=PERSON&signatureType=APPROVAL&classifier=EMAIL

7.4.2. Für einen externen Signierenden:

GET <base-url>/getPlaceholder?iteration=0&signer=Username&signerType=PERSON&signatureType=EXTERNAL_APPROVAL&externalEmail=user.name@domain.com


Query-Parameter:

Parameter

Beschreibung

iteration

Integer, beginnend bei 0. Kodiert, zu welcher Iteration dieser Platzhalter gehört.

signer

Für interne Benutzer: die E-Mail-Adresse, UPN oder ID des Benutzers. Für externe Benutzer: der Anzeigename.

signerType

PERSON für persönliche Platzhalter

signatureType

APPROVAL oder QSIG für interne Benutzer; EXTERNAL_APPROVAL oder EXTERNAL_QSIG für externe Benutzer

classifier

Für interne Benutzer: EMAIL, UPN oder ID

externalEmail

Für externe Benutzer: die E-Mail-Adresse (zusammen mit dem Anzeigenamen in signer verwendet)

Die Antwort ist ein PNG-Bild. Betten Sie dieses Bild an jeder Stelle in Ihr PDF ein, an der die Signatur erscheinen soll.

Um die physische Größe des Platzhalterbildes zu steuern, verwenden Sie getPlaceholderWithSize mit dem zusätzlichen Parameter placeHolderSize (SMALL, MEDIUM oder LARGE):

GET <base-url>/getPlaceholderWithSize?iteration=0&signer=user.name@domain.com&signerType=PERSON&signatureType=APPROVAL&classifier=EMAIL&placeHolderSize=MEDIUM


7.5. Den Platzhalter in Ihrem PDF platzieren

Nachdem Sie das Platzhalterbild von der API herunterladen haben, betten Sie es mit Ihrem Werkzeug oder Ihrer Bibliothek zur Dokumentgenerierung (zum Beispiel iText, PDFBox oder einer Template-Engine) in Ihr PDF ein. Die Position des Bildes im PDF bestimmt, wo die Signaturvisualisierung erscheint.

Wird das PDF an MOXIS übermittelt, durchsucht die Plattform es nach eingebetteten Platzhalterbildern, extrahiert die EXIF-/QR-Daten und erstellt den Signatur-Workflow automatisch.


7.6. Vollständiges cURL-Beispiel: Ein PDF mit persönlichen Platzhaltern übermitteln

curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    }
  };type=application/json' \
  -F "documentToSign=@/path/to/document-with-personal-placeholders.pdf;type=application/pdf"

Bei Erfolg liefert MOXIS HTTP 201 Created mit der processInstanceId als reinen String.


7.7. Verhalten bei mehreren persönlichen Platzhaltern

Wenn Sie denselben persönlichen Platzhalter (gleicher Signer, gleiche Iteration) mehrfach in ein Dokument einbetten:

  • erhält der Signer eine einzige Signaturanfrage

  • nachdem er einmal signiert hat, erscheint die Signaturvisualisierung an jeder Stelle, an der der Platzhalter eingebettet war

  • dies wird manchmal als „Mehrfachvisualisierung“ bezeichnet

Dies unterscheidet sich von Gruppenplatzhaltern, bei denen jede eingebettete Instanz eine separate Signaturaktion erfordert.


7.8. Siehe auch

  • Gruppenplatzhalter: Platzhalterbilder für gruppen-/rollenbasierte Signatur

  • Mehrere Platzhalter: Kombination persönlicher und Gruppenplatzhalter in einem Dokument

  • Entwurf erstellen: Benutzergesteuerte Platzierung, wenn die Position nicht vorab bekannt ist

  • Create Job API-Referenz: Vollständige Parameterreferenz

8. PDF-Signaturfelder

PDF-Signaturfelder sind interaktive Formularelemente, die vom Dokumentautor direkt in ein PDF eingebettet werden, typischerweise mit Adobe Acrobat oder einem ähnlichen PDF-Autorenwerkzeug. Jedes Feld erhält bei seiner Erstellung einen eindeutigen Namen. Wird ein PDF mit eingebetteten Signaturfeldern an MOXIS übermittelt, kann das System diese Felder erkennen und ihnen über die API Signer zuweisen.


8.1. Wann verwenden Sie PDF-Signaturfelder am Besten?

Verwenden Sie PDF-Signaturfelder, wenn:

  • Ihre PDF-Dokumente bereits mit spezifischen Signaturfeldern erstellt wurden, die von Ihrem Design- oder Rechtsteam platziert wurden

  • Sie sicherstellen möchten, dass Signaturen genau an der richtigen Position eines komplexen Formulars landen, ohne rohe Koordinaten verwalten zu müssen

  • Ihr Dokument aus einer Vorlage mit bereits definierten Signaturblöcken stammt

MOXIS Tipp
Die Platzhalterauswertung (einschließlich der Erkennung von Signaturfeldern) kann von einem MOXIS-Administrator pro Prozess deaktiviert werden. Funktioniert die Übermittlung von Signaturfeldern nicht, prüfen Sie mit Ihrem Administrator, ob die Funktion für Ihren Prozess aktiviert ist.


8.2. Funktionsweise

  1. Ihr PDF wird mit einem oder mehreren Signaturfeldern erstellt, die an bestimmten Positionen eingebettet sind. Jedes Feld hat einen eindeutigen Zeichenfolgennamen (zum Beispiel Signature1 oder SignatureFieldCEO).

  1. In der jobDescription setzen Sie auf oberster Ebene "positionType": "SIGNATURE_FIELD".

  1. Für jeden Invitee verwenden Sie @class: com.xitrust.moxispe.api.UserForSignatureField (intern) oder com.xitrust.moxispe.api.ExternalUserForSignatureField (extern, ab MOXIS v4.53).

  2. MOXIS ordnet jedem Signer sein zugewiesenes Feld zu und platziert nach der Signatur die Signaturvisualisierung dort.

MOXIS Tipp
Feldnamen unterscheiden zwischen Groß- und Kleinschreibung. Signature1 und signature1 werden als unterschiedliche Felder behandelt. Prüfen Sie die exakten Feldnamen in Ihrem PDF, bevor Sie die jobDescription schreiben.


8.3. Felder Signierenden zuweisen

Es stehen zwei Modi zur Verfügung:

Alle Formularfelder einem Signierenden zuweisen:

"assignAllFormFields": true

Alle Formularfelder im Dokument werden diesem Signer zugewiesen. Verwenden Sie dies, wenn eine einzelne Person alle Felder signiert.

Bestimmte Felder anhand des Namens zuweisen:

"assignFormFields": ["SignatureField1", "SignatureField2"]

Nur die genannten Felder werden diesem Signer zugewiesen. Verwenden Sie dies, wenn mehrere Signer jeweils unterschiedliche Felder besitzen.


8.4. Interne Signierende: Beispiel jobDescription

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "SIGNATURE_FIELD",
  "metaData": {
    "description": "Demo SignatureField"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForSignatureField",
          "classifier": "EMAIL",
          "name": "internal.signer@yourdomain.com",
          "roleName": "moxisSigner",
          "signatureFieldName": "UniqueIdofFieldSignature1"
        }
      ],
      "category": "QSIG",
      "iterationNumber": 0
    }
  ]
}


8.5. Externe Signierende: Beispiel jobDescription (MOXIS v4.53+)

Ab MOXIS-Version 4.53 können externe Signer mithilfe der Klasse ExternalUserForSignatureField ebenfalls Signaturfeldern zugewiesen werden.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "SIGNATURE_FIELD",
  "metaData": {
    "description": "Demo External SignatureField"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUserForSignatureField",
          "classifier": "EMAIL",
          "name": "external.signer@example.com",
          "externalUserName": "External Signer",
          "roleName": "Extern",
          "locale": "en",
          "phoneNumber": "+43664123456",
          "signatureFieldName": "UniqueIdofFieldSignature1"
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 0
    }
  ]
}


MOXIS Tipp
ExternalUserForSignatureField erfordert MOXIS Version 4.53 oder höher. In früheren Versionen werden für die Zuweisung von Signaturfeldern nur interne Signer (UserForSignatureField) unterstützt.


8.6. Mehrere Signierende mit unterschiedlichen Feldern

Wenn Ihr PDF zwei Signaturfelder enthält (zum Beispiel SignatureFieldAuthor auf Seite 1 und SignatureFieldApprover auf Seite 3) können Sie jedes davon in separaten Iterationen an einen anderen Signierenden leiten:

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "SIGNATURE_FIELD",
  "metaData": {
    "description": "Two signers, two fields"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForSignatureField",
          "classifier": "EMAIL",
          "name": "author@yourdomain.com",
          "roleName": "moxisSigner",
          "signatureFieldName": "SignatureFieldAuthor"
        }
      ],
      "category": "QSIG",
      "iterationNumber": 0
    },
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForSignatureField",
          "classifier": "EMAIL",
          "name": "approver@yourdomain.com",
          "roleName": "moxisSigner",
          "signatureFieldName": "SignatureFieldApprover"
        }
      ],
      "category": "QSIG",
      "iterationNumber": 1
    }
  ]
}

Der Autor signiert zuerst (Iteration 0). Nachdem dieser die Signatur abgeschlossen hat, löst MOXIS automatisch den Prüfer aus (Iteration 1).


8.7. Vollständiges cURL-Beispiel

curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    },
    "positionType": "SIGNATURE_FIELD",
    "metaData": {
      "description": "Demo SignatureField"
    },
    "iterationData": [
      {
        "invitees": [
          {
            "@class": "com.xitrust.moxispe.api.UserForSignatureField",
            "classifier": "EMAIL",
            "name": "internal.signer@yourdomain.com",
            "roleName": "moxisSigner",
            "signatureFieldName": "UniqueIdofFieldSignature1"
          }
        ],
        "category": "QSIG",
        "iterationNumber": 0
      }
    ]
  };type=application/json' \
  -F "documentToSign=@/path/to/document-with-fields.pdf;type=application/pdf"


8.8 Siehe auch

  • Gruppenplatzhalter: Bildbasierter Platzhalteransatz für die Gruppensignatur

  • Direkte Position: Exakte Koordinaten angeben, ohne das PDF zu verändern

  • Create Job API-Referenz: Vollständige Parameterreferenz

9. Gruppenplatzhalter

Ein Gruppenplatzhalter ist eine Bilddatei, die die Gruppenzugehörigkeit und die Signaturiterationsdaten in ihren EXIF-Metadaten und einem eingebetteten QR-Code kodiert. Wird ein PDF mit einem oder mehreren Gruppenplatzhalterbildern an MOXIS übermittelt und ist der Prozess so konfiguriert, dass Platzhalter ausgewertet werden, liest MOXIS die kodierten Informationen automatisch aus und richtet den Signatur-Workflow entsprechend ein.

9.1. Was sind Gruppenplatzhalter?

Gruppenplatzhalter identifizieren eine MOXIS-Gruppe statt einer bestimmten Einzelperson. Jedes Mitglied der konfigurierten Gruppe kann an der durch den Platzhalter repräsentierten Position signieren. Dies ist nützlich, wenn Sie einen rollenbasierten Signatur-Workflow wünschen (zum Beispiel „ein beliebiger Teamleiter der Gruppe Approvals muss hier signieren“) ohne eine bestimmte Person fest zu kodieren.

Wesentliche Merkmale:

  • Das Platzhalterbild kodiert den Gruppennamen, die Signaturart und die Iterationsnummer in EXIF-Daten und einem QR-Code

  • Das Bild wird von Ihrem System zur Dokumentgenerierung in Ihr PDF eingebettet, bevor das PDF an MOXIS gesendet wird

  • Trifft das PDF bei MOXIS ein, durchsucht das System es nach Platzhaltern und extrahiert die Signaturanweisungen automatisch

  • Nach der Signatur ersetzt MOXIS das Platzhalterbild durch die tatsächliche Signaturvisualisierung

MOXIS Tipp
Die vom Platzhalter referenzierte Gruppe muss in MOXIS bereits existieren. Wird die Gruppe beim Übermitteln des PDFs nicht gefunden, schlägt der Aufruf fehl. Gruppen werden von MOXIS-Administratoren verwaltet.


9.2. Die Anzahl erforderlicher Signaturen konfigurieren

Hat Ihre Gruppe mehrere Mitglieder, können Sie festlegen, dass nur ein Teil davon signieren muss. Dies wird über das Feld numberOfSignatures in der iterationData gesteuert:

  • Setzen Sie numberOfSignatures auf die Anzahl der Mitglieder, die signieren müssen

  • Betten Sie entsprechend viele Gruppenplatzhalterbilder in Ihr PDF ein (ein Platzhalter = eine erforderliche Signaturaktion)

  • MOXIS sendet Signaturanfragen an die Gruppenmitglieder und betrachtet die Iteration als abgeschlossen, sobald die erforderliche Anzahl an Signaturen eingeholt wurde


9.3. Ein Gruppenplatzhalterbild über die API generieren

Sie können das Platzhalterbild programmatisch über den Endpunkt getPlaceholder generieren, statt es in der MOXIS-Admin-Oberfläche zu erstellen.

Standard-Gruppenplatzhalter:

GET <base-url>/getPlaceholder?iteration=0&signer=moxisApprover&signerType=GROUP&signatureType=APPROVAL&placeHolderText=insert-text

Gruppenplatzhalter für eine bestimmte Entra-/LDAP-Gruppe:

GET <base-url>/getPlaceholder?iteration=0&signer=Individual-MSEntra-Group-Name&signerType=GROUP&signatureType=APPROVAL&placeHolderText=eg-MSEntra

Query-Parameter:

Parameter

Beschreibung

iteration

Integer, beginnend bei 0. Muss mit der iterationNumber in Ihrer jobDescription übereinstimmen.

signer

Der Gruppen- oder Rollenname, wie in MOXIS konfiguriert (Groß-/Kleinschreibung beachten)

signerType

GROUP für Gruppenplatzhalter, oder ROLE für Rollenplatzhalter (siehe unten)

signatureType

Signaturqualität: APPROVAL, QSIG, EXTERNAL_APPROVAL oder EXTERNAL_QSIG

placeHolderText

Auf dem Platzhalterbild angezeigter Beschriftungstext

9.3.1. GROUP- vs. ROLE-Platzhalter

signerType unterstützt zwei gruppenähnliche Werte:

  • GROUP: Verweist auf eine bestimmte MOXIS-Gruppe (z. B. eine synchronisierte Entra-/LDAP-Gruppe). Jedes Mitglied dieser Gruppe kann signieren.

  • ROLE: Verweist auf einen Basis- oder benutzerdefinierten Rollennamen (z. B. moxisSigner, oder die externe Rolle Extern) statt auf eine benannte Gruppe. So werden auch rollenbasierte Platzhalter für externe Signer generiert:

  GET <base-url>/getPlaceholder?iteration=0&signer=Extern&signerType=ROLE&signatureType=EXTERNAL_APPROVAL


ROLE-Platzhalter sind nicht auf interne Benutzer beschränkt — eine externe Rolle wie Extern kann auf dieselbe Weise referenziert werden wie eine interne Rolle wie moxisSigner.

Die Antwort ist eine PNG-Bilddatei. Betten Sie dieses Bild an der Stelle in Ihr PDF ein, an der die Signatur erscheinen soll.

Um die physische Größe des Platzhalters zu steuern, verwenden Sie getPlaceholderWithSize und fügen Sie den Parameter placeHolderSize hinzu (SMALL, MEDIUM oder LARGE):

GET <base-url>/getPlaceholderWithSize?iteration=0&signer=moxisApprover&signerType=GROUP&signatureType=APPROVAL&placeHolderText=insert-text&placeHolderSize=MEDIUM


9.4. jobDescription für die Signatur mit Gruppenplatzhalter

Da die Positions- und Iterationsinformationen bereits im in das PDF eingebetteten Platzhalterbild kodiert sind, ist positionType in der jobDescription nicht erforderlich (automatisch wird das Standardverhalten ON_PLACEHOLDER verwendet). Sie müssen jedoch die Gruppe in iterationData referenzieren, indem Sie die Klasse UserForRole verwenden und roleName auf den Gruppennamen setzen.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Demo GroupPlaceholder"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "group.member@yourdomain.com",
          "roleName": "moxisSigner"
        }
      ],
      "category": "QSIG",
      "iterationNumber": 0
    }
  ]
}

In diesem Beispiel stimmt roleName mit dem Gruppennamen überein, der beim Generieren des Platzhalterbildes verwendet wurde. Das Feld name referenziert einen bestimmten Benutzer innerhalb dieser Gruppe.

Für ein Szenario, bei dem 2 von 3 Gruppenmitgliedern signieren müssen, betten Sie 2 Gruppenplatzhalterbilder in das PDF ein und setzen Sie numberOfSignatures: 2:

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "2 of 3 group members must sign"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "member1@yourdomain.com",
          "roleName": "ApprovalGroup"
        },
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "member2@yourdomain.com",
          "roleName": "ApprovalGroup"
        },
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "member3@yourdomain.com",
          "roleName": "ApprovalGroup"
        }
      ],
      "numberOfSignatures": 2,
      "category": "APPROVAL",
      "iterationNumber": 0
    }
  ]
}


9.5. Vollständiges cURL-Beispiel

curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.User"
    },
    "metaData": {
      "description": "Demo GroupPlaceholder"
    },
    "iterationData": [
      {
        "invitees": [
          {
            "@class": "com.xitrust.moxispe.api.UserForRole",
            "classifier": "EMAIL",
            "name": "group.member@yourdomain.com",
            "roleName": "moxisSigner"
          }
        ],
        "category": "QSIG",
        "iterationNumber": 0
      }
    ]
  };type=application/json' \
  -F "documentToSign=@/path/to/document-with-placeholder.pdf;type=application/pdf"


9.6. Wesentliche Unterschiede zu persönlichen Platzhaltern


Gruppenplatzhalter

Persönlicher Platzhalter

Wer signieren kann

Ein beliebiges Mitglied der Gruppe

Eine bestimmte, namentlich genannte Person

invitees in der jobDescription

Erforderlich: Referenzierung der Gruppe über roleName

Nicht erforderlich: Im Bild kodiert

Mehrere Platzhalter in einem Dokument

Jeder Platzhalter erfordert eine separate Signaturaktion

Mehrere Platzhalter = eine Signatur, mehrfach visualisiert

Benutzertyp

Intern (GROUP); intern oder extern (ROLE)

Intern oder extern

9.7. Siehe auch

  • Persönliche Platzhalter: Individuenspezifische Platzhalterbilder

  • Mehrere Platzhalter: Kombination persönlicher und Gruppenplatzhalter

  • Signaturfelder: Eingebettete PDF-Formularfelder als Signaturpositionen

  • Create Job API-Referenz: Vollständige Parameterreferenz


10. Mehrere Platzhalter in einem Dokument

MOXIS unterstützt das Einbetten mehrerer Platzhalterbilder in ein einzelnes PDF. Das Verhalten hängt von der Art des verwendeten Platzhalters und deren Kombination ab. Das Verständnis dieser Regeln hilft Ihnen, den richtigen Workflow für Dokumente zu entwerfen, die mehr als eine Signaturposition benötigen.


10.1. Verhalten nach Platzhaltertyp

10.1.1. Mehrere persönliche Platzhalter (gleicher Signer, gleiche Iteration)

Betten Sie denselben persönlichen Platzhalter mehrfach in ein Dokument ein (gleiche Person, gleiche Iterationsnummer), ist das Ergebnis:

  • Der Signierende erhält eine einzige Signaturanfrage

  • Er signiert einmal

  • Die Signaturvisualisierung erscheint an jeder Stelle, an der der Platzhalter eingebettet war

Dies ist nützlich, wenn die Signatur aus visuellen oder Referenzgründen an mehreren Stellen erscheinen soll (zum Beispiel auf jeder Seite eines mehrseitigen Vertrags, oder sowohl in der Kopf- als auch in der Fußzeile), ohne dass der Signer jede Position einzeln explizit autorisieren muss.

MOXIS Tipp
Die jobDescription für dieses Szenario benötigt lediglich das Feld constituent. Keine iterationData ist erforderlich, da alle Signer- und Iterationsinformationen bereits in den Platzhalterbildern selbst kodiert sind.


Minimale jobDescription:

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  }
}


Mehrere Gruppenplatzhalter (gleiche Iteration)

Betten Sie denselben Gruppenplatzhalter mehrfach in ein Dokument ein (gleiche Gruppe, gleiche Iteration), ist das Ergebnis:

  • Jeder Platzhalter repräsentiert eine separate Signaturaktion

  • Jedes Gruppenmitglied, das signiert, füllt eine Platzhalterposition

  • Die Anzahl der Platzhalterbilder im Dokument bestimmt, wie viele Signaturen erforderlich sind

So implementiert MOXIS das „N von M“-Signaturmodell für Gruppen. Um 2 Signaturen aus einer Gruppe von 5 Mitgliedern zu verlangen, betten Sie das Gruppenplatzhalterbild zweimal in das PDF ein und konfigurieren Sie numberOfSignatures: 2 in der iterationData.


Kombination persönlicher und Gruppenplatzhalter

Persönliche und Gruppenplatzhalter können nicht innerhalb derselben Iteration gemischt werden. Um beide in einem Dokument zu verwenden, weisen Sie sie separaten Iterationen zu.

  • Iteration 0: Signatur mit Gruppenplatzhalter

  • Iteration 1: Signatur mit persönlichem Platzhalter (oder umgekehrt)

MOXIS verarbeitet Iterationen sequenziell. Das heißt, Iteration 1 beginnt erst, wenn Iteration 0 abgeschlossen ist.


10.2. Vollständiges JSON-Beispiel: Gruppe in Iteration 0, persönlich in Iteration 1

Dieses Beispiel aus der MOXIS-API-Dokumentation zeigt einen kombinierten Job. Zwei externe Prüfer signieren in Iteration 0 über einen Gruppenplatzhalter (beide referenzieren dieselbe Gruppenrolle). Ein persönlicher Platzhalter steuert Iteration 1 (der iterationData-Eintrag ist für den externen Signer enthalten, die Position wird jedoch aus dem Platzhalterbild im PDF gelesen).

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Combination: group placeholder (iteration 0) and personal placeholder (iteration 1)",
    "referenceId": "null"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalApproverForRole",
          "classifier": "EMAIL",
          "name": "approver1@yourdomain.com",
          "roleName": "Extern",
          "externalUserName": "Approver One (extern)"
        },
        {
          "@class": "com.xitrust.moxispe.api.ExternalApproverForRole",
          "classifier": "EMAIL",
          "name": "approver2@yourdomain.com",
          "roleName": "Extern",
          "externalUserName": "Approver Two (extern)"
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 0
    }
  ]
}

MOXIS Tipp
Iteration 1 (der persönliche Platzhalter) benötigt keinen Eintrag in iterationData — die Identität des Signers und die Position werden aus dem in das PDF eingebetteten Platzhalterbild gelesen. MOXIS erstellt die Signaturanfrage für Iteration 1 automatisch, sobald Iteration 0 abgeschlossen ist.


10.3. Vollständiges JSON-Beispiel: Mehrfachplatzhalter (interne Gruppe, 2 von 3 erforderlich)

Dieses Beispiel zeigt, wie 2 von 3 internen Prüfern zur Signatur verpflichtet werden, indem mehrere Gruppenplatzhalter in das PDF eingebettet werden.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@yourdomain.com",
    "@class": "com.xitrust.moxispe.api.UserForRole"
  },
  "metaData": {
    "description": "Demo multi-placeholder",
    "referenceId": "123456",
    "customMap": { "key": "value" }
  },
  "iterationData": [
    {
      "invitees": [
        {
          "classifier": "EMAIL",
          "name": "approver1@yourdomain.com",
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "roleName": "moxisApprover"
        },
        {
          "classifier": "EMAIL",
          "name": "approver2@yourdomain.com",
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "roleName": "moxisApprover"
        },
        {
          "classifier": "EMAIL",
          "name": "approver3@yourdomain.com",
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "roleName": "moxisApprover"
        }
      ],
      "numberOfSignatures": 2,
      "iterationNumber": 0
    }
  ]
}

Mit dieser Konfiguration und zwei in das PDF eingebetteten Gruppenplatzhalterbildern:

  • Alle drei Prüfer erhalten eine Signatureinladung

  • Sobald 2 von ihnen signiert haben, gilt die Iteration als abgeschlossen

  • Jeder Signierende füllt eine der beiden eingebetteten Platzhalterpositionen


10.4. Vollständiges cURL-Beispiel

curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -F 'jobDescription={
    "constituent": {
      "classifier": "EMAIL",
      "name": "owner@yourdomain.com",
      "@class": "com.xitrust.moxispe.api.UserForRole"
    },
    "metaData": {
      "description": "Demo multi-placeholder",
      "referenceId": "123456",
      "customMap": { "key": "value" }
    },
    "iterationData": [
      {
        "invitees": [
          {
            "classifier": "EMAIL",
            "name": "approver1@yourdomain.com",
            "@class": "com.xitrust.moxispe.api.UserForRole",
            "roleName": "moxisApprover"
          },
          {
            "classifier": "EMAIL",
            "name": "approver2@yourdomain.com",
            "@class": "com.xitrust.moxispe.api.UserForRole",
            "roleName": "moxisApprover"
          },
          {
            "classifier": "EMAIL",
            "name": "approver3@yourdomain.com",
            "@class": "com.xitrust.moxispe.api.UserForRole",
            "roleName": "moxisApprover"
          }
        ],
        "numberOfSignatures": 2,
        "iterationNumber": 0
      }
    ]
  };type=application/json' \
  -F "documentToSign=@/path/to/document-with-placeholders.pdf;type=application/pdf"


10.5. Zusammenfassung der Regeln

Szenario

Verhalten

iterationData erforderlich?

Mehrere persönliche Platzhalter, gleicher Signer, gleiche Iteration

1 Signaturaktion; Signatur erscheint an allen Positionen

Nein

Mehrere Gruppenplatzhalter, gleiche Iteration

1 Signaturaktion pro Platzhalter

Ja

Persönlich + Gruppe in derselben Iteration

Nicht unterstützt

—

Persönlich + Gruppe in unterschiedlichen Iterationen

Unterstützt; sequenziell verarbeitet

Gruppen-Iteration benötigt Invitees; persönliche Iteration nicht

10.6. Siehe auch

  • Persönliche Platzhalter: Erstellung und Verwendung persönlicher Platzhalterbilder

  • Gruppenplatzhalter: Erstellung und Verwendung von Gruppenplatzhalterbildern

  • Create Job API-Referenz: Vollständige Parameterreferenz


11. InstantSign für interne Benutzer

11.1. Was ist InstantSign für interne Benutzer?

InstantSign ist eine vereinfachte, einbildschirmige Signaturansicht für interne MOXIS-Benutzer. Wie die externalSignerUrl für externe Signer bietet InstantSign eine fokussierte Oberfläche, die als <iframe> in Ihre eigene Anwendung eingebettet werden kann, sodass interne Benutzer ihre Signaturtransaktion abschließen können, ohne zum vollständigen MOXIS-Portal navigieren zu müssen.

Interne Benutzer authentifizieren sich üblicherweise über den Identity Provider (IdP) Ihrer Organisation, etwa Microsoft Entra (früher Azure AD).

MOXIS Tipp
InstantSign ist standardmäßig nicht aktiviert. Wenden Sie sich an MOXIS, um diese Funktion für Ihre MOXIS-Instanz aktivieren zu lassen. InstantSign gilt ausschließlich für interne Benutzer. Externe Signierende (Gäste) verwenden stattdessen externalSignerUrl (siehe External Signer URL).


11.2. So rufen Sie die InstantSign-URL ab

Nachdem Sie einen Job mit POST startProcess erstellt haben, rufen Sie GET getJobState auf, um den aktuellen Job-Status auszulesen. Die instantSignUrl wird für jeden internen Invitee der aktuellen Iteration innerhalb von iterations[].invitees[] zurückgegeben.

GET <base-url>/getJobState/{processInstanceId}/{nameClassifier

Parameter

Beschreibung

processInstanceId

Die beim Erstellen des Jobs zurückgegebene ID

nameClassifier

E-Mail, UPN oder ID des anfragenden Benutzers

11.3. Antwort: instantSignUrl finden

Suchen Sie nach Invitees mit einer internen Benutzerklasse (z. B. com.xitrust.moxispe.api.Signer) im Array iterations[].invitees[]. Das Feld instantSignUrl enthält den Signaturlink, wenn die Funktion aktiviert ist.

{
  "state": "PROCESSING",
  "processId": "customer100",
  "processInstanceId": "277764",
  "jobMetaData": {
    "description": "Jobstate example",
    "category": null,
    "expirationDate": "2024-08-17T21:59:59.849+00:00",
    "referenceId": null,
    "customMap": {
      "key": "value"
    },
    "externalPassword": null
  },
  "creationDate": "2024-06-18T11:54:48.471+00:00",
  "endDate": null,
  "currentIteration": 0,
  "iterations": [
    {
      "numberOfSignatures": 1,
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.Signer",
          "classifier": "UPN",
          "name": "user.name@domain.com",
          "directUserPosition": null,
          "directUserPositions": null,
          "assignFormFields": [],
          "assignAllFormFields": false,
          "visualizationPlacementRequired": false,
          "customMap": {},
          "action": null,
          "actionDate": null,
          "comments": null,
          "instantSignUrl": "https://your-moxis-instance/instant-sign/task/277764/f3eba906-9879-42ce-a331-0224b32e8954"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0,
      "remark": null,
      "signerGroup": null,
      "privateIteration": null,
      "customMap": {},
      "groupPositions": null
    },
    {
      "numberOfSignatures": 1,
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalSigner",
          "classifier": "UPN",
          "name": "user.name@domain.com",
          "directUserPosition": null,
          "directUserPositions": null,
          "assignFormFields": [],
          "assignAllFormFields": false,
          "visualizationPlacementRequired": false,
          "customMap": {},
          "action": null,
          "actionDate": null,
          "comments": null,
          "instantSignUrl": null,
          "externalSignerName": "User Name extern",
          "externalSignerEmail": "user.name@domain.com",
          "externalSignerUrl": "https://your-moxis-instance/guest/job/b6655956-f433-46d1-9498-57283b4c86ca",
          "externalSignerQrCodeDownloadUrl": "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getQrCodeForExternalMeqaSigner/277902/9f62b365-db7c-42bf-99df-a418e40441fb",
          "externalDownloadUrl": "https://your-moxis-instance/guest/job/b6655956-f433-46d1-9498-57283b4c86ca"
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 1,
      "remark": null,
      "signerGroup": null,
      "privateIteration": null,
      "customMap": {},
      "groupPositions": null
    }
  ],
  "additionalRecipients": [],
  "owner": "user.name@domain.com",
  "customMap": {}
}

Beachten Sie bitte in diesem Beispiel:
- Iteration 0 (interner Benutzer, com.xitrust.moxispe.api.Signer) hat eine befüllte instantSignUrl und externalSignerUrl: null.
- Iteration 1 (externer Benutzer, com.xitrust.moxispe.api.ExternalSigner) hat instantSignUrl: null und eine befüllte externalSignerUrl.


11.4. Einbettung in ein iframe

Zeigen Sie die InstantSign-URL innerhalb Ihrer Anwendung an, damit der interne Benutzer signieren kann, ohne Ihr Produkt zu verlassen:

HTML
<iframe
  src="https://your-moxis-instance/instant-sign/task/277764/f3eba906-9879-42ce-a331-0224b32e8954"
  width="100%"
  height="800px"
  frameborder="0"
  title="Sign document">
</iframe>

Der Benutzer wird zur Authentifizierung über Ihren konfigurierten IdP (z. B. Entra SSO) aufgefordert, falls er noch nicht angemeldet ist.

MOXIS Tipp
Bestätigen Sie mit Ihrem MOXIS-Ansprechpartner, dass die MOXIS-Instanz die iframe-Einbettung von der Domain Ihrer Anwendung zulässt.


11.5. Nach der Signatur

Sobald der interne Signer die Transaktion in der InstantSign-Ansicht abgeschlossen hat:

  1. Das signierte Dokument ist im regulären MOXIS-Konto des Benutzers unter der Standard-Dokumentliste verfügbar.

  1. Der Job wechselt zur nächsten Iteration oder in den Status FINISHED_SUCCESS, wenn alle Iterationen abgeschlossen sind.

  1. Ihre Anwendung kann GET getJobState abfragen oder eine Webhook-Benachrichtigung (Enterprise-Stufe) erhalten, um den Abschluss zu erkennen und das signierte PDF abzurufen. Siehe Fetching Documents.


11.6. Interne Benutzerklassen, die instantSignUrl erhalten

@class

Beschreibung

com.xitrust.moxispe.api.User

Standard-interner Benutzer, identifiziert per E-Mail, UPN oder ID

com.xitrust.moxispe.api.UserForRole

Interner Benutzer, referenziert über Rollen- oder Gruppenname

Externe Benutzerklassen (ExternalUser, ExternalUserForRole) haben stets instantSignUrl: null und erhalten stattdessen eine externalSignerUrl.

11.7. Verwandte Themen

  • External Signer URL: Entsprechende vereinfachte Ansicht für externe Signierende

  • Fetching Documents: Das signierte PDF nach Abschluss abrufen

  • Signature Iterations: Signatur-Workflows mit mehreren Signierenden orchestrieren


12. External Signer URL (MOXIS Guest für externe Signierende)

12.1. Was ist MOXIS Guest für externe Signierende?

Enthält ein MOXIS-Job externe Signer, generiert MOXIS für jeden externen Invitee in jeder Iteration eine eindeutige URL. Der Aufruf dieses Links öffnet MOXIS Guest für externe Signierende eine vereinfachte Signaturansicht für Personen, die kein reguläres MOXIS-Konto besitzen.

Diese URL kann:

  • direkt an den Signer gesendet werden (MOXIS versendet sie standardmäßig automatisch per E-Mail)

  • als <iframe> in Ihre eigene Anwendung eingebettet werden, sodass externe Signer signieren können, ohne Ihr Produkt zu verlassen

Nach Abschluss der Signaturtransaktion kann der externe Signer das signierte Dokument über dieselbe URL ansehen und herunterladen. Der Download-Zugriff kann von Ihrem MOXIS-Administrator eingeschränkt werden.

MOXIS Tipp
externalSignerUrl wird nur für Invitees generiert, deren @class eine externe Benutzerklasse ist — konkret com.xitrust.moxispe.api.ExternalUser oder com.xitrust.moxispe.api.ExternalUserForRole. Interne Benutzer erhalten stattdessen eine instantSignUrl. Siehe InstantSign für das entsprechende Gegenstück für interne Benutzer.


12.2. So rufen Sie die URL ab

Nachdem Sie einen Job mit POST startProcess erstellt haben, rufen Sie GET getJobState auf, um den aktuellen Job-Status auszulesen. Die externalSignerUrl wird für jeden externen Invitee der aktuellen Iteration innerhalb von iterations[].invitees[] zurückgegeben.

GET <base-url>/getJobState/{processInstanceId}/{nameClassifier}

Parameter

Beschreibung

processInstanceId

Die beim Erstellen des Jobs zurückgegebene ID

nameClassifier

E-Mail, UPN oder ID des anfragenden Benutzers


12.3. Antwort: externalSignerUrl finden

Die relevanten Felder in der getJobState-Antwort befinden sich verschachtelt unter iterations[].invitees[]. Suchen Sie nach Invitees mit @class: "com.xitrust.moxispe.api.ExternalSigner".

{
  "state": "PROCESSING",
  "processId": "customer100",
  "processInstanceId": "277764",
  "jobMetaData": {
    "description": "Jobstate example",
    "category": null,
    "expirationDate": "2024-08-17T21:59:59.849+00:00",
    "referenceId": null,
    "customMap": {
      "key": "value"
    },
    "externalPassword": null
  },
  "creationDate": "2024-06-18T11:54:48.471+00:00",
  "endDate": null,
  "currentIteration": 0,
  "iterations": [
    {
      "numberOfSignatures": 1,
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.Signer",
          "classifier": "UPN",
          "name": "user.name@domain.com",
          "directUserPosition": null,
          "directUserPositions": null,
          "assignFormFields": [],
          "assignAllFormFields": false,
          "visualizationPlacementRequired": false,
          "customMap": {},
          "action": null,
          "actionDate": null,
          "comments": null,
          "instantSignUrl": "https://your-moxis-instance/instant-sign/task/277764/f3eba906-9879-42ce-a331-0224b32e8954"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0,
      "remark": null,
      "signerGroup": null,
      "privateIteration": null,
      "customMap": {},
      "groupPositions": null
    },
    {
      "numberOfSignatures": 1,
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalSigner",
          "classifier": "UPN",
          "name": "user.name@domain.com",
          "directUserPosition": null,
          "directUserPositions": null,
          "assignFormFields": [],
          "assignAllFormFields": false,
          "visualizationPlacementRequired": false,
          "customMap": {},
          "action": null,
          "actionDate": null,
          "comments": null,
          "instantSignUrl": null,
          "externalSignerName": "User Name",
          "externalSignerEmail": "user.name@domain.com",
          "externalSignerUrl": "https://your-moxis-instance/guest/job/b6655956-f433-46d1-9498-57283b4c86ca",
          "externalSignerQrCodeDownloadUrl": "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getQrCodeForExternalMeqaSigner/277902/9f62b365-db7c-42bf-99df-a418e40441fb",
          "externalDownloadUrl": "https://your-moxis-instance/guest/job/b6655956-f433-46d1-9498-57283b4c86ca"
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 1,
      "remark": null,
      "signerGroup": null,
      "privateIteration": null,
      "customMap": {},
      "groupPositions": null
    }
  ],
  "additionalRecipients": [],
  "owner": "user.name@domain.com",
  "customMap": {}
}


12.3.1. Wichtige Felder erklärt

Feld

Beschreibung

externalSignerUrl

Die URL zum Öffnen von MOXIS Guest für diesen Signer. Präsentieren Sie diesen Link dem externen Benutzer oder betten Sie ihn in ein iframe ein.

externalDownloadUrl

Die URL, unter der der externe Signierende das fertige signierte Dokument nach der Signatur herunterladen kann.

externalSignerName

Anzeigename des externen Signierenden, wie in der Job-Beschreibung angegeben.

externalSignerEmail

E-Mail-Adresse des externen Signierenden.

externalSignerQrCodeDownloadUrl

Veraltet. Dieses Feld wurde mit dem Legacy-System MEQA verwendet, das durch MOXIS Guest für externe Signierende ersetzt wurde. Verwenden Sie diese URL in neuen Integrationen nicht.


12.4. Einbettung in ein iframe

Um den Signaturbildschirm innerhalb Ihrer Anwendung anzuzeigen, ohne den Benutzer weiterzuleiten:

HTML
<iframe
  src="https://your-moxis-instance/guest/job/b6655956-f433-46d1-9498-57283b4c86ca"
  width="100%"
  height="800px"
  frameborder="0"
  allow="camera"
  title="Sign document">
</iframe>

MOXIS Tipp
Einige Browser schränken die iframe-Einbettung von Drittanbieter-Origins ein. Bestätigen Sie mit Ihrem MOXIS-Ansprechpartner, dass die MOXIS-Instanz für die Einbettung von der Domain Ihrer Anwendung konfiguriert ist.


12.5. Nach der Signatur

Sobald der externe Signer die Transaktion in MOXIS Guest abgeschlossen hat:

  1. Der Job wechselt zur nächsten Iteration (falls vorhanden) oder in den Status FINISHED_SUCCESS, wenn alle Iterationen abgeschlossen sind.

  1. Der Signer kann das signierte Dokument über dieselbe externalDownloadUrl ansehen und herunterladen. Der Administrator kann die Download-Verfügbarkeit einschränken.

  1. Ihre Anwendung kann GET getJobState abfragen oder eine Webhook-Benachrichtigung (Enterprise-Stufe) erhalten, um die Statusänderung zu erkennen und das fertige Dokument abzurufen. Siehe Fetching Documents.


12.6. Anforderungen an die Benutzerklasse

Die externalSignerUrl wird nur generiert, wenn der Invitee in der jobDescription iterationData mit einer externen Benutzerklasse deklariert ist. Die unterstützten externen Klassen sind:

@class

Wann verwenden

com.xitrust.moxispe.api.ExternalUser

Externer Signer ohne Gruppen-/Rollenkontext

com.xitrust.moxispe.api.ExternalUserForRole

Externer Signer, platziert über eine vorkonfigurierte Rolle oder einen Gruppenplatzhalter

Interne Benutzer (com.xitrust.moxispe.api.User, com.xitrust.moxispe.api.UserForRole) haben externalSignerUrl: null und erhalten stattdessen eine instantSignUrl. Siehe InstantSign.


12.7. Verwandte Themen

  • InstantSign: Vereinfachte Signaturansicht für interne Benutzer

  • Fetching Documents: Das signierte PDF nach Abschluss abrufen

  • Metadata and Custom Data: Passwörter, Weiterleitungs-URLs und weitere Job-Optionen für externe Signer festlegen


13. Metadaten und benutzerdefinierte Daten

MOXIS bietet mehrere optionale Felder in der Job-Beschreibung, mit denen Sie eigene Daten anhängen, den Job-Lebenszyklus steuern und Sonderfälle für externe Signer behandeln können. Diese Anleitung behandelt jede Option mit Beispielen, die Sie direkt in Ihre Integration übernehmen können.

Alle hier beschriebenen Felder werden in dem jobDescription-JSON gesetzt, das Sie mit POST startProcess (oder POST createDraft) übermitteln.


13.1. referenceId

13.1.1. Was ist die referenceId?

referenceId ist ein optionales String-Feld innerhalb von metaData, mit dem Sie die Kennung Ihres eigenen Systems an einen MOXIS-Job anhängen können. Verwenden Sie es, um MOXIS-Jobs mit Datensätzen in Ihrer Datenbank, Ihrem CRM, ERP oder einem anderen System zu verknüpfen.

Sobald gesetzt, ist die Referenz-ID als Query-Parameter in GET lookupJobStates und als Pfad-Parameter in den *ByReferenceId-API-Methoden verfügbar (ab MOXIS v4.52).

MOXIS Tipp
MOXIS erzwingt bei der Job-Erstellung keine Eindeutigkeit von referenceId. Ihre Integration ist dafür verantwortlich, Eindeutigkeit sicherzustellen, wenn Sie eine eindeutige, referenzbasierte Abfrage benötigen. Bitte beachten Sie: Die referenceId ist nur in Job-Detailansichten und API-Antworten sichtbar. Sie erscheint nicht in den Standard-Kachelansichten der MOXIS-Benutzeroberfläche.


13.1.2. Beispiel

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Demo ReferenceId",
    "referenceId": "Ref123456"
  }
}

Jobs anhand der referenceId abrufen

Nachdem Sie eine referenceId gesetzt haben, können Sie Jobs abfragen und Dokumente abrufen, ohne die MOXIS-processInstanceId speichern zu müssen:

GET <base-url>/getJobStateByReferenceId/{referenceId}/{nameClassifier}
GET <base-url>/getDocumentByReferenceId/{referenceId}
GET <base-url>/getAttachmentsByReferenceId/{referenceId}
GET <base-url>/getMultisignDocumentsByReferenceId/{referenceId}

Sie können lookupJobStates auch nach Referenz-ID filtern:

GET <base-url>/lookupJobStates?referenceId=Ref123456


13.2. customMap

13.2.1. Was ist die customMap?

customMap ist ein freiformatiges Schlüssel-Wert-Objekt, das Sie an einen Job anhängen können, um beliebige Daten aus Ihrem System durch MOXIS hindurchzuführen. Die Werte werden in Webhook-Payloads und getJobState-Antworten zurückgegeben, was ein „Fire-and-forget“-Muster ermöglicht, bei dem Ihr System keine separate Zuordnungstabelle pflegen muss.

customMap kann auf zwei Ebenen gesetzt werden:

  • Ebene metaData: gilt für den gesamten Job

  • Ebene iterationData: gilt für eine bestimmte Signaturiteration

MOXIS Tipp
Daten aus customMap erscheinen nicht in der MOXIS-Benutzeroberfläche.


13.2.2. Beispiel (customMap auf Job-Ebene)

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Demo CustomMap",
    "referenceId": "Ref123456",
    "customMap": {
      "ID": "123",
      "key": "value",
      "status": "active",
      "changed": true
    }
  }
}

Beispiel (customMap auf Iterationsebene)

{
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "roleName": "moxisSigner"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0,
      "customMap": {
        "approvalRound": "1",
        "department": "finance"
      }
    }
  ]
}


13.3. expirationDate

13.3.1. Was ist das expirationDate?

expirationDate steuert, wie lange ein Job in MOXIS aktiv bleibt, bevor er automatisch abläuft. Sobald das Ablaufdatum erreicht ist, wechselt der Job in den Status FINISHED_TIMEOUT und wird von MOXIS irgendwann gelöscht.

Geben Sie diesen Wert im ISO-8601-Format an: yyyy-MM-ddTHH:mm:ssTZD.

MOXIS Tipp
Rufen Sie Ihre signierten Dokumente vor dem Ablaufdatum ab. Nach der Löschung können Dokumente über die API nicht wiederhergestellt werden. Siehe Fetching Documents.


13.3.2. Beispiel

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Contract with deadline",
    "expirationDate": "2024-12-31T23:59:59+01:00"
  }
}


13.4. externalPassword

13.4.1. Was ist das externalPassword?

Greift ein externer Signer auf MOXIS Guest für externe Signierende zu und ist keine Telefonnummer bekannt (das heißt, SMS-TAN-Authentifizierung steht nicht zur Verfügung), können Sie ein statisches Passwort angeben, das der Signer zum Zugriff auf das Dokument eingeben muss. Dieses Passwort wird im Block metaData der Job-Beschreibung gesetzt.

MOXIS Tipp
Ist für den externen Signierenden eine phoneNumber konfiguriert, ist SMS-TAN die bevorzugte Authentifizierungsmethode. Verwenden Sie externalPassword nur, wenn die telefonbasierte Authentifizierung nicht verfügbar oder nicht gewünscht ist.


13.4.2. Beispiel

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Example with external Password MOXIS Guest User",
    "externalPassword": "Abcd1234!"
  },
  "positionType": "DIRECT_POSITION",
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "externalUserName": "User Name",
          "roleName": "Extern",
          "locale": "de",
          "directUserPosition": {
            "x": "66",
            "y": "510",
            "width": "225",
            "height": "80",
            "pageNumber": 1
          }
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 0
    }
  ]
}


13.5. externalNoMail: Externe Signierende ohne E-Mail-Adresse

13.5.1. Was ist externalNoMail?

In manchen Workflows ist die E-Mail-Adresse des externen Signers zum Zeitpunkt der Job-Erstellung nicht bekannt. Lassen Sie in diesem Fall das Feld name (E-Mail) beim Invitee weg und verwenden Sie stattdessen die phoneNumber zur Identifikation und Authentifizierung per SMS-TAN.

Wird keine E-Mail-Adresse angegeben, sendet MOXIS keine automatische Einladungs-E-Mail. Ihre Anwendung ist dafür verantwortlich, dem Signer die externalSignerUrl auf anderem Weg zukommen zu lassen (zum Beispiel durch Einbettung in Ihre App oder Versand per SMS oder einem anderen Kanal).


13.5.2. Beispiel

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "SIGNATURE_PAGE",
  "metaData": {
    "description": "no Mail"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
          "classifier": "UPN",
          "externalUserName": "User Name",
          "phoneNumber": "+43664123456",
          "roleName": "Extern"
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 0
    }
  ]
}

MOXIS Tipp
In diesem Beispiel fehlt das Feld name beim Invitee. Die phoneNumber wird für die SMS-TAN-Authentifizierung in MOXIS Guest für externe Signierende verwendet.


13.6. Zusätzliche Empfänger

13.6.1. Was sind “zusätzliche Empfänger”?

Zusätzliche Empfänger sind Personen, die das fertige Dokument und Benachrichtigungs-E-Mails erhalten, aber nicht am Signatur-Workflow beteiligt sind — sie signieren oder genehmigen nicht. Dies ist nützlich für Verteilerlisten, CC-Empfänger, Compliance-Beauftragte oder jeden, der eine Kopie des endgültigen signierten Dokuments benötigt.

Zusätzliche Empfänger werden im Array additionalRecipients auf oberster Ebene der Job-Beschreibung (außerhalb von iterationData) definiert.


13.6.2. Beispiel

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "INVISIBLE",
  "metaData": {
    "description": "Demo AdditionalRecipients"
  },
  "additionalRecipients": [
    {
      "@class": "com.xitrust.moxispe.api.AddressBookEntry",
      "name": "User Name extern",
      "email": "user.name@domain.com",
      "phoneNumber": "+43664123456",
      "locale": "de"
    }
  ],
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "roleName": "moxisSigner"
        }
      ],
      "category": "EXTERNAL_QSIG",
      "iterationNumber": 0
    }
  ]
}


13.6.3. Felder für zusätzliche Empfänger

Feld

Typ

Beschreibung

@class

String

Für externe Empfänger com.xitrust.moxispe.api.AddressBookEntry verwenden

name

String

Anzeigename des Empfängers

email

String

E-Mail-Adresse, an die Benachrichtigung und Dokumentlink gesendet werden

phoneNumber

String

Optionale Telefonnummer

locale

String

Sprache für E-Mail-Benachrichtigungen (z. B. "de", "en")


13.7. Weiterleitungs-URL

13.7.1. Was ist die “Weiterleitungs-URL”?

Nachdem ein externer Signierender seine Transaktion in MOXIS Guest für externe Signierende abgeschlossen hat, kann MOXIS den Benutzer auf eine URL Ihrer Wahl weiterleiten. Dies ist nützlich, um den Benutzer zur Bestätigungsseite Ihrer Anwendung zurückzuführen, einen Modal-Flow zu schließen oder einen nächsten Schritt in Ihrem Prozess auszulösen.

Die Weiterleitung wird konfiguriert, indem Sie beim Öffnen der MOXIS-Guest-URL einen Query-Parameter successUrl anhängen. Die URL muss URL-kodiert sein.

MOXIS Tipp
Die Unterstützung von Weiterleitungs-URLs ist eine instanzweite Konfiguration. Ihr MOXIS-Administrator kann einschränken, welche URLs oder URL-Muster als Weiterleitungsziele zulässig sind. Bestätigen Sie mit MOXIS, dass Weiterleitungs-URLs aktiviert sind und Ihre Zieldomain erlaubt ist.


13.7.2. URL-Format

Hier wird eine Success URL mittels URL-Encoding übergeben.

https://your-moxis-instance/mogu/job/{GUID}/?successUrl=https%3A%2F%2Fwww.your-application.com%2Fsigned


13.7.3. Verwandte Themen

  • External Signer URL: Zugriff auf MOXIS Guest für externe Signer

  • Fetching Documents: Signierte Dokumente nach Job-Abschluss abrufen

  • Signature Iterations: Konfiguration von Workflows mit mehreren Signern


14. Workflow-Genehmigung ohne Signatur (APPROVAL_NOSIG)

14.1. Was ist die Workflow-Genehmigung ohne Signatur?

APPROVAL_NOSIG ist eine Signaturkategorie in MOXIS, die eine Workflow-Genehmigungsaktion protokolliert, ohne eine kryptografische Signatur auf dem Dokument anzubringen. MOXIS führt den Job weiterhin durch seinen Workflow-Zustandsautomaten und protokolliert die Genehmigungsaktion. Das Dokument wird lediglich nicht kryptografisch signiert.

Verwenden Sie diese Kategorie, wenn Sie ein Dokument durch einen internen Prüf- oder Freigabeprozess leiten müssen, eine rechtlich anerkannte elektronische Signatur jedoch nicht erforderlich ist. Typische Beispiele sind:

  • Interne Dokumentenprüfungs- und Bestätigungsabläufe

  • Freigabe durch das Management, bevor ein Dokument an einen qualifizierten Signer weitergeleitet wird

  • Compliance-getriebene Genehmigungsketten, bei denen die rechtsverbindliche Signatur von einem einzigen abschließenden Genehmiger stammt

14.2. Unterschied zu APPROVAL

Kategorie

Kryptografische Signatur

Workflow-Aktion protokolliert

Typischer Anwendungsfall

APPROVAL

Ja (SES / SES+)

Ja

Einfache elektronische Signatur mit persönlichem Bezug

APPROVAL_NOSIG

Nein

Ja

Reine Workflow-Genehmigung; keine Signatur auf dem PDF

QSIG

Ja (QES)

Ja

Qualifizierte elektronische Signatur

Bei APPROVAL_NOSIG protokolliert MOXIS, wer genehmigt hat und wann (sichtbar im Prüfbericht), aber es wird kein Signaturfeld oder keine Signaturseite zum PDF hinzugefügt.

14.3. Job-Beschreibung

Setzen Sie "category": "APPROVAL_NOSIG" im relevanten iterationData-Eintrag. Dem Invitee muss in MOXIS die Rolle moxisApprover zugewiesen sein.

14.3.1. Vollständiges Beispiel

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Example approval without a signature (Durchwinken — workflow step without cryptographic signature)"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "roleName": "moxisApprover"
        }
      ],
      "category": "APPROVAL_NOSIG",
      "iterationNumber": 0
    }
  ]
}

14.4. Kombination von APPROVAL_NOSIG mit anderen Kategorien

APPROVAL_NOSIG ist besonders nützlich als ein Schritt in einem mehrstufigen Workflow. Zum Beispiel genehmigt ein interner Prüfer das Dokument (ohne Signatur), wonach ein qualifizierter Signer in der nächsten Iteration eine QES-Signatur leistet.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "manager@example.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "INVISIBLE",
  "metaData": {
    "description": "Review then sign"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "reviewer@example.com",
          "roleName": "moxisApprover"
        }
      ],
      "category": "APPROVAL_NOSIG",
      "iterationNumber": 0
    },
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "signer@example.com",
          "roleName": "moxisSigner"
        }
      ],
      "category": "QSIG",
      "iterationNumber": 1
    }
  ]
}

In diesem Beispiel wechselt das Dokument erst zu Iteration 1 (dem QES-Signer), wenn der Prüfer in Iteration 0 seine APPROVAL_NOSIG-Aktion abgeschlossen hat. Siehe Signature Iterations für eine vollständige Erklärung der Funktionsweise von Iterationen.

14.5. Rollenanforderungen

Der Invitee für eine APPROVAL_NOSIG-Iteration muss in MOXIS die Rolle moxisApprover zugewiesen haben. Die Rolle allein reicht nicht aus — der Benutzer benötigt zusätzlich moxisUser, um sich anzumelden:

Rolle

Zweck

moxisUser

Erforderlich, um sich an der MOXIS-Benutzeroberfläche anzumelden

moxisApprover

Erforderlich, um Aktionen der Kategorie Approval durchzuführen, einschließlich APPROVAL_NOSIG

14.6. Job-Status nach der Genehmigung

Nachdem der Genehmiger die APPROVAL_NOSIG-Aktion abgeschlossen hat:

  • wechselt der Job zur nächsten Iteration oder in den Status FINISHED_SUCCESS, wenn keine weiteren Iterationen vorhanden sind.

  • protokolliert der Prüfbericht (abgerufen mit GET getReport) die Aktion und den Zeitstempel des Genehmigers.

  • bleibt das PDF-Dokument selbst unverändert. Es wird kein Signaturfeld oder keine Signaturseite hinzugefügt.

MOXIS Tipp
Wenn Sie den Prüfbericht abrufen müssen, um nachzuweisen, dass die Genehmigung stattgefunden hat, verwenden Sie GET getReport. Siehe Fetching Documents.


14.7. Verwandte Themen

  • Signature Iterations: Mehrstufige Workflows orchestrieren

  • Fetching Documents: Das signierte PDF und den Prüfbericht abrufen

  • Metadata and Custom Data: Referenz-IDs und benutzerdefinierte Daten an Jobs anhängen


15. Dokumente und Berichte abrufen

Sobald ein MOXIS-Signatur-Job den Status FINISHED_SUCCESS erreicht, können Sie die signierten Dokumente und den Prüfbericht über dedizierte GET-Endpunkte abrufen. Diese Anleitung behandelt jede Methode, wann sie zu verwenden ist, und liefert einsatzbereite cURL-Beispiele.

MOXIS Tipp
MOXIS löscht Jobs automatisch nach ihrem Enddatum (gesteuert über expirationDate in der Job-Beschreibung oder den Systemstandard). Rufen Sie alle Dokumente ab, bevor der Job abläuft — gelöschte Dokumente können nicht wiederhergestellt werden.


15.1. Übersicht der Abrufmethoden

Methode

Liefert

Wann verwenden

GET getDocument

Hauptsignaturdokument (PDF)

Jobs mit einem einzelnen Dokument

GET getAttachments

Alle Anhänge als ZIP (oder PDF bei nur einem)

Job hat angehängte Dokumente

GET getMultiSignDocuments

Alle Hauptdokumente als ZIP

Multi-Sign-Jobs mit mehreren Hauptdokumenten

GET getReport

Prüf-/Signaturbericht als PDF

Ein zertifizierter Prüfnachweis wird benötigt

Alle Endpunkte liefern Binärinhalte (application/pdf oder application/zip). Authentifizieren Sie sich mit Ihren Webservice-Benutzeranmeldedaten (Basic Auth oder Bearer-Token).


15.2. GET getDocument

Ruft das Hauptsignaturdokument (PDF) eines Jobs ab.

GET <base-url>/getDocument/{processInstanceId}

Parameter

Typ

Beschreibung

processInstanceId

String

Die beim Erstellen des Jobs zurückgegebene ID

Liefert: Blob (die signierte PDF-Datei).

15.2.1. cURL-Beispiel

JavaScript
curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getDocument/277764" \
  -u "webservice-user:password" \
  -o signed-document.pdf

15.2.2. cURL-Beispiel mit Bearer-Token

JavaScript
curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getDocument/277764" \
  -H "Authorization: Bearer <your-access-token>" \
  -o signed-document.pdf

MOXIS Tipp
Rufen Sie diesen Endpunkt erst auf, wenn der Job den Status FINISHED_SUCCESS erreicht hat. Der Aufruf während der Job noch ACTIVE ist, liefert die unsignierte Version des Dokuments.


15.3. GET getAttachments

Ruft alle angehängten Dokumente eines Jobs ab. Anhänge sind zusätzliche Dateien, die zusammen mit dem Hauptdokument eingereicht wurden — sie unterscheiden sich vom primären signierten PDF.

GET <base-url>/getAttachments/{processInstanceId}

Parameter

Typ

Beschreibung

processInstanceId

String

Die beim Erstellen des Jobs zurückgegebene ID

Liefert:

  • Bei einem einzelnen Anhang: Blob (der Anhang als PDF).

  • Bei mehreren Anhängen: Blob (alle Anhänge gebündelt als ZIP-Archiv).

15.3.1. cURL-Beispiel

curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getAttachments/277764" \
  -u "webservice-user:password" \
  -o attachments.zip

MOXIS Tipp
Ihr HTTP-Client sollte den Antwort-Header Content-Type prüfen, um festzustellen, ob die Antwort application/pdf oder application/zip ist, und entsprechend darauf reagieren.


15.4. GET getMultiSignDocuments

Ruft alle Hauptdokumente eines Multi-Sign-Jobs als ZIP-Archiv ab. Verwenden Sie dies, wenn Sie den Job mit POST startMultiSignProcess erstellt haben und alle primären signierten PDFs auf einmal herunterladen müssen.

GET <base-url>/getMultiSignDocuments/{processInstanceId}

Parameter

Typ

Beschreibung

processInstanceId

String

Die beim Erstellen des Jobs zurückgegebene ID

Liefert: Blob (alle Hauptdokumente als ZIP-Archiv).

15.4.1. cURL-Beispiel

curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getMultiSignDocuments/277764" \
  -u "webservice-user:password" \
  -o all-signed-documents.zip


15.5. GET getReport

Ruft den Prüf-/Signaturbericht eines Jobs als PDF ab. Der Bericht enthält einen zertifizierten Prüfnachweis mit: wer signiert hat, wann signiert wurde, welche Signaturmethode verwendet wurde, sowie weitere relevante Metadaten.

GET <base-url>/getReport/{processInstanceId}/{language}

Parameter

Typ

Beschreibung

processInstanceId

String

Die beim Erstellen des Jobs zurückgegebene ID

language

String

Berichtssprache: en (Englisch) oder de (Deutsch)

Liefert: Blob (der Prüfbericht als PDF).

15.5.1. cURL-Beispiel (englischer Bericht)

curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getReport/277764/en" \
  -u "webservice-user:password" \
  -o signing-report.pdf

15.5.2. cURL-Beispiel (deutscher Bericht)

curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getReport/277764/de" \
  -u "webservice-user:password" \
  -o signing-report-de.pdf


15.6. Abrufen anhand der referenceId

Haben Sie beim Erstellen des Jobs eine referenceId gesetzt (ab MOXIS v4.52 verfügbar), können Sie Dokumente anhand Ihrer eigenen Referenz statt der MOXIS-processInstanceId abrufen:

# Hauptdokument anhand der Referenz-ID

JavaScript
curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getDocumentByReferenceId/Ref123456" \
  -u "webservice-user:password" \
  -o signed-document.pdf

# Anhänge anhand der Referenz-ID

curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getAttachmentsByReferenceId/Ref123456" \
  -u "webservice-user:password" \
  -o attachments.zip

# Multi-Sign-Dokumente anhand der Referenz-ID

curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getMultisignDocumentsByReferenceId/Ref123456" \
  -u "webservice-user:password" \
  -o all-signed-documents.zip

Siehe Metadata and Custom Data für Details zum Setzen einer referenceId beim Erstellen eines Jobs.


15.7. Erkennen, wann ein Job abgeschlossen ist

15.7.1. Polling mit getJobState

Fragen Sie GET getJobState ab und prüfen Sie das Feld state:

curl -X GET \
  "https://your-moxis-instance/webservices/rest/api/layer2/v1.0/getJobState/277764/webservice-user@example.com" \
  -u "webservice-user:password"

Rufen Sie Dokumente ab, wenn state gleich FINISHED_SUCCESS ist. Rufen Sie Dokumente in keinem anderen finalen Status ab — das Dokument ist möglicherweise nicht vollständig signiert.

Job-Statuswerte

Status

Bedeutung

DRAFTING

Der Job befindet sich im Entwurfsmodus, noch nicht gestartet

ACTIVE

Der Job läuft — die Signatur ist im Gange

POST_PROCESSING

Die Signatur ist abgeschlossen; MOXIS führt die Nachbearbeitung durch

FINISHED_SUCCESS

Alle Signaturschritte erfolgreich abgeschlossen — Dokumente können sicher abgerufen werden

FINISHED_FAILED

Der Job ist fehlgeschlagen

FINISHED_TIMEOUT

Der Job ist vor Abschluss abgelaufen

FINISHED_WF_CANCELLED

Der Job wurde über den Workflow abgebrochen

FINISHED_SIGNATURE_DENIED

Ein Signer hat die Signatur abgelehnt/verweigert

DRAFT_DISMISSED

Der Entwurf wurde verworfen, bevor der Job gestartet wurde

15.7.2. Webhooks (Enterprise-Stufe)

Läuft Ihre MOXIS-Instanz auf der Enterprise-Stufe, konfigurieren Sie einen Webhook für den Prozess, um eine Push-Benachrichtigung zu erhalten, sobald sich der Job-Status ändert. Der Webhook liefert dasselbe Datenmodell wie getJobState, sodass Ihre Anwendung nach Erhalt der Benachrichtigung sofort den passenden Endpunkt zum Abrufen des Dokuments aufrufen kann.


15.8. Hauptdokument vs. Anhänge


Hauptdokument

Anhänge

Übermittlung

Feld documentToSign in der Multipart-Anfrage

Feld attachments in der Multipart-Anfrage

Abruf

GET getDocument

GET getAttachments

Signaturverhalten

Die elektronische Signatur wird auf dieses Dokument angewendet

Anhänge können je nach Prozesskonfiguration signiert sein oder nicht

Mehrere Dateien

Verwenden Sie POST startMultiSignProcess mit documentsToSign

Bis zu N Anhänge unterstützt

15.9. Verwandte Themen

  • Metadata and Custom Data: referenceId und expirationDate festlegen

  • Signature Iterations: Den Job-Lebenszyklus in Workflows mit mehreren Signierenden verstehen

  • External Signer URL: Externe Signierende benachrichtigen und ihren Fortschritt verfolgen


16. Workflows mit mehreren Signierenden über Iterationen

16.1. Was Iterationen sind

Eine Iteration ist eine Signaturrunde in einem MOXIS-Job. Hat ein Job mehrere Signierende, die in einer festgelegten Reihenfolge signieren müssen, modellieren Sie dies als Array von Iterationsobjekten in der Job-Beschreibung. Jede Iteration muss abgeschlossen sein, bevor die nächste beginnt.

Wesentliche Regeln:

  • iterationNumber beginnt bei 0 und erhöht sich für jede weitere Runde um 1.

  • Signierende, die in derselben Iteration aufgeführt sind, signieren parallel. Sie können alle gleichzeitig signieren, und die Iteration ist erst abgeschlossen, wenn alle erforderlichen Signer gehandelt haben.

  • Signierende, die in unterschiedlichen Iterationen aufgeführt sind, signieren sequenziell (Iteration 1 beginnt erst, wenn Iteration 0 vollständig abgeschlossen ist).

  • Das Feld category jeder Iteration bestimmt die Signaturqualität (QES, SES, Approval usw.) für diese Runde. Unterschiedliche Iterationen können unterschiedliche Kategorien verwenden.


16.2. Parallele vs. sequenzielle Signatur

16.2.1. Sequenziell (unterschiedliche Iterationen)

Zwei Signer in unterschiedlichen Iterationen: Signer A muss abschließen, bevor Signer B überhaupt benachrichtigt wird.

iterationNumber: 0  →  iterationNumber: 1
     Signer A                Signer B
  (muss zuerst fertig sein)  (beginnt nach Abschluss von 0)

16.2.2. Parallel (gleiche Iteration)

Zwei Signer in derselben Iteration: Beide werden gleichzeitig benachrichtigt, und die Iteration endet, wenn beide signiert haben.

iterationNumber: 0
  Signer A  |  Signer B
  (beide signieren gleichzeitig; Iteration abgeschlossen, wenn beide fertig sind)


16.3. Beispiel: parallele Iteration 0, sequenzielle Iteration 1

Dieses Beispiel zeigt zwei interne Benutzer, die parallel signieren (Iteration 0, QES), gefolgt von einem einzelnen externen Signer (Iteration 1, EXTERNAL_QSIG). Der externe Signer wird erst eingeladen, nachdem beide internen Signer abgeschlossen haben.

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "SIGNATURE_PAGE",
  "metaData": {
    "description": "Demo parallel versus sequential",
    "referenceId": "123456"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "roleName": "moxisSigner"
        },
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "roleName": "moxisSigner"
        }
      ],
      "category": "QSIG",
      "iterationNumber": 0
    },
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "externalUserName": "User Name",
          "phoneNumber": "+43664123456",
          "roleName": "Extern",
          "locale": "en"
        }
      ],
      "category": "EXTERNAL_QSIG",
      "iterationNumber": 1
    }
  ]
}


16.4. Vollständiges Multi-Iterations-Beispiel

Dieses Beispiel zeigt einen dreistufigen Workflow:

1. Iteration 0: interner Genehmiger (SES, keine QES erforderlich)
2. Iteration 1: externer Signer (EXTERNAL_APPROVAL mit einer direkten Signaturposition auf dem Dokument)

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "metaData": {
    "description": "Iterations example",
    "referenceId": "1234567"
  },
  "positionType": "DIRECT_POSITION",
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "roleName": "moxisApprover"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0
    },
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.ExternalUser",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "externalUserName": "User Name",
          "phoneNumber": "+43699123456",
          "roleName": "Extern",
          "locale": "de",
          "directUserPosition": {
            "x": "66",
            "y": "510",
            "width": "225",
            "height": "80",
            "pageNumber": 1
          }
        }
      ],
      "category": "EXTERNAL_APPROVAL",
      "iterationNumber": 1
    }
  ]
}


16.5. Weitere Iterationsoptionen

Über die erforderlichen Felder (iterationNumber, category, invitees) hinaus unterstützt jede Iteration mehrere optionale Parameter:

16.5.1. numberOfSignatures: Gruppensignatur (N von M)

Hat eine Iteration mehrere Invitees, die eine Gruppe repräsentieren, ermöglicht numberOfSignatures, dass nur N der M Gruppenmitglieder signieren müssen, bevor die Iteration weiterschreitet.

{
  "invitees": [
    {
      "@class": "com.xitrust.moxispe.api.UserForRole",
      "classifier": "EMAIL",
      "name": "member1@example.com",
      "roleName": "moxisSigner"
    },
    {
      "@class": "com.xitrust.moxispe.api.UserForRole",
      "classifier": "EMAIL",
      "name": "member2@example.com",
      "roleName": "moxisSigner"
    },
    {
      "@class": "com.xitrust.moxispe.api.UserForRole",
      "classifier": "EMAIL",
      "name": "member3@example.com",
      "roleName": "moxisSigner"
    }
  ],
  "category": "QSIG",
  "iterationNumber": 0,
  "numberOfSignatures": 2
}

In diesem Beispiel müssen beliebige 2 der 3 aufgeführten Signer signieren. Die Iteration ist abgeschlossen, sobald 2 Signaturen eingegangen sind — das dritte Mitglied muss nicht mehr handeln.

16.5.2. privateIteration

Setzen Sie privateIteration: true, um eine Iteration vor Beobachtern und Vertretern zu verbergen. Nur die tatsächlichen Invitees dieser Iteration sehen sie.

{
  "invitees": [ ... ],
  "category": "QSIG",
  "iterationNumber": 0,
  "privateIteration": true
}

16.5.3. customMap (auf Iterationsebene)

Hängen Sie Schlüssel-Wert-Metadaten an eine bestimmte Iteration an. Nützlich, um nachzuverfolgen, welche Systemaktion oder welcher Prozessschritt zu welcher Signaturrunde gehört.

{
  "invitees": [ ... ],
  "category": "APPROVAL",
  "iterationNumber": 0,
  "customMap": {
    "step": "legal-review",
    "departmentId": "42"
  }
}

16.5.4. Remark

Ein optionaler Freitexthinweis für die Iteration, sichtbar für die Invitees.

{
  "invitees": [ ... ],
  "category": "APPROVAL",
  "iterationNumber": 0,
  "remark": "Please review section 3 carefully before signing."
}


16.6. Signaturkategorien pro Iteration

Jede Iteration legt ihre eigene category fest, die bestimmt, welche Art von Signaturaktion erwartet wird:

Kategorie

Signertyp

Beschreibung

QSIG

Intern

Qualifizierte elektronische Signatur (QES)

EXTERNAL_QSIG

Extern

Qualifizierte elektronische Signatur für externe Signer

APPROVAL

Intern

Einfache elektronische Signatur (SES / SES+)

EXTERNAL_APPROVAL

Extern

Einfache elektronische Signatur für externe Signer

APPROVAL_NOSIG

Intern

Workflow-Genehmigung ohne kryptografische Signatur

Siehe Approval Without Signature für eine eigene Anleitung zu APPROVAL_NOSIG.

16.7. Iterationsfortschritt überwachen

Verwenden Sie GET getJobState, um zu sehen, welche Iteration aktuell aktiv ist und welche Aktion jeder Invitee vorgenommen hat:

GET <base-url>/getJobState/{processInstanceId}/{nameClassifier}

Die Antwort enthält: - currentIteration — den Index der aktuell aktiven Iteration (beginnend bei 0) - iterations[].invitees[].action — die von jedem Invitee vorgenommene Aktion (null, falls noch nicht gehandelt) - iterations[].invitees[].actionDate — Zeitstempel der Aktion - state — der Gesamtstatus des Jobs (z. B. ACTIVE, FINISHED_SUCCESS)


16.8. Vollständiges Beispiel: zwei sequenzielle Genehmigungen

{
  "constituent": {
    "classifier": "EMAIL",
    "name": "user.name@domain.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "INVISIBLE",
  "metaData": {
    "description": "Some iterations",
    "referenceId": "referenceId"
  },
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "roleName": "moxisApprover"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0
    },
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.UserForRole",
          "classifier": "EMAIL",
          "name": "user.name@domain.com",
          "roleName": "moxisApprover"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 1
    }
  ]
}


16.9. Verwandte Themen

  • Approval Without Signature: Verwendung von APPROVAL_NOSIG für reine Workflow-Schritte

  • External Signer URL: Zugriff auf MOXIS Guest für externe Signierende

  • InstantSign: Vereinfachte Signaturansicht für interne Benutzer

  • Fetching Documents: Signierte Dokumente nach Job-Abschluss abrufen

  • Metadata and Custom Data: Referenz-IDs, benutzerdefinierte Daten und weitere Metadaten anhängen