Inhalt
Die MOXIS REST API ermöglicht es externen Systemen, elektronische Signaturaufträge programmatisch zu erstellen, zu verwalten und abzufragen.
1. Allgemeine Informationen
1.1. Basis-URL
basis-url/webservices/rest/api/layer2/v1.0
1.2. API-Versionierung
Die aktuelle API-Version ist v1.0. Die Version ist Teil des URL-Pfads. Für Reference-ID-Funktionen und Keycloak-basiertes OAuth ist MOXIS v4.52 oder höher erforderlich.
1.3. Authentifizierung
Die API unterstützt zwei Authentifizierungsmethoden.
-
Basic Authentication
HTTP Basic Auth mit einem technischen Webservice-Benutzernamen und -Passwort. MOXIS-Administratoren registrieren Webservice-Benutzer und konfigurieren deren Zugriffsebene.
-
OAuth 2.0 (Bearer-Token)
Verfügbar ab MOXIS v4.52 mit Keycloak-Integration.
Fügen Sie das Bearer-Token im Authorization-Header ein:
Authorization: Bearer <token>
1.4. Content-Type
POST-, PUT- und PATCH-Anfragen müssen multipart/form-data (RFC 7578) verwenden. Einfache JSON-Request-Bodies werden für diese Methoden nicht unterstützt. Ein typischer Multipart-Aufruf umfasst:
-
jobDescription: Eine JSON-codierte Zeichenkette mit der Job- oder Entwurfskonfiguration.
-
documentToSign: Die PDF-Datei als binäres Blob
-
attachments: Optionale zusätzliche PDF-Dateien (1–n)
GET-Anfragen benötigen keinen Request-Body.
1.5. HTTP-Statuscodes
|
Code |
Bedeutung |
|
200 |
OK
|
|
201 |
Created
|
|
302 |
Redirect
|
|
400 |
Bad Request
|
|
404 |
Not Found
|
|
500 |
Server Error
|
1.6 Paginierung
Endpunkte, die Listen zurückgeben (wie lookupJobStates), liefern standardmäßig maximal 50 Ergebnisse. Verwenden Sie die Query-Parameter offset und pageSize, um durch größere Ergebnismengen zu blättern.
GET .../lookupJobStates?offset=0&pageSize=50 # Ergebnisse 1–50
GET .../lookupJobStates?offset=50&pageSize=50 # Ergebnisse 51–100
2. Endpunkte
2.1. Auftragsverwaltung
|
Methode |
Endpunkt |
Beschreibung |
|
POST |
createDraft |
Einen Entwurfsauftrag zur Prüfung in der MOXIS-Oberfläche erstellen |
|
POST |
startProcess |
Einen Signaturauftrag sofort starten |
|
PUT |
dismissDraft |
Einen vorhandenen Entwurf verwerfen |
|
PUT |
cancelJob |
Einen aktiven Signaturauftrag abbrechen |
|
GET |
deleteClosedJob |
Einen zuvor abgebrochenen Auftrag löschen |
|
GET |
getJobState |
Den aktuellen Status und die Details eines Auftrag abrufen |
|
GET |
getDocument |
Das signierte Hauptdokument herunterladen |
2.2. Massenoperationen
|
Methode |
Endpunkt |
Beschreibung |
|
GET |
getAttachments |
Alle Anhänge eines Auftrags herunterladen |
|
GET |
getMultiSignDocuments |
Alle Hauptdokumente eines Multi-Sign-Jobs herunterladen |
|
POST |
createMultiSignDraft |
Einen Multi-Dokument-Entwurf erstellen |
|
POST |
startMultiSignProcess |
Einen Multi-Dokument-Signaturauftrag starten |
2.3. Lookup
|
Methode |
Endpunkt |
Beschreibung |
|
GET |
lookupJobStates |
Aufträge suchen und filtern, liefert processInstanceId und Status zurück |
|
GET |
countLookupJobStates |
Aufträge zählen, die denselben Filterkriterien entsprechen |
2.4. Reference-ID-Methoden
|
Methode |
Endpunkt |
Beschreibung |
|
GET |
getJobStateByReferenceId |
Auftragsstatus über Ihre eigene Reference-ID abrufen |
|
GET |
getDocumentByReferenceId |
Hauptdokument über Ihre eigene Reference-ID herunterladen |
|
GET |
getAttachmentsByReferenceId |
Anhänge über Ihre eigene Reference-ID herunterladen |
|
GET |
getMultisignDocumentsByReferenceId |
Multi-Sign-Dokumente über Ihre eigene Reference-ID herunterladen |
2.5. Utility
|
Methode |
Endpunkt |
Beschreibung |
|
GET |
getPlaceholder |
Ein Signatur-Platzhalterbild erzeugen |
|
GET |
getPlaceholderWithSize |
Ein Signatur-Platzhalterbild in einer bestimmten Größe erzeugen |
|
POST |
placeholderInfo |
Platzhalter in einem PDF vor dem Absenden eines Jobs validieren |
|
GET |
getReport |
Den Prüf-/Signaturbericht für einen abgeschlossenen Job herunterladen |
|
GET |
findMoxisUser |
Einen MOXIS-Benutzer per E-Mail-Adresse suchen |
|
GET |
getLicenses |
Lizenznutzungsdaten als CSV-ZIP-Archiv exportieren |
|
GET |
getDynamicKeyLink |
Eine einmalige Registrierungs-URL für ein Trust Center abrufen |
2.6. Authentifizierung
|
Methode |
Endpunkt |
Beschreibung |
|
POST |
Token (Keycloak) |
Ein OAuth 2.0 Bearer-Token über Keycloak beziehen |
|
POST |
startProcessWithTemplate |
Einen Signaturauftrag über eine vorkonfigurierte MOXIS-Vorlage starten |
2.7. Tracking
|
Methode |
Endpunkt |
Beschreibung |
|
GET |
getJobDocumentDownloadState |
Download-Tracking-Informationen für die Dokumente eines Auftrags abrufen |
|
GET |
getJobDocumentDownloadStateByReferenceId |
Download-Tracking-Informationen über Ihre eigene Reference-ID abrufen |
3. POST Start Process (Auftrag erstellen)
Startet einen Signaturauftrag in MOXIS sofort und leitet ihn ohne Entwurfsprüfung direkt an die angegebenen Signer weiter.
3.1. Endpunkt
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/{processId}
3.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processId |
String |
Ja |
Identifiziert die zu verwendende Prozessvorlage. Diesen Wert finden Sie im MOXIS-Bereich für die Prozessverwaltung. |
3.3. Request-Body
Die Anfrage muss multipart/form-data verwenden.
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
jobDescription |
JSON-String |
Ja |
Beschreibt den Auftrag. Muss constituent und iterationData mit mindestens einer eingeladenen Person (Signer) enthalten. |
|
documentToSign |
Binär (PDF) |
Ja |
Das zu signierende PDF-Dokument. |
|
attachments |
Binär (PDF) |
Nein |
Ein oder mehrere zusätzliche PDF-Anhänge. Wiederholen Sie das Feld für jeden Anhang. |
3.4. Struktur von jobDescription
Im Gegensatz zu createDraft erfordert startProcess vollständige iterationData, die festlegen, wer in welcher Iteration signiert.
{
"constituent": {
"classifier": "UPN",
"name": "max.test@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
},
"metaData": {
"description": "Q1 Contract",
"referenceId": "CONTRACT-2024-001"
},
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "UPN",
"name": "signer.one@xitrust.com",
"roleName": "moxisSigner"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
Optional kann pro Signierenden eine alternative Signaturvisualisierung über das Feld visualizationLayoutId im jeweiligen Invitee-Objekt festgelegt werden. Für alle externen Signierenden eines Jobs zentral lässt sie sich außerdem über visualizationLayoutIds in metaData konfigurieren (ab MOXIS 4.56.
3.5. Signaturkategorien
|
Wert |
Beschreibung |
|
QSIG |
Qualifizierte elektronische Signatur: interner Signierender |
|
EXTERNAL_QSIG |
Qualifizierte elektronische Signatur: externer Signierender |
|
APPROVAL |
Einfache Signatur (SES oder AES): interner Signierender |
|
EXTERNAL_APPROVAL |
Einfache Signatur (SES oder AES)externer Signierender |
|
APPROVAL_NOSIG |
Nur Workflow-Schritt, es wird keine Signatur angebracht |
3.6. Beispiel mit mehreren Iterationen
Signierende in getrennten Iterationen signieren nacheinander. iterationNumber beginnt bei 0.
{
"constituent": {
"classifier": "UPN",
"name": "testUser",
"@class": "com.xitrust.moxispe.api.User"
},
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.UserForRole",
"classifier": "UPN",
"name": "testUser",
"roleName": "moxisSigner"
}
],
"category": "QSIG",
"iterationNumber": 0
},
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.ExternalUserForRole",
"classifier": "EMAIL",
"name": "external.user@email.com",
"externalUserName": "External User",
"roleName": "Extern",
"locale": "de",
"phoneNumber": "+43123456789"
}
],
"category": "EXTERNAL_QSIG",
"iterationNumber": 1
}
]
}
3.7. Antwort
Gibt bei Erfolg die processInstanceId (String) des neu erstellten Auftrags zurück.
|
Status |
Bedeutung |
|
201 |
Auftrag wurde erfolgreich erstellt und gestartet. |
3.8. Hinweise
-
Im Gegensatz zu createDraft aktiviert startProcess den Auftrag sofort und benachrichtigt die eingeladenen Personen.
-
Signierende werden über @class referenziert. Interne Benutzer verwenden com.xitrust.moxispe.api.User oder com.xitrust.moxispe.api.UserForRole; externe Signierende verwenden com.xitrust.moxispe.api.ExternalUserForRole oder ExternalUser.
3.9. Beispiel
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/my-process-id
Authorization: Basic <base64-encoded-credentials>
Content-Type: multipart/form-data; boundary=----FormBoundary
------FormBoundary
Content-Disposition: form-data; name="jobDescription"
{
"constituent": {
"classifier": "EMAIL",
"name": "owner@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
},
"positionType": "INVISIBLE",
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer@xitrust.com",
"roleName": "moxisSigner"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
------FormBoundary
Content-Disposition: form-data; name="documentToSign"; filename="contract.pdf"
Content-Type: application/pdf
<binary PDF content>
------FormBoundary--
4. POST Create Draft
Erstellt einen Auftragsentwurf in MOXIS, den ein Benutzer in der Web-Oberfläche prüfen und fertigstellen kann, bevor der Signaturprozess beginnt.
4.1. Endpunkt
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/createDraft/{processId}
Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processId |
String |
Ja |
Identifiziert die zu verwendende Prozessvorlage. Diesen Wert finden Sie im MOXIS-Bereich für die Prozessverwaltung. |
4.2. Request-Body
Die Anfrage muss multipart/form-data verwenden.
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
jobDescription |
JSON-String |
Ja |
Beschreibt den Auftrag . Für einen Entwurf ist nur das Feld constituent erforderlich. Vollständige Signer-/Iterationsdaten sind zu diesem Zeitpunkt nicht nötig. |
|
documentToSign |
Binär (PDF) |
Ja |
Das zu signierende PDF-Dokument. |
|
attachments |
Binär (PDF) |
Nein |
Ein oder mehrere zusätzliche PDF-Anhänge. Wiederholen Sie das Feld für jeden Anhang. |
4.3. Minimale jobDescription für einen Entwurf
Beim Erstellen eines Entwurfs ist nur constituent erforderlich. Der Constituent gibt an, wem der Job in MOXIS gehört.
{
"constituent": {
"classifier": "EMAIL",
"name": "max.test@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
}
}
4.4. Antwort
Gibt bei Erfolg die processInstanceId (String) des neu erstellten Entwurfs zurück.
|
Status |
Bedeutung |
|
201 |
Entwurf wurde erfolgreich erstellt. |
|
404 |
Die angegebene processId wurde in MOXIS nicht gefunden. |
4.5. URL für die Entwurfsansicht
Nach dem Erstellen eines Entwurfs können Sie ihn im Vollbildmodus der MOXIS-Web-Oberfläche über folgende URL anzeigen:
https://<moxis-base-url>/ui/protected/?moxisView=CreateDraftedProcessView/<processInstanceId>
Diese URL eignet sich, um den Entwurfsprüfungsschritt in Drittanwendungen einzubetten.
4.6. Hinweise
-
Ein Entwurf benötigt in jobDescription nur constituent. Im Gegensatz zu startProcess müssen Sie bei der Erstellung keine iterationData mit Signer-Informationen angeben.
-
Entwürfe werden beim Verwerfen nicht sofort gelöscht. Sie werden in MOXIS automatisch entfernt, nachdem ihr Enddatum verstrichen ist.
-
Je nach Systemkonfiguration dürfen auch Administratoren Entwürfe verwerfen.
4.7. Beispiel
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/createDraft/my-process-id
Authorization: Basic <base64-encoded-credentials>
Content-Type: multipart/form-data; boundary=----FormBoundary
------FormBoundary
Content-Disposition: form-data; name="jobDescription"
{
"constituent": {
"classifier": "EMAIL",
"name": "max.test@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
}
}
------FormBoundary
Content-Disposition: form-data; name="documentToSign"; filename="contract.pdf"
Content-Type: application/pdf
<binary PDF content>
------FormBoundary--
5. POST Start Process With Template
Startet einen Signaturauftrag über eine vorkonfigurierte MOXIS-Vorlage, die die Signaturpositionen festlegt, sodass im API-Aufruf keine Platzierungskoordinaten angegeben werden müssen.
5.1. Endpunkt
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcessWithTemplate/{templateName}
5.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
templateName |
String |
Ja |
Der Name der Vorlage, wie er in MOXIS konfiguriert ist. Der Name muss unter allen freigegebenen Vorlagen eindeutig sein. |
5.3. Request-Body
Die Anfrage muss multipart/form-data verwenden.
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
jobDescription |
JSON-String |
Ja |
Beschreibt den Job, einschließlich constituent und iterationData mit Signer-Informationen. |
|
documentsToSign |
Binär (PDF) |
Ja |
Ein oder mehrere zu signierende PDF-Dokumente. Wiederholen Sie dieses Feld für jedes Dokument (1–n). |
|
attachments |
Binär (PDF) |
Nein |
Ein oder mehrere zusätzliche PDF-Anhänge. Wiederholen Sie dieses Feld für jeden Anhang (1–n). |
5.4. Struktur von jobDescription
Es gilt dieselbe Struktur wie bei startProcess. Geben Sie constituent und die vollständigen iterationData an.
{
"constituent": {
"classifier": "EMAIL",
"name": "owner@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
},
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer@xitrust.com",
"roleName": "moxisSigner"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
5.5. Antwort
Gibt bei Erfolg die processInstanceId (String) des neu erstellten Auftrags zurück.
|
Status |
Bedeutung |
|
201 |
Auftrag wurde über die Vorlage erfolgreich erstellt und gestartet. |
5.6. Voraussetzungen
-
Die Vorlage muss in MOXIS als freigegeben (shared) markiert sein. Private Vorlagen können über diesen Endpunkt nicht verwendet werden.
-
Die Seitenanzahl der übermittelten Dokumente muss exakt der Seitenanzahl der Vorlage entsprechen. Bei einer Abweichung schlägt die Anfrage fehl.
-
Vorlagen werden von MOXIS-Administratoren oder Benutzern mit der Rolle templateAdmin erstellt und verwaltet.
-
Vorlagennamen müssen unter allen freigegebenen Vorlagen einer MOXIS-Instanz eindeutig sein.
5.7. Hinweise
-
Dieser Endpunkt ist nützlich für standardisierte Dokumentenabläufe, bei denen die Signaturpositionen immer gleich sind — zum Beispiel unternehmensweite Vertragsvorlagen.
-
Im Gegensatz zu startProcess müssen Sie positionType oder Signaturkoordinaten in jobDescription nicht angeben; diese werden von der Vorlage übernommen.
-
Wenden Sie sich an Ihren MOXIS-Administrator, um eine Vorlage einzurichten oder freizugeben.
5.8. Beispiel
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcessWithTemplate/Q1-Contract-Template
Authorization: Basic <base64-encoded-credentials>
Content-Type: multipart/form-data; boundary=----FormBoundary
------FormBoundary
Content-Disposition: form-data; name="jobDescription"
{
"constituent": {
"classifier": "EMAIL",
"name": "owner@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
},
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer@xitrust.com",
"roleName": "moxisSigner"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
------FormBoundary
Content-Disposition: form-data; name="documentsToSign"; filename="contract.pdf"
Content-Type: application/pdf
<binary PDF content>
------FormBoundary--
6. POST Create Multi-Sign Draft
Erstellt einen Auftragsentwurf mit mehreren Dokumenten zur Prüfung in der MOXIS-Web-Oberfläche, bevor der Signaturprozess beginnt.
6.1. Endpunkt
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/createMultiSignDraft/{processId}
6.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processId |
String |
Ja |
Identifiziert die zu verwendende Prozessvorlage. Diesen Wert finden Sie im MOXIS-Bereich für die Prozessverwaltung. |
6.3. Request-Body
Die Anfrage muss multipart/form-data verwenden. Dieser Endpunkt funktioniert identisch zu createDraft, akzeptiert jedoch mehrere Dokumente über das Feld documentsToSign anstelle eines einzelnen documentToSign.
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
jobDescription |
JSON-String |
Ja |
Beschreibt den Job. Für einen Entwurf ist nur constituent erforderlich. |
|
documentsToSign |
Binär (PDF) |
Ja |
Ein oder mehrere zu signierende PDF-Dokumente. Wiederholen Sie dieses Feld für jedes Dokument (1–n). |
|
attachments |
Binär (PDF) |
Nein |
Ein oder mehrere zusätzliche PDF-Anhänge. Wiederholen Sie dieses Feld für jeden Anhang (1–n). |
6.4. Minimale jobDescription für einen Entwurf
{
"constituent": {
"classifier": "EMAIL",
"name": "max.test@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
}
}
6.5. Antwort
Gibt bei Erfolg die processInstanceId (String) des neu erstellten Entwurfs zurück.
|
Status |
Bedeutung |
|
201 |
Multi-Sign-Entwurf wurde erfolgreich erstellt. |
6.6. Hinweise
-
Verwenden Sie für diesen Endpunkt documentsToSign (Plural), nicht documentToSign. Jedes Dokument wird als separates Multipart-Feld mit demselben Feldnamen übermittelt.
-
MIME-Type-Einschränkungen für Anhänge können von Administratoren pro Prozess in MOXIS konfiguriert werden.
-
Um den Entwurf in der MOXIS-Web-Oberfläche anzuzeigen, verwenden Sie das URL-Muster der Entwurfsansicht: https://<moxis-base-url>/ui/protected/?moxisView=CreateDraftedProcessView/<processInstanceId>
-
Um einen Multi-Sign-Job direkt ohne Entwurf zu starten, verwenden Sie startMultiSignProcess.
6.7. Beispiel
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/createMultiSignDraft/my-process-id
Authorization: Basic <base64-encoded-credentials>
Content-Type: multipart/form-data; boundary=----FormBoundary
------FormBoundary
Content-Disposition: form-data; name="jobDescription"
{
"constituent": {
"classifier": "EMAIL",
"name": "owner@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
}
}
------FormBoundary
Content-Disposition: form-data; name="documentsToSign"; filename="contract1.pdf"
Content-Type: application/pdf
<binary PDF content>
------FormBoundary
Content-Disposition: form-data; name="documentsToSign"; filename="contract2.pdf"
Content-Type: application/pdf
<binary PDF content>
------FormBoundary--
7. POST Start Multi-Sign Process
Startet einen Signatur-Job, der mehrere Dokumente enthält, und leitet alle Dokumente gleichzeitig an die angegebenen Signer weiter.
7.1. Endpunkt
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startMultiSignProcess/{processId}
7.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processId |
String |
Ja |
Identifiziert die zu verwendende Prozessvorlage. Diesen Wert finden Sie im MOXIS-Bereich für die Prozessverwaltung. |
7.3. Request-Body
Die Anfrage muss multipart/form-data verwenden.
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
jobDescription |
JSON-String |
Ja |
Beschreibt den Job, einschließlich constituent und iterationData mit Signer-Informationen. |
|
documentsToSign |
Binär (PDF) |
Ja |
Ein oder mehrere zu signierende PDF-Dokumente. Wiederholen Sie dieses Feld für jedes Dokument (1–n). |
|
attachments |
Binär (PDF) |
Nein |
Ein oder mehrere zusätzliche PDF-Anhänge. Wiederholen Sie dieses Feld für jeden Anhang (1–n). |
7.4. Struktur von jobDescription
Es sind vollständige Signer- und Iterationsdaten erforderlich, genau wie bei startProcess.
{
"constituent": {
"classifier": "EMAIL",
"name": "owner@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
},
"metaData": {
"description": "Q1 Batch Contracts",
"referenceId": "BATCH-2024-001"
},
"positionType": "INVISIBLE",
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer@xitrust.com",
"roleName": "moxisSigner"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
7.5. Antwort
Gibt bei Erfolg die processInstanceId (String) des neu erstellten Multi-Sign-Jobs zurück.
|
Status |
Bedeutung |
|
201 |
Multi-Sign-Job wurde erfolgreich erstellt und gestartet. |
7.6. Hinweise
-
Verwenden Sie für diesen Endpunkt documentsToSign (Plural), nicht documentToSign. Wiederholen Sie das Feld für jedes Dokument.
-
Alle Dokumente in diesem Auftrag teilen sich dieselbe jobDescription — Signer, Iterationen und Auftrags-Metadaten gelten für alle Dokumente.
-
MIME-Type-Einschränkungen für Anhänge können von Administratoren pro Prozess in MOXIS konfiguriert werden.
-
Um die signierten Dokumente nach Abschluss abzurufen, verwenden Sie getMultiSignDocuments.
-
Um einen Multi-Sign-Job zunächst über einen Entwurf zu erstellen, verwenden Sie createMultiSignDraft.
7.7. Beispiel
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startMultiSignProcess/my-process-id
Authorization: Basic <base64-encoded-credentials>
Content-Type: multipart/form-data; boundary=----FormBoundary
------FormBoundary
Content-Disposition: form-data; name="jobDescription"
{
"constituent": {
"classifier": "EMAIL",
"name": "owner@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
},
"positionType": "INVISIBLE",
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer@xitrust.com",
"roleName": "moxisSigner"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
------FormBoundary
Content-Disposition: form-data; name="documentsToSign"; filename="document1.pdf"
Content-Type: application/pdf
<binary PDF content>
------FormBoundary
Content-Disposition: form-data; name="documentsToSign"; filename="document2.pdf"
Content-Type: application/pdf
<binary PDF content>
------FormBoundary--
8. PUT Dismiss Draft
Verwirft einen vorhandenen Auftragsentwurf und entfernt ihn aus der aktiven Entwurfsansicht, ohne ihn sofort zu löschen.
8.1. Endpunkt
PUT https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/dismissDraft/{processInstanceId}
8.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja |
Die ID des zu verwerfenden Entwurfs. Diese wird von createDraft bei der Erstellung zurückgegeben. |
8.3. Request-Body
Die Anfrage muss multipart/form-data verwenden. Geben Sie den Constituent (den Benutzer, der den Entwurf verwirft) als JSON-Objekt an.
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
user |
JSON-String |
Ja |
Identifiziert den Constituent, der das Verwerfen anfordert. |
{
"classifier": "EMAIL",
"name": "max.test@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
}
8.4. Antwort
Gibt bei Erfolg den HTTP-Statuscode 200 OK zurück. Es wird kein Response-Body zurückgegeben.
|
Status |
Bedeutung |
|
200 |
Entwurf wurde erfolgreich verworfen. |
8.5. Hinweise
-
dismissDraft löscht den Entwurf nicht. Entwürfe werden in MOXIS automatisch entfernt, nachdem ihr konfiguriertes Enddatum verstrichen ist.
-
Je nach Systemkonfiguration von MOXIS dürfen Administratoren auch Entwürfe anderer Benutzer verwerfen.
8.6. Beispiel
PUT https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/dismissDraft/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Basic <base64-encoded-credentials>
Content-Type: multipart/form-data; boundary=----FormBoundary
------FormBoundary
Content-Disposition: form-data; name="user"
{
"classifier": "EMAIL",
"name": "max.test@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
}
------FormBoundary--
9. GET Job State
Ruft den aktuellen Status und alle Details eines bestimmten Signaturauftrags ab.
9.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/{processInstanceId}/{nameClassifier}
9.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja |
Die ID des abzufragenden Auftrags. Wird von startProcess oder createDraft bei der Erstellung zurückgegeben. |
|
nameClassifier |
String |
Ja |
Identifiziert den anfragenden Benutzer. Verwenden Sie die MOXIS-ID, den UPN (User Principal Name) oder die E-Mail-Adresse des Benutzers. |
9.2. Request-Body
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Request-Body.
9.3. Antwort
Gibt ein JSON-Objekt mit dem vollständigen Auftragsstatusstatus zurück, einschließlich Metadaten, Iterationsdetails, Aktionen der eingeladenen Personen und Signatur-URLs.
|
Status |
Bedeutung |
|
200 |
Auftragsstatus wurde erfolgreich zurückgegeben. |
Auftrags-Zustände
|
Zustand |
Kategorie |
Bedeutung |
|
DRAFTING |
Aktiv |
Auftrag befindet sich im Entwurfsstatus, noch nicht zur Signatur eingereicht |
|
ACTIVE |
Aktiv |
Job läuft — Signatur ist im Gange |
|
POST_PROCESSING |
Aktiv |
Signatur ist abgeschlossen, Nachbearbeitung läuft |
|
FINISHED_SUCCESS |
Final |
Job erfolgreich abgeschlossen |
|
FINISHED_FAILED |
Final |
Auftrag fehlgeschlagen |
|
DRAFT_DISMISSED |
Final |
Entwurf wurde verworfen, bevor er zu einem Auftrag wurde |
|
FINISHED_TIMEOUT |
Final |
Auftrag ist abgelaufen, bevor alle Signaturen eingeholt wurden |
|
FINISHED_WF_CANCELLED |
Final |
Auftrag wurde durch den Workflow abgebrochen |
|
FINISHED_SIGNATURE_DENIED |
Final |
Ein Signer hat die Signaturanfrage abgelehnt |
ACTIVE und POST_PROCESSING sind die einzigen aktiven (nicht endgültigen) Zustände. Alle anderen Zustände sind final — sobald ein Auftrag einen dieser Zustände erreicht, erfolgen keine weiteren Übergänge.
Struktur der Antwort
Die Antwort folgt dem Datenmodell des Auftragsstatus. Wichtige Felder umfassen:
{
"state": "ACTIVE",
"processId": "my-process-id",
"processInstanceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"jobMetaData": {
"description": "Contract signing",
"category": null,
"expirationDate": "2024-12-31T23:59:59",
"referenceId": "CONTRACT-001",
"customMap": {}
},
"creationDate": "2024-01-15T10:00:00",
"endDate": "2024-12-31T23:59:59",
"currentIteration": 0,
"iterations": [
{
"numberOfSignatures": 1,
"invitees": [
{
"@class": "com.xitrust.moxispe.api.Signer",
"classifier": "UPN",
"name": "signer@xitrust.com",
"action": null,
"actionDate": null,
"instantSignUrl": "<base-url>/instant-sign/task/123456/3eefb2d4-74f5-4f9b-85da-f847bead4191"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
],
"constituent": "owner@xitrust.com",
"eventTimestamp": "2024-01-15T10:05:00",
"eventType": "JOB_STATE_CHANGED"
}
9.4. InstantSign-URL
Für interne Signierende liefert das Feld instantSignUrl im Objekt der eingeladenen Person einen direkten Link, der eine vereinfachte Signaturansicht öffnet. Dieser kann in ein iframe innerhalb einer Drittanwendung eingebettet werden. Diese Funktion muss von MOXIS aktiviert sein.
9.5. URL für externe Signierende (via MOXIS Guest)
Für externe Signierende liefert das Feld externalSignerUrl einen Link zu MOXIS Guest für externe Signierende, wo der externe Signierende seine Signatur abschließt. Diese URL ist in den Iteration Eingeladene der aktuellen Iteration verfügbar.
{
"@class": "com.xitrust.moxispe.api.ExternalSigner",
"externalSignerName": "External User",
"externalSignerEmail": "external@example.com",
"externalSignerUrl": "<base-url>/guest/job/de4f783c-99d0-4678-a513-b8e5eecfc11a"
}
9.6. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/a1b2c3d4-e5f6-7890-abcd-ef1234567890/signer@xitrust.com
Authorization: Basic <base64-encoded-credentials>
10. GET Lookup Job States
Sucht und filtert Aufträge über MOXIS hinweg und gibt für jeden übereinstimmenden Job die processInstanceId und den aktuellen Status zurück.
10.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/lookupJobStates
10.2. Parameter
Alle Query-Parameter sind optional. Ohne Angabe von Parametern werden die ersten 50 Aufträge zurückgegeben.
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processIds |
String |
Nein |
Filtert nach der ID der Prozessvorlage. Nicht in der MOXIS-Oberfläche sichtbar — aus der Prozessverwaltung zu beziehen. |
|
referenceId |
String |
Nein |
Filtert nach einer benutzerdefinierten Reference-ID, die in jobDescription.metaData.referenceId gesetzt wurde. |
|
lookupStates |
String |
Nein |
Durch Kommas getrennte Liste von Job-Zuständen zum Filtern (z. B. FINISHED_SUCCESS,ACTIVE). Siehe Job-Zustände unten. |
|
jobFinishedAfter |
String |
Nein |
Gibt nur Jobs zurück, die nach diesem Datum/dieser Uhrzeit abgeschlossen wurden. ISO-Format: yyyy-MM-ddTHH:mm:ss. |
|
jobFinishedBefore |
String |
Nein |
Gibt nur Jobs zurück, die vor diesem Datum/dieser Uhrzeit abgeschlossen wurden. ISO-Format: yyyy-MM-ddTHH:mm:ss. |
|
category |
String |
Nein |
Filtert nach Job-Kategorie. Die Kategorie-Zeichenkette muss in MOXIS vordefiniert sein. |
|
constituentSearchString |
String |
Nein |
Filtert nach der E-Mail-Adresse des Job-Inhabers (Constituent). |
|
documentSearchString |
String |
Nein |
Filtert nach Dokumentdateiname, ohne Dateierweiterung. |
|
offset |
Int |
Nein |
Nullbasierte Startposition für die Paginierung. Standardwert 0. |
|
pageSize |
Int |
Nein |
Anzahl der pro Seite zurückgegebenen Ergebnisse. Standardwert 50. |
10.3. Request-Body
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Request-Body.
10.4. Antwort
Gibt ein JSON-Array von Objekten zurück, die jeweils processInstanceId und status enthalten.
[
{
"processInstanceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "FINISHED_SUCCESS"
},
{
"processInstanceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"status": "ACTIVE"
}
]
|
Status |
Bedeutung |
|
200 |
Ergebnisse wurden erfolgreich zurückgegeben. |
Referenz der Job-Zustände
|
Zustand |
Beschreibung |
|
DRAFTING |
Job befindet sich im Entwurfsstatus |
|
ACTIVE |
Job läuft |
|
POST_PROCESSING |
Signatur abgeschlossen, Nachbearbeitung läuft |
|
FINISHED_SUCCESS |
Erfolgreich abgeschlossen |
|
FINISHED_FAILED |
Fehlgeschlagen |
|
DRAFT_DISMISSED |
Entwurf wurde verworfen |
|
FINISHED_TIMEOUT |
Job ist abgelaufen |
|
FINISHED_WF_CANCELLED |
Durch Workflow abgebrochen |
|
FINISHED_SIGNATURE_DENIED |
Signatur wurde verweigert |
10.4. Paginierung
Die Standard-Seitengröße beträgt 50 Ergebnisse. Verwenden Sie offset und pageSize, um durch größere Ergebnismengen zu blättern.
Erste Seite (Ergebnisse 1–50): GET .../lookupJobStates
Nächste Seite (Ergebnisse 51–100): GET .../lookupJobStates?offset=50&pageSize=50
Benutzerdefinierte Seitengröße (1–20): GET .../lookupJobStates?offset=0&pageSize=20
Um die Gesamtzahl übereinstimmender Ergebnisse vor der Paginierung zu ermitteln, verwenden Sie countLookupJobStates mit denselben Query-Parametern.
10.5. Beispiele
Alle Jobs (erste 50 Ergebnisse):
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/lookupJobStates
Authorization: Basic <base64-encoded-credentials>
Mit Paginierung (Ergebnisse 51–70):
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/lookupJobStates?offset=50&pageSize=20
Authorization: Basic <base64-encoded-credentials>
Filtern nach Zeitraum:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/lookupJobStates?jobFinishedAfter=2020-02-28T06:55:13.000-00:00&jobFinishedBefore=2020-07-11T14:55:13.000-00:00
Authorization: Basic <base64-encoded-credentials>
Filtern nach Job-Zustand:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/lookupJobStates?lookupStates=FINISHED_FAILED,FINISHED_SUCCESS
Authorization: Basic <base64-encoded-credentials>
11. GET Count Lookup Job States
Zählt die Anzahl der Jobs, die einem bestimmten Satz von Filterkriterien entsprechen, ohne die Job-Datensätze selbst abzurufen.
11.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/countLookupJobStates
11.2. Parameter
Akzeptiert dieselben Query-Parameter wie lookupJobStates. Alle Parameter sind optional.
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processIds |
String |
Nein |
Filtert nach der ID der Prozessvorlage. |
|
referenceId |
String |
Nein |
Filtert nach einer benutzerdefinierten Reference-ID. |
|
lookupStates |
String |
Nein |
Durch Kommas getrennte Liste von Job-Zuständen (z. B. FINISHED_SUCCESS,ACTIVE). |
|
jobFinishedAfter |
String |
Nein |
Jobs, die nach diesem Datum/dieser Uhrzeit abgeschlossen wurden. ISO-Format: yyyy-MM-ddTHH:mm:ss. |
|
jobFinishedBefore |
String |
Nein |
Jobs, die vor diesem Datum/dieser Uhrzeit abgeschlossen wurden. ISO-Format: yyyy-MM-ddTHH:mm:ss. |
|
category |
String |
Nein |
Filtert nach der Job-Kategorie-Zeichenkette. |
|
constituentSearchString |
String |
Nein |
Filtert nach der E-Mail-Adresse des Job-Inhabers. |
|
documentSearchString |
String |
Nein |
Filtert nach Dokumentdateiname ohne Erweiterung. |
|
offset |
Int |
Nein |
Start-Offset für die Zählung (einschließlich). |
|
pageSize |
Int |
Nein |
Chunk-Größe für die Zählung. |
11.3. Request-Body
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Request-Body.
11.4. Antwort
Gibt eine einzelne Long-Ganzzahl zurück, die die Anzahl der übereinstimmenden Jobs darstellt.
|
Status |
Bedeutung |
|
200 |
Anzahl wurde erfolgreich zurückgegeben. |
11.5. Hinweise
-
Verwenden Sie diesen Endpunkt zusammen mit lookupJobStates, um Paginierung zu implementieren: Rufen Sie zunächst countLookupJobStates auf, um die Gesamtzahl der Ergebnisse zu bestimmen, und blättern Sie dann mithilfe von offset und pageSize in lookupJobStates durch die Ergebnisse.
-
Die Verwendung derselben Filterparameter für beide Endpunkte gewährleistet konsistente Ergebnisse.
11.6. Beispiel
Alle erfolgreich abgeschlossenen Jobs zählen:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/countLookupJobStates?lookupStates=FINISHED_SUCCESS
Authorization: Basic <base64-encoded-credentials>
Alle Jobs zählen, die innerhalb eines bestimmten Zeitraums abgeschlossen wurden:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/countLookupJobStates?jobFinishedAfter=2024-01-01T00:00:00&jobFinishedBefore=2024-02-01T00:00:00
Authorization: Basic <base64-encoded-credentials>
12. Reference-ID-Methoden
MOXIS v4.52 und höher unterstützt benutzerdefinierte Reference-IDs. Damit können Integrationspartner Jobs und Dokumente über ihre eigenen Identifikatoren abrufen, anstatt über die von MOXIS vergebene processInstanceId.
12.1. Über referenceId
Legen Sie beim Erstellen eines Jobs eine benutzerdefinierte Reference-ID fest, indem Sie diese in den metaData-Block von jobDescription einfügen:
{
"constituent": {
"classifier": "EMAIL",
"name": "owner@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
},
"metaData": {
"referenceId": "CONTRACT-2024-001"
},
"iterationData": [...]
}
Die referenceId ist dazu bestimmt, innerhalb Ihres Systems eindeutig zu sein. MOXIS erzwingt die Eindeutigkeit bei der Erstellung nicht. Wenn mehrere Jobs dieselbe referenceId verwenden, ist das Verhalten dieser Endpunkte nicht definiert und die Ergebnisse können unvorhersehbar sein. Stellen Sie die Eindeutigkeit in Ihrer Integrationsschicht sicher.
Sie können auch in den Endpunkten lookupJobStates und countLookupJobStates über den Query-Parameter referenceId nach referenceId filtern.
12.2. GET getJobStateByReferenceId
Ruft den aktuellen Status und alle Details eines Jobs über Ihre eigene Reference-ID ab.
12.2.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobStateByReferenceId/{referenceId}/{nameClassifier}
12.2.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
referenceId |
String |
Ja |
Ihre benutzerdefinierte Reference-ID, wie in jobDescription.metaData.referenceId festgelegt. |
|
nameClassifier |
String |
Ja |
Identifiziert den anfragenden Benutzer. Verwenden Sie die MOXIS-ID, den UPN oder die E-Mail-Adresse des Benutzers. |
12.2.3. Antwort
Gibt dasselbe JSON-Jobstatus-Objekt zurück wie getJobState.
|
Status |
Bedeutung |
|
200 |
Jobstatus wurde erfolgreich zurückgegeben. |
12.2.4. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobStateByReferenceId/CONTRACT-2024-001/owner@xitrust.com
Authorization: Basic <base64-encoded-credentials>
12.3. GET getDocumentByReferenceId
Lädt das signierte Hauptdokument eines Jobs über Ihre eigene Reference-ID herunter.
12.3.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocumentByReferenceId/{referenceId}
12.3.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
referenceId |
String |
Ja |
Ihre benutzerdefinierte Reference-ID, wie in jobDescription.metaData.referenceId festgelegt. |
12.3.3. Antwort
Gibt das Hauptdokument als binäres PDF-Blob zurück.
|
Status |
Bedeutung |
|
200 |
Dokument wurde erfolgreich zurückgegeben. |
12.3.4. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocumentByReferenceId/CONTRACT-2024-001
Authorization: Basic <base64-encoded-credentials>
12.4. GET getAttachmentsByReferenceId
Lädt alle Anhangsdokumente eines Jobs über Ihre eigene Reference-ID herunter.
12.4.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getAttachmentsByReferenceId/{referenceId}
12.4.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
referenceId |
String |
Ja |
Ihre benutzerdefinierte Reference-ID, wie in jobDescription.metaData.referenceId festgelegt. |
12.4.3. Antwort
Gibt die Anhänge als binäres Blob zurück.
-
Wenn der Job mehrere Anhänge hat, werden diese als ZIP-Archiv zurückgegeben.
-
Wenn der Job nur einen Anhang hat, wird dieser direkt als PDF-Datei zurückgegeben.
|
Status |
Bedeutung |
|
200 |
Anhänge wurden erfolgreich zurückgegeben. |
12.4.4. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getAttachmentsByReferenceId/CONTRACT-2024-001
Authorization: Basic <base64-encoded-credentials>
12.5. GET getMultisignDocumentsByReferenceId
Lädt alle Hauptdokumente eines Multi-Sign-Jobs über Ihre eigene Reference-ID herunter.
12.5.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getMultisignDocumentsByReferenceId/{referenceId}
12.5.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
referenceId |
String |
Ja |
Ihre benutzerdefinierte Reference-ID, wie in jobDescription.metaData.referenceId festgelegt. |
12.5.3. Antwort
Gibt alle Hauptdokumente als binäres ZIP-Archiv zurück.
|
Status |
Bedeutung |
|
200 |
Dokumente wurden erfolgreich als ZIP-Blob zurückgegeben. |
12.5.4. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getMultisignDocumentsByReferenceId/BATCH-2024-001
Authorization: Basic <base64-encoded-credentials>
13. GET Report
Laden Sie den Prüf- und Signaturbericht für einen abgeschlossenen Signaturauftrag als PDF herunter.
13.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getReport/{processInstanceId}/{language}
13.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja |
Die ID des abgeschlossenen Jobs, für den der Bericht erstellt werden soll. |
|
language |
String |
Ja |
Die Sprache für den Berichtsinhalt. Verwenden Sie einen zweistelligen Sprachcode, z. B. en für Englisch oder de für Deutsch. |
13.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
13.4. Antwort
Gibt den Signaturbericht als binäres PDF-Blob zurück.
|
Status |
Bedeutung |
|
200 |
Bericht erfolgreich als PDF-Blob zurückgegeben. |
13.5. Hinweise
-
Der Bericht enthält Prüfpfadinformationen für den Signaturprozess, einschließlich Signaturzertifikaten und Zeitstempeln.
-
Der Bericht ist in der Regel erst aussagekräftig, wenn der Job einen Endzustand erreicht hat (FINISHED_SUCCESS, FINISHED_SIGNATURE_DENIED usw.). Verwenden Sie getJobState, um den Jobstatus zu prüfen, bevor Sie den Bericht anfordern.
-
Die verfügbaren Sprachen hängen von der MOXIS-Konfiguration ab. Gängige Werte sind en (Englisch) und de (Deutsch).
13.6. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getReport/a1b2c3d4-e5f6-7890-abcd-ef1234567890/en
Authorization: Basic <base64-encoded-credentials>
14. GET Document
Laden Sie das Hauptdokument eines abgeschlossenen Signaturauftrags herunter.
14.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/{processInstanceId}
14.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja |
Die ID des Jobs, dessen Hauptdokument Sie abrufen möchten. |
14.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
14.4. Antwort
Gibt das Hauptdokument als binäres PDF-Blob zurück.
|
Status |
Bedeutung |
|
200 |
Dokument erfolgreich als PDF-Blob zurückgegeben. |
14.5. Hinweise
-
Dieser Endpunkt ruft nur das Hauptdokument ab. Die einzelne PDF-Datei, die bei der Erstellung des Jobs als documentToSign übergeben wurde.
-
Um Anhänge herunterzuladen, verwenden Sie getAttachments.
-
Um alle Hauptdokumente eines Multi-Sign-Jobs herunterzuladen, verwenden Sie getMultiSignDocuments.
-
Das Dokument wird in der Regel abgerufen, sobald der Job den Status FINISHED_SUCCESS erreicht hat. Verwenden Sie getJobState, um den Abschluss abzufragen.
14.6. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Basic <base64-encoded-credentials>
15. GET Multi-Sign Documents
Laden Sie alle Hauptdokumente eines Multi-Sign-Jobs als ZIP-Archiv herunter.
15.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getMultiSignDocuments/{processInstanceId}
15.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja |
Die ID des Multi-Sign-Jobs, dessen Dokumente Sie abrufen möchten. |
15.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
15.4. Antwort
Gibt alle Hauptdokumente als binäres ZIP-Archiv zurück.
|
Status |
Bedeutung |
|
200 |
Dokumente erfolgreich als ZIP-Blob zurückgegeben. |
15.5. Hinweise
-
Dieser Endpunkt ist für Aufträge vorgesehen, die mit startMultiSignProcess oder createMultiSignDraft erstellt wurden und mehrere documentsToSign akzeptieren.
-
Für Aufträge mit nur einem Dokument verwenden Sie stattdessen getDocument.
-
Um Anhänge (keine Hauptdokumente) abzurufen, verwenden Sie getAttachments.
-
Sie können Multi-Sign-Dokumente auch über eine benutzerdefinierte Referenz-ID mit getMultisignDocumentsByReferenceId abrufen.
15.6. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getMultiSignDocuments/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Basic <base64-encoded-credentials>
16. GET Attachments
Laden Sie alle Anhangdokumente herunter, die zu einem Signaturauftrag gehören.
16.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getAttachments/{processInstanceId}
16.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja |
Die ID des Jobs, dessen Anhänge Sie abrufen möchten. |
16.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
16.4. Antwort
Gibt die Anhänge als binäres Blob zurück.
|
Status |
Bedeutung |
|
200 |
Anhänge erfolgreich zurückgegeben. |
-
Wenn der Job mehrere Anhänge hat, werden diese als ein einzelnes ZIP-Archiv zurückgegeben.
-
Wenn der Job nur einen Anhang hat, wird dieser direkt als PDF-Datei zurückgegeben.
16.5. Hinweise
-
Dieser Endpunkt ruft nur Dateien ab, die bei der Job-Erstellung als attachments übergeben wurden, nicht das Hauptdokument documentToSign.
-
Um das signierte Hauptdokument abzurufen, verwenden Sie getDocument.
-
Um Hauptdokumente eines Multi-Sign-Jobs abzurufen, verwenden Sie getMultiSignDocuments.
-
Sie können Anhänge auch über eine benutzerdefinierte Referenz-ID mit getAttachmentsByReferenceId abrufen.
16.6. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getAttachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Basic <base64-encoded-credentials>
17. PUT Cancel Job
Brechen Sie einen aktiven Signaturauftrag ab und halten Sie den Signaturprozess an, ohne den Job-Datensatz zu löschen.
17.1. Endpunkt
PUT https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/cancelJob/{processInstanceId}
17.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja |
Die ID des abzubrechenden Jobs. Wird bei der Erstellung von startProcess oder createDraft zurückgegeben. |
17.3. Anfragetext
Die Anfrage muss multipart/form-data verwenden. Geben Sie den Constituent (den Benutzer, der den Abbruch anfordert) als JSON-Objekt an.
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
user |
JSON-String |
Ja |
Identifiziert den Constituent, der den Abbruch anfordert. |
{
"classifier": "EMAIL",
"name": "max.test@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
}
17.4. Antwort
Gibt bei Erfolg HTTP 200 OK zurück. Es wird kein Antworttext zurückgegeben.
|
Status |
Bedeutung |
|
200 |
Job erfolgreich abgebrochen. |
17.5. Hinweise
-
cancelJob löscht den Job nicht. Der Job-Datensatz bleibt in MOXIS bestehen und wechselt in einen abgebrochenen/abgeschlossenen Zustand.
-
Um einen abgebrochenen Job dauerhaft zu entfernen, verwenden Sie deleteClosedJob.
-
Aufträge werden automatisch gelöscht, nachdem ihr Enddatum verstrichen ist. Der Aufbewahrungszeitraum bis zum Enddatum ist je MOXIS-Anwendungsstufe konfigurierbar.
-
Abhängig von der MOXIS-Systemkonfiguration dürfen Administratoren unter Umständen auch Aufträge anderer Benutzer abbrechen.
17.6. Beispiel
PUT https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/cancelJob/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Basic <base64-encoded-credentials>
Content-Type: multipart/form-data; boundary=----FormBoundary
------FormBoundary
Content-Disposition: form-data; name="user"
{
"classifier": "EMAIL",
"name": "max.test@xitrust.com",
"@class": "com.xitrust.moxispe.api.User"
}
------FormBoundary--
18. GET Delete Closed Job
Löschen Sie einen bereits abgebrochenen Job dauerhaft.
18.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/deleteClosedJob/{processInstanceId}
18.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja |
Die ID des zu löschenden, abgebrochenen Jobs. |
18.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
18.4. Antwort
Gibt bei Erfolg HTTP 200 OK zurück. Es wird kein Antworttext zurückgegeben.
|
Status |
Bedeutung |
|
200 |
Job erfolgreich gelöscht. |
18.5. Hinweise
-
Trotz des Namens verwendet dieser Endpunkt die HTTP-Methode GET.
-
Dieser Endpunkt funktioniert nur bei Aufträgen, die bereits über cancelJob abgebrochen wurden. Ein aktiver oder laufender Job kann mit dieser Methode nicht gelöscht werden.
-
Wenn Sie einen aktiven Job entfernen müssen, brechen Sie ihn zunächst mit cancelJob ab und löschen Sie ihn anschließend mit deleteClosedJob.
-
Aufträge werden nach Erreichen ihres konfigurierten Enddatums automatisch ohne manuellen Eingriff gelöscht. Verwenden Sie diesen Endpunkt nur, wenn eine sofortige Löschung erforderlich ist.
18.6. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/deleteClosedJob/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Basic <base64-encoded-credentials>
19. GET Placeholder
Erzeugen Sie ein Signaturplatzhalter-Bild, das vor der Übermittlung an MOXIS in ein PDF eingebettet werden kann. Der Platzhalter kodiert die Identität des Signers und Iterationsdaten in seinen EXIF-Metadaten und im QR-Code, sodass MOXIS die Signaturkonfiguration beim Empfang des Dokuments automatisch auslesen kann.
19.1. GET getPlaceholder
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getPlaceholder
19.1.1. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
iteration |
Int |
Ja |
Die Iterationsnummer, zu der der Platzhalter gehört. Beginnt bei 0. |
|
signer |
String |
Ja |
Identifiziert den Benutzer oder die Gruppe, für die der Platzhalter bestimmt ist. Verwenden Sie den Benutzernamen, UPN, die E-Mail-Adresse oder den Gruppennamen. |
|
signerType |
String |
Ja |
Der Typ des Signers. Einer von: PERSON, GROUP oder ROLE. |
|
signatureType |
String |
Ja |
Die Signaturqualität. Eine von: QSIG, EXTERNAL_QSIG, APPROVAL oder EXTERNAL_APPROVAL. Siehe Signaturqualitäten. |
|
classifier |
String |
Nein |
Wie der Wert von signer interpretiert werden soll. Einer von: ID, UPN oder EMAIL. |
|
placeHolderText |
String |
Nein |
Eine auf dem Platzhalter-Bild angezeigte Bezeichnung (z. B. "Signature"). |
|
externalEmail |
String |
Nein |
In den Platzhalter einzubettende E-Mail-Adresse für einen externen Benutzer. |
19.1.2. Antwort
Gibt ein Platzhalter-Bild als binäres PNG-Blob zurück.
|
Status |
Bedeutung |
|
200 |
Platzhalter-Bild erfolgreich zurückgegeben. |
19.1.3. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getPlaceholder?iteration=0&signer=moxisSigner&signerType=ROLE&signatureType=QSIG&placeHolderText=Unterschrift
Authorization: Basic <base64-encoded-credentials>
19.2. GET getPlaceholderWithSize
Erzeugen Sie ein Platzhalter-Bild mit einer expliziten Größenbeschränkung. Identisch zu getPlaceholder, mit einem zusätzlichen Parameter.
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getPlaceholderWithSize
19.2.1. Parameter
Alle Parameter von getPlaceholder gelten, zusätzlich:
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
iteration |
Int |
Ja |
Die Iterationsnummer. Beginnt bei 0. |
|
signer |
String |
Ja |
Identifiziert den Benutzer oder die Gruppe. |
|
signerType |
String |
Ja |
PERSON, GROUP oder ROLE. |
|
signatureType |
String |
Ja |
QSIG, EXTERNAL_QSIG, APPROVAL oder EXTERNAL_APPROVAL. |
|
classifier |
String |
Nein |
ID, UPN oder EMAIL. |
|
placeHolderText |
String |
Nein |
Auf dem Platzhalter-Bild angezeigte Bezeichnung. |
|
externalEmail |
String |
Nein |
E-Mail-Adresse für den Platzhalter eines externen Benutzers. |
|
placeHolderSize |
String |
Nein |
Steuert die Abmessungen des Ausgabebilds. Eine von: SMALL, MEDIUM oder LARGE. |
19.2.2. Antwort
Gibt ein Platzhalter-Bild als binäres PNG-Blob zurück.
|
Status |
Bedeutung |
|
200 |
Platzhalter-Bild erfolgreich zurückgegeben. |
19.2.3. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getPlaceholderWithSize?iteration=0&signer=moxisSigner&signerType=ROLE&placeHolderSize=SMALL&signatureType=QSIG&placeHolderText=Unterschrift
Authorization: Basic <base64-encoded-credentials>
19.3. Hinweise
-
Platzhalter unterstützen sowohl individuelle (persönliche) als auch Gruppen-Signaturszenarien. Ein persönlicher Platzhalter richtet sich an eine bestimmte Einzelperson; ein Gruppen-Platzhalter erlaubt jedem Mitglied der konfigurierten Gruppe die Signatur.
-
Wenn ein PDF mit eingebetteten Platzhaltern an MOXIS übermittelt wird und der betreffende Prozess für deren Auswertung konfiguriert ist, liest MOXIS die Platzhalter-Metadaten automatisch aus. Es sind keine zusätzlichen Angaben zu positionType oder Koordinaten in jobDescription erforderlich.
-
Persönliche Platzhalter erfordern keine zusätzlichen Angaben in iterationData in der Jobbeschreibung, während Gruppen-Platzhalter Gruppeninformationen in der Iteration benötigen.
-
Die Kombination von persönlichen und Gruppen-Platzhaltern in einem einzigen Job wird nur unterstützt, wenn sie sich in unterschiedlichen Iterationen befinden.
-
Der Endpunkt getQrCodeForExternalMeqaSigner ist veraltet und wird nicht weiter aktualisiert. Das Produkt MEQA wurde durch MOXIS Guest (MOGU) ersetzt. Verwenden Sie stattdessen die im Jobstatus zurückgegebene externalSignerUrl für den Zugriff externer Signer.
-
Um zu prüfen, ob die Platzhalter in einem bestehenden PDF vor der Übermittlung eines Jobs korrekt konfiguriert sind, verwenden Sie placeholderInfo.
20. POST Placeholder Info
Validieren Sie die in einem PDF-Dokument eingebetteten Signaturplatzhalter, bevor Sie es als Teil eines Signaturauftrags an MOXIS übermitteln.
20.1. Endpunkt
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/placeholderInfo/{processParameterId}/{owner}
20.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processParameterId |
String |
Ja |
Die Prozess-Referenz-ID, gegen die das Dokument übermittelt wird. |
|
owner |
String |
Ja |
Der Benutzerkontext, unter dem die Validierung angewendet werden soll (in der Regel der Constituent/Eigentümer). |
20.3. Anfragetext
Die Anfrage muss multipart/form-data verwenden. Ein Anfragetext ist zwingend erforderlich — ohne ihn schlägt der Endpunkt fehl.
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
document |
Binär (PDF) |
Ja |
Die zu validierende PDF-Datei, übermittelt mit dem Schlüssel document:file. |
|
classifierType |
String |
Nein |
Wie Benutzer in den Platzhaltern identifiziert werden. Einer von: ID, EMAIL oder UPN. Standardwert ist UPN. |
20.4. Antwort
Gibt ein JSON-Objekt mit den Validierungsdetails der Platzhalter für jede im Dokument gefundene Iteration zurück.
|
Status |
Bedeutung |
|
200 |
Validierung abgeschlossen. Prüfen Sie den Antworttext auf die Ergebnisse je Platzhalter. |
20.4.1. Beispiel für die Antwortstruktur
{
"iterations": [
{
"iterationNumber": 0,
"valid": true,
"placeholders": [
{
"signer": "signer@xitrust.com",
"signerType": "PERSON",
"signatureType": "QSIG",
"valid": true,
"failureCode": null
}
]
}
]
}
20.5. Anwendungsfall
Verwenden Sie placeholderInfo als Vorabprüfung, bevor Sie startProcess oder createDraft aufrufen. So können Sie fehlerhaft konfigurierte oder nicht erkannte Platzhalter erkennen, bevor der Job erstellt wird, und Fehler bei der Job-Erstellung oder unerwartetes Signaturverhalten vermeiden.
20.6. Hinweise
-
Ein Anfragetext ist zwingend erforderlich. Der Endpunkt funktioniert ohne das Feld document:file nicht.
-
Fehlercodes und ein detailliertes Antwortmodell für spezifische Validierungsfehler sind auf Anfrage bei MOXIS erhältlich.
20.7. Beispiel
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/placeholderInfo/my-process-id/owner@xitrust.com
Authorization: Basic <base64-encoded-credentials>
Content-Type: multipart/form-data; boundary=----FormBoundary
------FormBoundary
Content-Disposition: form-data; name="document:file"; filename="contract-with-placeholders.pdf"
Content-Type: application/pdf
<binary PDF content>
------FormBoundary
Content-Disposition: form-data; name="classifierType"
UPN
------FormBoundary--
21. GET Find MOXIS User
Suchen Sie einen MOXIS-Benutzer anhand seiner E-Mail-Adresse, um zu prüfen, ob er im System vorhanden ist, und um seine zugewiesenen Rollen und Gruppen abzurufen.
21.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/findMoxisUser?email=user@example.com
21.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
|
String |
Ja |
Die E-Mail-Adresse des zu suchenden Benutzers. |
21.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
21.4. Antwort
Gibt ein JSON-Objekt mit der MOXIS-ID, dem Namen sowie den zugewiesenen Rollen und Gruppen des Benutzers zurück.
|
Status |
Bedeutung |
|
200 |
Benutzer gefunden — Details werden im Antworttext zurückgegeben. |
|
404 |
Es wurde kein Benutzer mit der angegebenen E-Mail-Adresse gefunden. |
21.4.1. Beispielantwort
{
"userId": "abc123de-f456-7890-abcd-ef1234567890",
"name": "Max Test",
"email": "max.test@xitrust.com",
"groups": [
"moxisUser",
"moxisApprover",
"moxisOwner"
]
}
21.5. Anwendungsfall
Verwenden Sie diesen Endpunkt, um zu prüfen, ob ein Benutzer in MOXIS vorhanden ist und über die erforderlichen Rollen verfügt, bevor Sie einen Job erstellen, der ihn als Signer oder Constituent referenziert. Gängige zu prüfende Rollen:
|
Rolle |
Zweck |
|
moxisUser |
Erforderlich für die Anmeldung an der MOXIS-Benutzeroberfläche |
|
moxisApprover |
Erforderlich für Signaturen der Genehmigungskategorie (SES/SES+) |
|
moxisSigner |
Erforderlich für qualifizierte (QSIG) Signaturen |
|
moxisOwner |
Erforderlich, um Aufträge über ein Benutzerkonto zu erstellen |
21.6. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/findMoxisUser?email=max.test@xitrust.com
Authorization: Basic <base64-encoded-credentials>
22. GET Licenses
Exportieren Sie Lizenznutzungsdaten für einen festgelegten Zeitraum als ZIP-Archiv mit CSV-Dateien.
22.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getLicenses?fromDate=2024-01-01&toDate=2024-02-01
22.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
fromDate |
String |
Ja |
Beginn des Berichtszeitraums (einschließlich). Format: yyyy-mm-dd. |
|
toDate |
String |
Ja |
Ende des Berichtszeitraums (einschließlich). Format: yyyy-mm-dd. |
22.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
22.4. Antwort
Gibt ein ZIP-Archiv mit einer oder mehreren CSV-Dateien zurück, die die Lizenznutzungsdaten für den angegebenen Zeitraum enthalten.
|
Status |
Bedeutung |
|
200 |
Lizenzdaten erfolgreich als ZIP-Blob zurückgegeben. |
|
403 |
Zugriff verweigert: Der Webservice-Benutzer verfügt nicht über die Rolle reporting. |
22.5. Anforderungen
Der Webservice-Benutzer, der diese Anfrage stellt, muss in MOXIS die Rolle reporting zugewiesen haben. Anfragen von Benutzern ohne diese Rolle werden abgelehnt.
22.6. Hinweise
-
Die CSV-Dateien im ZIP-Archiv enthalten lizenzrelevante Datenbankeinträge für den angegebenen Zeitraum.
-
Verwenden Sie diesen Endpunkt für Compliance-Berichte, Abrechnungsabgleiche oder Lizenzprüfungen.
22.7. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getLicenses?fromDate=2024-01-01&toDate=2024-02-01
Authorization: Basic <base64-encoded-credentials>
23. POST Get Token (OAuth via Keycloak)
Beziehen Sie ein OAuth-2.0-Bearer-Token zur Authentifizierung nachfolgender MOXIS-API-Anfragen.
23.1. Endpunkt
POST <token-url>/protocol/openid-connect/token
Die <token-url> ist spezifisch für Ihre MOXIS-Keycloak-Instanz. Sie wird von MOXIS bei der Konfiguration bereitgestellt und ist von der Standard-MOXIS-API-Basis-URL getrennt.
23.2. Anforderungen
-
MOXIS Version v4.52 oder höher
-
Keycloak 24 oder höher, integriert in Ihre MOXIS-Instanz
-
Konfiguration wurde durch MOXIS durchgeführt. Dies kann nicht selbst über die MOXIS-Benutzeroberfläche konfiguriert werden
23.3. Anfragetext
Die Anfrage muss application/x-www-form-urlencoded verwenden (Standard-OAuth-2.0-Formularkodierung).
|
Feld |
Typ |
Erforderlich |
Beschreibung |
|
client_id |
String |
Ja |
Die Ihrer Integration zugewiesene Client-ID. Wird von MOXIS bereitgestellt. |
|
client_secret |
String |
Ja |
Das Client-Secret für Ihre Integration. Wird von MOXIS bereitgestellt. |
|
username |
String |
Ja |
Der Benutzername des technischen Webservice-Benutzers. |
|
password |
String |
Ja |
Das Passwort des technischen Webservice-Benutzers. |
|
grant_type |
String |
Ja |
Muss password sein. |
|
scope |
String |
Ja |
Muss openid sein. |
23.4. Antwort
Gibt bei Erfolg einen Bearer-Token-String zurück.
{
"access_token": "<bearer-token-string>",
"token_type": "Bearer",
"expires_in": 300
}
|
Status |
Bedeutung |
|
200 |
Token erfolgreich ausgestellt. |
|
401 |
Authentifizierung fehlgeschlagen — ungültige Anmeldedaten. |
23.5. Verwendung
Fügen Sie das Token in den Authorization-Header aller nachfolgenden MOXIS-API-Anfragen ein:
Authorization: Bearer <access_token>
Tokens haben eine begrenzte Lebensdauer (expires_in Sekunden). Ihre Integration muss den Ablauf des Tokens berücksichtigen und rechtzeitig vor Ablauf des aktuellen Tokens ein neues anfordern.
23.6. Hinweise
-
Dieser Token-Endpunkt ist nicht Teil der Standard-MOXIS-REST-API-Basis-URL (/webservices/rest/api/layer2/v1.0). Die <token-url> ist ein separater Keycloak-Endpunkt.
-
Die Keycloak-Integration und die Client-Anmeldedaten werden ausschließlich von MOXIS konfiguriert. Wenden Sie sich an MOXIS, um OAuth für Ihre Integration einzurichten.
-
Die Basisauthentifizierung (Benutzername und Passwort im Authorization-Header) bleibt als Alternative verfügbar, falls Keycloak nicht konfiguriert ist.
23.7. Beispiel
POST https://<keycloak-base-url>/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
client_id=my-client-id&client_secret=my-client-secret&username=ws-user&password=ws-password&grant_type=password&scope=openid
24. GET Dynamic Key Link
Rufen Sie eine einmalig verwendbare Registrierungs-URL für ein unterstütztes Trust Center und einen Identitätsanbieter ab, um einen Signer mit einer neuen digitalen Identität zu onboarden.
24.1. Endpunkt
GET https://<moxis-base-url>/xignup/getDynamicKeyLink?trustCenter=ATRUST&identityProvider=NECT
Beachten Sie, dass dieser Endpunkt unter dem Pfad /xignup auf Ihrer MOXIS-Instanz bereitgestellt wird und nicht unter dem Standard-API-Basispfad /webservices/rest/api/layer2/v1.0, der von den anderen Endpunkten in dieser Referenz verwendet wird.
24.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
trustCenter |
String |
Ja |
Das Trust Center, bei dem die Registrierung erfolgen soll, z. B. ATRUST. |
|
identityProvider |
String |
Ja |
Der für die Registrierung zu verwendende Identitätsanbieter, z. B. NECT. |
24.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
24.4. Antwort
Gibt eine URL (String) für die Registrierung mit einem einmaligen Schlüssel zurück.
|
Status |
Bedeutung |
|
200 |
Registrierungs-URL erfolgreich zurückgegeben. |
24.5. Hinweise
-
Die zurückgegebene URL ist einmalig verwendbar und dient dazu, einem Signer die Registrierung einer digitalen Identität beim angegebenen Trust Center und Identitätsanbieter zu ermöglichen, bevor eine qualifizierte Signatur abgeschlossen wird.
-
Die unterstützten Werte für trustCenter und identityProvider hängen davon ab, welche Trust Center und Identitätsanbieter für Ihre MOXIS-Instanz konfiguriert sind. Wenden Sie sich an Ihren MOXIS-Administrator, um die für Ihre Umgebung gültigen Werte zu erfahren.
24.6. Beispiel
GET https://<moxis-base-url>/xignup/getDynamicKeyLink?trustCenter=ATRUST&identityProvider=NECT
Authorization: Basic <base64-encoded-credentials>
25. GET Job Document Download State (Download-Tracking)
Ruft ab, welche externen Empfänger die Dokumente eines Jobs bereits heruntergeladen haben — inklusive Zeitpunkt, Format (Einzeldatei oder ZIP) und Signaturstatus zum Zeitpunkt des Downloads. Erfasst werden sowohl Einzeldateidownloads als auch ZIP-Downloads über MOXIS Guest (MOGU); die Ereignisse werden für Auditing- und Analysezwecke gespeichert.
25.1. Endpunkt
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobDocumentDownloadState/<processInstanceId>
Alternativ über Ihre eigene Reference-ID:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobDocumentDownloadStateByReferenceId/<referenceId>
25.2. Parameter
|
Parameter |
Typ |
Erforderlich |
Beschreibung |
|
processInstanceId |
String |
Ja, bei getJobDocumentDownloadState |
Die ID des Jobs, dessen Download-Status Sie abrufen möchten. |
|
referenceId |
String |
Ja, bei getJobDocumentDownloadStateByReferenceId |
Ihre eigene Reference-ID für den Job, siehe Kapitel 12. |
25.3. Anfragetext
Keiner. Dies ist eine GET-Anfrage und akzeptiert keinen Anfragetext.
25.4. Antwort
Gibt für jedes Hauptdokument des Jobs die Liste der Benutzer zurück, die darauf zugegriffen haben, inklusive aller einzelnen Download-Ereignisse.
{
"jobId": "43255",
"referenceId": null,
"currentJobState": "FINISHED_SUCCESS",
"documents": [
{
"documentId": 143151,
"documentName": "Lorem ipsum dolor sit amet_long.pdf",
"users": [
{
"userId": "externi2@externi.com",
"name": "externi2",
"email": "externi2@externi.com",
"userType": "EXTERNAL",
"downloadEvents": [
{
"downloadDate": 1774873713119,
"asZip": false,
"hasAlreadySigned": false,
"iterationSnapshot": 0,
"jobStateSnapshot": "FINISHED_SUCCESS",
"additionalReceiver": true,
"delegate": false
}
]
}
]
}
]
}
Felder von downloadEvents
|
Feld |
Typ |
Beschreibung |
|
downloadDate |
Number |
Zeitpunkt des Downloads als Unix-Timestamp in Millisekunden. |
|
asZip |
Boolean |
true, wenn das Dokument als Teil eines ZIP-Archivs heruntergeladen wurde. |
|
hasAlreadySigned |
Boolean |
true, wenn der Benutzer zum Zeitpunkt des Downloads bereits signiert hatte. |
|
iterationSnapshot |
Number |
Iterationsnummer zum Zeitpunkt des Downloads. |
|
jobStateSnapshot |
String |
Jobstatus zum Zeitpunkt des Downloads. |
|
additionalReceiver |
Boolean |
true, wenn der Benutzer als zusätzlicher Empfänger (nicht als Signer) auf das Dokument zugegriffen hat. |
|
delegate |
Boolean |
true, wenn der Download durch eine bevollmächtigte Vertretung erfolgte. |
25.5. Hinweise
-
Download-Tracking ist standardmäßig aktiviert und erfordert keine Konfiguration; es ist auf allen Tarifstufen inklusive Business Cloud verfügbar.
25.6. Beispiel
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobDocumentDownloadState/abc-123-def
Authorization: Basic <base64-encoded-credentials>
26. Alternative Signaturvisualisierungen
Standardmäßig kann ein Signer in MOXIS Guest beim Signieren selbst wählen, wie seine Signatur visuell dargestellt wird (Text, Bild oder Freihandzeichnung). Alternativ kann pro Job oder pro Signer ein vordefiniertes Visualisierungsprofil vorgegeben werden - ein vollständig gestalteter Signaturblock, ähnlich einer Amtssignatur. Ist ein Profil vorgegeben, entfällt die manuelle Auswahl für den betroffenen Signer; MOXIS Guest zeigt vor dem Signieren eine Vorschau des zugewiesenen Signaturblocks.
Dieses Feature ist derzeit ausschließlich über Layer2 verfügbar.
26.1. Konzept
Visualisierungsprofile werden serverseitig in MOGU als benannte Layouts hinterlegt; jedes Profil definiert das Erscheinungsbild des Signaturblocks. Felder, die im Profil nicht befüllt sind (z. B. kein Benutzerbild hinterlegt), werden automatisch ausgeblendet. Wird kein Profil angegeben, verhält sich MOGU wie bisher - der Signer wählt selbst zwischen Text, Bild und Freihandzeichnung.
26.2. Profil pro Signer festlegen
Geben Sie den Profilnamen im jeweiligen Invitee-Objekt der iterationData als visualizationLayoutId an. So können innerhalb eines Jobs verschiedene Signer unterschiedliche Visualisierungen erhalten:
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.ExternalUserForRole",
"classifier": "EMAIL",
"name": "a.k@xitrust.com",
"externalUserName": "Aragorn Kenobi",
"visualizationLayoutId": "signature-block_modern-v1",
"locale": "de",
"phoneNumber": "",
"roleName": "Extern"
}
],
"category": "EXTERNAL_APPROVAL",
"iterationNumber": 1
}
26.3. Profil zentral über Auftrags-Metadaten festlegen
Alternativ kann das Profil einmalig für alle externen Signer eines Jobs über metaData festgelegt werden. Gibt ein einzelner Invitee zusätzlich ein eigenes visualizationLayoutId an, überschreibt dieses den Metadaten-Eintrag für diesen Signer. Existiert das angegebene Profil nicht, liefert die API die Fehlermeldung visualisationLayout does not exist.
Ab MOXIS 4.56 (aktueller Ansatz): visualizationLayoutIds als Objekt, das nach Signaturqualität unterscheidet:
"metaData": {
"description": "REST-Test mit externer pers. PH",
"referenceId": "referenceId vom Vorsystem",
"visualizationLayoutIds": {
"EXTERNAL_QSIG": "signature-block_qsig",
"EXTERNAL_SES": "signature-block_ses"
}
26.4. Verfügbare Visualisierungsprofile
Im Core-Produkt ist das Profil signature-block enthalten und in jedem Deployment zu Testzwecken verfügbar. Weitere Profile können kundenindividuell erstellt und hinzugefügt werden. Folgende Profile stehen zur Verfügung:
|
Profil |
|
signature-block_modern-v1 / -v2 / -v3 |
|
signature-block_moxis-green |
|
signature-block_moxis-green-pruef |
|
signature-block_shield / signature-block_shield_extended |
|
signature-block_xitrust-extended |
|
signature-block_small |
Einige der „modern”-Varianten nutzen zusätzlich den Resolver %certificate-issuer-dn, der den DN des Zertifikatausstellers auflöst.
26.5. Hinweise
-
Unterstützung für interne Signer sowie eine kompaktere „flat”-Variante der Profile sind zum aktuellen Stand noch nicht umgesetzt.
-
Welche Profile auf Ihrer Instanz verfügbar sind, erfahren Sie von Ihrem MOXIS-Administrator.