MOXIS API Dokumentation
German English

MOXIS REST API: Erste Schritte

Inhalt

MOXIS ist eine eSignature-Plattform. Sie unterstützt das gesamte Spektrum elektronischer Signaturen – von einfachen Freigaben bis hin zu qualifizierten elektronischen Signaturen (QES) – über konfigurierbare Signaturworkflows.

Diese API ermöglicht Ihnen die Integration von MOXIS in Ihre Anwendung: Sie erstellen Signatur-Jobs, weisen Signierende zu und rufen das signierte Dokument ab, sobald der Workflow abgeschlossen ist.

Der eigentliche Signaturschritt wird von den Benutzern in der MOXIS-Web-Anwendung bzw. von externen Signierenden in MOXIS Guest durchgeführt; die API übernimmt alles rund um diesen Schritt.


1. Voraussetzungen

Bevor Sie Ihren ersten API-Aufruf durchführen, benötigen Sie folgende Informationen:

Was Sie benötigen

Wie Sie es erhalten

MOXIS-Konto

Wird von MOXIS oder Ihrem MOXIS-Administrator bereitgestellt. Sie benötigen eine aktive Instanz-URL (<moxis-base-url>).

Webservice-Benutzer

Ein technischer Benutzer mit API-Zugriff. Bei Business Cloud und Enterprise Cloud konfiguriert MOXIS diesen Benutzer. Je nach MOXIS Version kann Ihr:e MOXIS-Administrator:in im Administrationsbereich einen solchen Benutzer anlegen (siehe Authentifizierung).

Process-ID

Jeder API-Aufruf, der einen Job erstellt, benötigt eine processId. Sie finden diese im MOXIS-Prozessadministrationsbereich. Bei Business Cloud sind die Standard-Process-IDs in der Plattformübersicht dokumentiert.

Die Anmeldedaten des Webservice-Benutzers (Benutzername und Passwort) übergeben Sie per Basic Authentication oder Oauth bei jeder Anfrage.

2. Schnellstart

Schritt 1: Authentifizierung einrichten

Kodieren Sie die Anmeldedaten Ihres Webservice-Benutzers und fügen Sie sie in jede Anfrage ein:

Authorization: Basic <base64(username:password)>

Details zur Einrichtung von Basic Auth und OAuth 2.0 finden Sie unter Authentifizierung.

Schritt 2: Signatur-Job erstellen

Senden Sie das Dokument und eine JSON-Job-Beschreibung per

POST 

an den startProcess-Endpunkt:

curl -X POST "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -u "username:password" \
  -F "documentToSign=@/pfad/zu/deiner/datei.pdf;type=application/pdf" \
  -F 'jobDescription={
  "constituent": {
    "classifier": "EMAIL",
    "name": "owner@example.com",
    "@class": "com.xitrust.moxispe.api.User"
  },
  "positionType": "INVISIBLE",
  "iterationData": [
    {
      "invitees": [
        {
          "@class": "com.xitrust.moxispe.api.User",
          "classifier": "EMAIL",
          "name": "signer@example.com"
        }
      ],
      "category": "APPROVAL",
      "iterationNumber": 0
    }
  ]
};type=application/json'

Bei Erfolg liefert die Antwort den HTTP-Status 201 sowie die

processInstanceId

für diesen Job.

Schritt 3: Auf Abschluss prüfen (oder Webhook empfangen)

Verwenden Sie die zurückgegebene processInstanceId, um den Job-Status abzufragen:

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

Fragen Sie den Status ab, bis er

FINISHED_SUCCESS 

erreicht. Bei Enterprise Cloud können Sie stattdessen einen Webhook für den Prozess konfigurieren, um eine Push-Benachrichtigung zu erhalten, anstatt zu pollen – siehe API-Referenz für das Datenmodell des Job-Status-Hooks.

Schritt 4: Signiertes Dokument abrufen

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

Liefert das signierte PDF als binären Blob.

3. Testumgebung

MOXIS stellt eine Testumgebung bereit, die auf einen Testzugang von A-Trust zurückgreift. Wenden Sie sich an servicedesk@xitrust.com, um Zugangsdaten für die Testumgebung zu erhalten. Nutzen Sie die Testumgebung, um Ihre Integration vor dem produktiven Einsatz zu validieren – dort ausgestellte qualifizierte Signaturen sind reine Testsignaturen und haben keine rechtliche Gültigkeit.

4. Verwendung der MOXIS-Postman-Collection

Die Postman-Collection der MOXIS REST API ermöglicht es Ihnen, jeden API-Endpunkt zu erkunden und zu testen, ohne zunächst Code zu schreiben. Nutzen Sie sie, um Ihre Zugangsdaten zu überprüfen, Request-/Response-Strukturen zu untersuchen und Sicherheit vor der Integration in Ihre Anwendung zu gewinnen.

4.1. Voraussetzungen

  • Postman ist auf Ihrem Rechner installiert oder wird von Ihnen im Browser verwendet

4.2. Collection herunterladen und importieren

Die Collection-Datei kann hier herunter geladen werden:

Download Collection Datei

So importieren Sie sie in Postman:

  1. Öffnen Sie Postman.

  1. Klicken Sie auf Import (Menü oben links).

  1. Ziehen Sie die .json-Datei per Drag-and-Drop in den Importdialog, oder klicken Sie auf Upload Files und wählen Sie die Datei aus.

  1. Die Collection erscheint in der Seitenleiste unter Collections.

4.3. Variablen der Collection konfigurieren

Alle Anfragen in der Collection sind bereits so vorbereitet, dass sie Variablen verwenden. Sie legen diese einmal auf Ebene der Collection fest, und jede Anfrage übernimmt sie automatisch.

Sobald Ihnen Zugang zur Testumgebung gewährt wird, sendet Ihnen MOXIS eine E-Mail mit allen erforderlichen Werten:

Variable

Beispielwert

Beschreibung

restServiceBaseUrl

https://rest-test.moxis.cloud/webservices/rest/api/layer2/v1.0

Vollständige Basis-URL des REST-Dienstes

basicAuthUser

Beispielbenutzername21

Benutzername für Basic Auth (Webservice-Benutzer)

basicAuthPw

Beispielpasswort

Passwort für Basic Auth

Die Collection definiert außerdem die Variablen token und clientSecret, die nur benötigt werden, wenn für Ihre Instanz OAuth 2.0/Keycloak konfiguriert ist (siehe Authentifizierung). Lassen Sie diese bei Basic Auth unverändert leer.

Es gibt keine separate Collection-Variable processId – die Process-ID (z. B. moxisStdMultiEidas) ist Teil des URL-Pfads jeder Anfrage (zum Beispiel startProcess/moxisStdMultiEidas). Ersetzen Sie den Platzhalter-Abschnitt in der URL jeder von Ihnen verwendeten Anfrage. Verfügbare Process-IDs finden Sie unter Einschränkungen.

So legen Sie die Variablen fest:

  1. Klicken Sie in der Seitenleiste auf den Namen der Collection.

  1. Öffnen Sie den Tab Variables.

  1. Tragen Sie die Werte aus Ihrer Willkommens-E-Mail in die Spalte Current value ein.

  1. Klicken Sie auf Save.

Informationen zum Anlegen und Verwalten von Webservice-Benutzern in MOXIS finden Sie im Administrationshandbuch der MOXIS Knowledge Base.

4.4. Funktionsweise von Multipart-Anfragen

MOXIS verwendet für die Dokumentübermittlung die Kodierung multipart/form-data. Dies ist der Standard, um eine Kombination aus strukturierten Daten (das JSON der Job-Beschreibung) und Binärdaten (das PDF) in einer einzigen HTTP-Anfrage zu senden.

In Postman werden Multipart-Anfragen im Tab Body konfiguriert:

  1. Öffnen Sie die Anfrage (z. B. startProcess).

  1. Wählen Sie den Tab Body.

  1. Wählen Sie form-data.

  1. Fügen Sie zwei Schlüssel hinzu:

Schlüssel

Typ

Wert

jobDescription

Text

Fügen Sie hier Ihr jobDescription-JSON ein, oder wählen Sie eine Datei aus

documentToSign

File

Wählen Sie die zu signierende PDF-Datei aus

Um einen Schlüssel auf den Typ File zu setzen, bewegen Sie den Mauszeiger über das Schlüsselfeld – rechts erscheint ein Dropdown-Menü, mit dem Sie zwischen Text und File wechseln können.

So sieht die rohe HTTP-Anfrage aus, wenn Postman sie sendet:

POST /webservices/rest/api/layer2/v1.0/startProcess/customer42 HTTP/1.1
Authorization: Basic d3N1c2VyOnMzY3IzdA=
Content-Type: multipart/form-data; boundary=--------------------------033859937284046759776005

----------------------------033859937284046759776005
Content-Disposition: form-data; name="documentToSign"; filename="Lorem Ipsum.pdf"
<Lorem Ipsum.pdf>
----------------------------033859937284046759776005
Content-Disposition: form-data; name="jobDescription"; filename="jobDescription_directposition.json"
<jobDescription_directposition.json>
----------------------------033859937284046759776005--

Bei Erfolg liefert die Antwort den HTTP-Status 201 Created mit der

processInstanceId

des neuen Jobs im Antwortkörper.

4.5. Ihre erste Anfrage ausführen: einen Entwurf erstellen

Das Erstellen eines Entwurfs ist der sicherste erste Aufruf – dabei wird ein Signatur-Job erstellt, ohne ihn sofort an die Unterzeichnenden zu versenden.

  1. Erweitern Sie die Collection in der Seitenleiste und suchen Sie die Anfrage Create Draft.

  1. Stellen Sie sicher, dass Ihre Collection-Variablen gesetzt sind (siehe oben).

  1. Setzen Sie im Tab Body documentToSign auf ein beliebiges Test-PDF und jobDescription auf das JSON der Entwurfs-Job-Beschreibung.

  1. Klicken Sie auf Send.

  1. Eine Antwort mit

    Status 201 Created und einer processInstanceId
    

bestätigt, dass alles funktioniert.

4.6. Die Collection als Sandbox verwenden

Nutzen Sie Postman, bevor Sie Integrationscode schreiben, um:

  • Ihre Zugangsdaten und Basis-URL auf Richtigkeit zu prüfen

  • das genaue von jedem Endpunkt erwartete Anfrageformat zu untersuchen

  • vollständige Antwort-Header und -Bodys einzusehen

  • verschiedene Process-IDs (URL-Pfadsegmente) und jobDescription-Konfigurationen auszuprobieren

Sobald sich eine Anfrage in Postman wie erwartet verhält, können Sie sie in Ihrer Anwendung mit denselben Headern, Parametern und der gleichen Body-Struktur nachbilden. Fertige Codebeispiele in C#, Java, JavaScript und Node.js finden Sie in den Codebeispielen in diesem Repository.

5. QES mit der A-Trust-Testbox testen

5.1. Was es ist

Die MOXIS-Testinstanz (https://rest-test.moxis.cloud ) ist mit einer A-Trust-Testbox verbunden – einer Sandbox-Umgebung, die vom österreichischen Vertrauensdiensteanbieter A-Trust betrieben wird. Die Testbox stellt ein synthetisches Testzertifikat und eine Testidentität bereit, die sich beim Testen exakt wie eine echte qualifizierte elektronische Signatur (QES) verhalten, ohne dass Sie oder Ihre Test-Unterzeichnenden über einen tatsächlichen digitalen Ausweis verfügen müssen.

So können Sie den vollständigen End-to-End-Signaturablauf – einschließlich des QES-Challenge/Response-Verfahrens – in einem vollständig sicheren, nicht-produktiven Kontext erstellen und testen.

Wichtig: Mit der A-Trust-Testidentität erstellte Signaturen sind rechtlich nicht gültig. Sie dienen ausschließlich der Entwicklung und dem Integrationstest. Für den produktiven Einsatz ist eine echte digitale Identität erforderlich. Details zum Erwerb einer solchen finden Sie in den FAQ zur digitalen Identität.

5.2. Wann sie verwendet wird

Verwenden Sie die A-Trust-Testzugang, wenn Ihre Job-Beschreibung einen QES-Signaturtyp angibt – konkret

QSIG oder QSIG_EXTERNAL

. Andere Signaturtypen (einfach, fortgeschritten) durchlaufen den A-Trust-Ablauf nicht.

5.3. Testzugangsdaten und Testidentitäten

A-Trust stellt Testidentitäten zur Verfügung. Diese können Sie verwenden, wenn der A-Trust-Signaturdialog auf der Testinstanz erscheint: Vordefinierte Testidentitäten

Diese Zugangsdaten sind für die Testbox fest vorgegeben – sie ändern sich nicht, und es wird tatsächlich keine SMS versendet.

5.4.1. Schritt-für-Schritt: ein Dokument mit der Testidentität signieren

  1. Signatur-Job erstellen über die MOXIS-Benutzeroberfläche oder die REST API, unter Verwendung des Prozesstyps

    QSIG oder QSIG_EXTERNAL
    

und Ihres Test-PDFs.

  1. Signaturlink öffnen. Navigieren Sie entweder zum Job in der MOXIS-Benutzeroberfläche, oder verwenden Sie die von der API zurückgegebene externe Signer-URL.

  1. Zum Signieren klicken. Ein Popup-Fenster erscheint – dies ist der A-Trust-Signaturdialog.

  1. Testtelefonnummer und Passwort laut einer der vordefinierten Identitäten eingeben.

  2. TAN anfordern. Klicken Sie auf TAN via SMS. Die Testbox sendet keine echte SMS – die TAN ist immer der unten genannte feste Wert.

  3. Bestätigen. Die Signatur wird angewendet, und das Dokument wird als signiert markiert.

Dieser Ablauf funktioniert sowohl für interne MOXIS-Benutzer als auch für externe Unterzeichnende.

5.4.2. Wie die Signatur in einem PDF-Viewer angezeigt wird

Wenn Sie ein signiertes Dokument in einem PDF-Viewer (z. B. Adobe Acrobat) öffnen, ist die Signatur sichtbar und strukturell technisch gültig. Da sie jedoch mit einem Testzertifikat erstellt wurde, meldet der Viewer, dass die Zertifikatskette nicht vollständig verifiziert werden kann.

Der angezeigte Signer-Name folgt einem generischen Muster XXX... anstelle des Namens einer echten Person – dies ist bei allen Testbox-Signaturen erwartetes Verhalten.

Dies ist normal und erwartet. Es weist nicht auf einen Fehler in Ihrer Integration hin.

5.4.3. Übergang in die Produktion

Beim produktiven Einsatz signieren Ihre Endbenutzer mit ihrer eigenen qualifizierten digitalen Identität (z. B. einer echten ID_Austria Signatur oder einem anderen eIDAS-konformen Identitätsanbieter). An Ihrer API-Integration sind keine Änderungen erforderlich – der Signaturablauf ist identisch; lediglich die vom Benutzer eingegebenen Zugangsdaten unterscheiden sich.

Hinweise zu Optionen für die digitale Identität finden Sie in den FAQ zur digitalen Identität von MOXIS.

6. Authentifizierung

Die MOXIS API unterstützt zwei Authentifizierungsmethoden: HTTP Basic Authentication mit einem Webservice-Benutzer und OAuth-2.0-Bearer-Token über Keycloak (MOXIS v4.52 und höher). Basic Auth ist die einfachere Option und funktioniert in allen MOXIS Varianten. OAuth ist nur in Enterprise-Umgebungen verfügbar, in denen Keycloak von MOXIS konfiguriert wurde.

6.1. Basic Authentication

Alle API-Anfragen können mit Benutzername und Passwort eines Webservice-Benutzers über HTTP Basic Authentication (RFC 7617) authentifiziert werden.

Funktionsweise

Verbinden Sie Benutzername und Passwort mit einem Doppelpunkt, kodieren Sie das Ergebnis Base64 und fügen Sie es in den Authorization-Header jeder Anfrage ein:

Authorization: Basic <base64(username:password)>

Beispiel für Benutzername wsuser und Passwort s3cr3t:

base64("wsuser:s3cr3t") = d3N1c2VyOnMzY3IzdA==
Authorization: Basic d3N1c2VyOnMzY3IzdA==

Einen Webservice-Benutzer konfigurieren

MOXIS konfiguriert Webservice-Benutzer für Instanzen von Business Cloud und Now Cloud. In der Enterprise MOXIS Variante kann ein MOXIS-Administrator diese im Administrationsbereich der MOXIS-Weboberfläche anlegen.

  • Der Webservice-Benutzer benötigt die Rolle system und layer2.

  • Der Webservice-Benutzer handelt im Namen des in jedem API-Aufruf angegebenen Constituent – er signiert selbst keine Dokumente.

6.2. Beispielanfragen

HTTP-Anfrage-Header

GET /webservices/rest/api/layer2/v1.0/getJobState/abc-123/EMAIL HTTP/1.1
Host: http://your-instance.moxis.at 
Authorization: Basic d3N1c2VyOnMzY3IzdA==

curl

curl -X GET \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/<processInstanceId>/EMAIL" \
  -H "Authorization: Basic d3N1c2VyOnMzY3IzdA=="

Job mit Basic Auth erstellen

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

OAuth 2.0 / Bearer-Token (Keycloak)

Ab MOXIS v4.52 wird OAuth 2.0 mit dem Password-Grant-Flow über Keycloak unterstützt. Dies setzt voraus, dass MOXIS Keycloak für Ihre Instanz konfiguriert hat – es ist in Business Cloud oder Now Cloud nicht verfügbar und kann nicht selbst konfiguriert werden.

Token-Endpunkt

POST <token-url>/protocol/openid-connect/token

Die

<token-url> 

wird von MOXIS bereitgestellt, sobald Keycloak für Ihre Instanz eingerichtet ist.

Anfrageparameter

Parameter

Wert

Beschreibung

client_id

<client-id>

Von MOXIS für Ihren Keycloak-Client bereitgestellt

client_secret

<client-secret>

Zugangsdaten für den Keycloak-Client

username

<webservice-username>

Benutzername des Webservice-Benutzers

password

<user-password>

Passwort des Webservice-Benutzers

grant_type

password

Fester Wert

scope

openid

Fester Wert

Ein Token anfordern

curl -X POST \
  "<token-url>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<client-id>" \
  -d "client_secret=<client-secret>" \
  -d "username=<webservice-username>" \
  -d "password=<user-password>" \
  -d "grant_type=password" \
  -d "scope=openid"

Bei Erfolg liefert die Antwort ein JSON-Objekt mit dem Feld access_token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 300
}

Verwendung des Bearer-Tokens

Fügen Sie das Token in den Authorization-Header jeder MOXIS-API-Anfrage ein:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...

curl-Beispiel

JavaScript
curl -X POST \
  "https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/<processId>" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..." \
  -F "documentToSign=@/path/to/document.pdf;type=application/pdf" \
  -F 'jobDescription={"constituent":{...}}'

Token laufen ab (typischerweise nach 5 Minuten). Ihre Anwendung sollte 401-Antworten erkennen und das Token durch Wiederholung der Token-Anfrage aktualisieren.

6.3. Authentifizierungsfehler

Eine 302 Redirect-Antwort deutet in der Regel auf einen Authentifizierungsfehler hin – die Anfrage wurde zu einer Login-Seite umgeleitet, weil Zugangsdaten fehlten oder falsch waren. Überprüfen Sie, ob der Authorization-Header vorhanden und die Base64-Kodierung korrekt ist.