Inhalt
Diese Dokumentation beschreibt die Swisscom Qualified Seal API als separaten MOXIS-Endpunkt zum automatisierten Anbringen qualifizierter elektronischer Firmensiegel auf PDF-Dokumenten nach Schweizer Recht (ZertES). Sie erläutert die Voraussetzungen, Statuscodes, API-Methoden sowie die empfohlene Reihenfolge der Aufrufe für einen vollständigen Siegelungsprozess.
1. Swisscom Qualified Seal API
1.1. Übersicht
Die Swisscom Seal API ist ein dedizierter MOXIS-Endpunkt zum Anbringen eines qualifizierten Firmensiegels (“geregeltes Siegel”) auf PDF-Dokumenten nach Schweizer Recht (ZertES). Sie ist eine von der Haupt-MOXIS-REST-API getrennte API und speziell für automatisierte, hochvolumige Siegelungs-Workflows konzipiert, bei denen keine Interaktion mit einem menschlichen Signer erforderlich ist.
Wesentliche Merkmale:
-
Arbeitet im Rahmen des ZertES-Gesetzesrahmens (Schweiz)
-
Bringt ein elektronisches Siegel an. Es wird kein visuelles Signaturelement zum Dokument hinzugefügt
-
Unterstützt die Siegelung von bis zu 100 Dokumenten pro Sitzung in einem einzigen Vorgang
-
Erfordert die Enterprise-Stufe sowie die Konfiguration des Swisscom-Siegels durch MOXIS
Falls Sie eine visuelle Darstellung auf dem gesiegelten Dokument benötigen, fügen Sie diese vor dem Aufruf dieser API mithilfe einer PDF-Verarbeitungssoftware eines Drittanbieters hinzu.
1.2. Voraussetzungen
Bevor Sie diese API nutzen können:
-
Sie verfügen über MOXIS Enterprise.
-
MOXIS muss einen Siegel-Benutzer sowie die zugehörigen Swisscom-Siegeleinstellungen in Ihrer MOXIS-Instanz konfigurieren.
-
Sie benötigen das API-Token, das MOXIS in der Siegelkonfigurations-UI für Ihren Siegel-Benutzer generiert.
MOXIS Tipp
Wenden Sie sich an Ihre:n MOXIS Ansprechpartner:in, um Ihren Siegel-Benutzer einzurichten und die erforderliche Konfiguration zu erhalten.
1.3. Basis-Endpunkt
https://<moxis-base-url>/webservices/rest/swisscom-seal-api/
Ersetzen Sie <moxis-base-url> durch den Hostnamen Ihrer MOXIS-Instanz (z. B. moxis.yourcompany.com).
1.4. Authentifizierung
Jede Anfrage erfordert HTTP Basic Authentication (Benutzername und Passwort des Webservice-Benutzers) sowie den Query-Parameter apiToken beim Aufruf von startSession.
Authorization: Basic <base64(username:password)>
Der apiToken ist das für den Siegel-Benutzer in der MOXIS-Siegelkonfigurations-UI generierte Token. Er wird einmalig bei der Sitzungserstellung übergeben und gilt implizit für alle nachfolgenden Aufrufe innerhalb dieser Sitzung.
1.5. HTTP-Statuscodes
|
Code |
Bedeutung |
|
200 |
OK: Anfrage erfolgreich |
|
201 |
Created: Ressource erfolgreich erstellt |
|
302 |
Redirect: Deutet in der Regel auf einen Authentifizierungsfehler hin; überprüfen Sie Ihre Zugangsdaten |
|
400 |
Bad Request: Fehlerhafte Anfragestruktur, oder der Siegeldienst ist inaktiv |
|
404 |
Not Found: Die referenzierte Sitzungs-ID oder Dokument-ID existiert nicht |
|
500 |
Server Error: Es ist ein interner Fehler aufgetreten, üblicherweise durch eine ungültige Objektreferenz |
1.6. API-Methoden
1.6.1. POST startSession
Erstellt eine neue Siegelungssitzung. Rufen Sie dies einmal auf, bevor Sie Dokumente hinzufügen.
POST <base-url>/startSession?apiToken={apiToken}
Query-Parameter
|
Parameter |
Typ |
Beschreibung |
|
apiToken |
String |
Token aus der MOXIS-Siegelkonfigurations-UI für den Siegel-Benutzer |
Request Body: keiner
Response
|
Feld |
Typ |
Beschreibung |
|
— |
String |
Sitzungs-ID — verwenden Sie diese als {sessionId} in allen nachfolgenden Aufrufen |
Beispiel
POST https://moxis.yourcompany.com/webservices/rest/swisscom-seal-api/startSession?apiToken=abc123xyz
Authorization: Basic dXNlcjpwYXNz
1.6.2. POST addDocument
Fügt der Sitzung ein PDF-Dokument zur Siegelung hinzu. Rufen Sie dies einmal pro Dokument auf. Pro Sitzung können maximal 100 Dokumente hinzugefügt werden.
POST <base-url>/{sessionId}/addDocument
Pfad-Parameter
|
Parameter |
Typ |
Beschreibung |
|
sessionId |
String |
Von startSession zurückgegebene Sitzungs-ID |
Request Body
|
Inhalt |
Typ |
Beschreibung |
|
PDF-Datei |
application/pdf-Blob |
Das zu siegelnde Dokument |
Response
|
Feld |
Typ |
Beschreibung |
|
— |
Int |
Dokument-ID (documentId) — verwenden Sie diese beim Abruf des gesiegelten Dokuments |
Beispiel
POST https://moxis.yourcompany.com/webservices/rest/swisscom-seal-api/a1b2c3d4/addDocument
Authorization: Basic dXNlcjpwYXNz
Content-Type: application/pdf
<PDF binary data>
1.6.3. PUT seal
Siegelt alle Dokumente, die der Sitzung hinzugefügt wurden. Dies löst den qualifizierten Siegelungsvorgang für alle Dokumente gleichzeitig aus. Rufen Sie dies genau einmal auf, nachdem alle Dokumente hinzugefügt wurden.
PUT <base-url>/{sessionId}/seal
Pfad-Parameter
|
Parameter |
Typ |
Beschreibung |
|
sessionId |
String |
Von startSession zurückgegebene Sitzungs-ID |
Request Body: keiner
Response
|
Feld |
Typ |
Beschreibung |
|
— |
Int |
1 bei Erfolg |
Beispiel
PUT https://moxis.yourcompany.com/webservices/rest/swisscom-seal-api/a1b2c3d4/seal
Authorization: Basic dXNlcjpwYXNz
1.6.4. GET getDocument
Ruft ein einzelnes gesiegeltes Dokument ab. Rufen Sie dies einmal pro Dokument auf, nachdem die Siegelung abgeschlossen ist.
GET <base-url>/{sessionId}/getDocument/{documentId}
Pfad-Parameter
|
Parameter |
Typ |
Beschreibung |
|
sessionId |
String |
Von startSession zurückgegebene Sitzungs-ID |
|
documentId |
Int |
Von addDocument zurückgegebene Dokument-ID |
Request Body: keiner
Response
|
Feld |
Typ |
Beschreibung |
|
— |
Blob |
Das gesiegelte PDF-Dokument |
Beispiel
GET https://moxis.yourcompany.com/webservices/rest/swisscom-seal-api/a1b2c3d4/getDocument/1
Authorization: Basic dXNlcjpwYXNz
1.6.5. DELETE endSession
Schließt die Sitzung und bereinigt sie. Rufen Sie dies einmal auf, nachdem alle gesiegelten Dokumente abgerufen wurden.
DELETE <base-url>/{sessionId}/endSession
Pfad-Parameter
|
Parameter |
Typ |
Beschreibung |
|
sessionId |
String |
Von startSession zurückgegebene Sitzungs-ID |
Request Body: keiner
Response
|
Feld |
Typ |
Beschreibung |
|
— |
Int |
1 bei Erfolg |
Beispiel
DELETE https://moxis.yourcompany.com/webservices/rest/swisscom-seal-api/a1b2c3d4/endSession
Authorization: Basic dXNlcjpwYXNz
1.7. Reihenfolge der API-Aufrufe
Befolgen Sie für jeden Siegelungsvorgang diese Reihenfolge:
-
POST startSession: Sitzung erstellen (einmalig)
-
POST addDocument: Jedes PDF der Sitzung hinzufügen (ein- bis hundertmal)
-
PUT seal: Alle Dokumente der Sitzung siegeln (einmalig)
-
GET getDocument: Jedes gesiegelte PDF abrufen (einmal pro Dokument)
-
DELETE endSession: Sitzung schließen (einmalig)
Rufen Sie seal nicht auf, bevor alle gewünschten Dokumente hinzugefügt wurden. Rufen Sie getDocument nicht auf, bevor seal erfolgreich abgeschlossen wurde.
1.8. Erste Schritte
Um die Swisscom Seal API auf Ihrer Instanz zu aktivieren, wenden Sie sich an servicedesk@xitrust.com. Die Einrichtung umfasst:
-
Sicherstellung, dass Sie über MOXIS Enterprise verfügen
-
Erstellen und Konfigurieren eines Siegel-Benutzers in MOXIS
-
Generieren des API-Tokens in der MOXIS-Siegelkonfigurations-UI
-
Bestätigung, dass Ihre Swisscom-Siegel-Zugangsdaten aktiv sind