eStamp: API-Referenz und Endpunkt-Katalog

Inhalt

Dieses Dokument ist die vollständige technische Referenz aller eStamp REST-API-Endpoints. Es beschreibt Parameter, Rückgabewerte und Besonderheiten jedes Endpoints. Voraussetzung für alle Aufrufe: eine gültige, kundenspezifische eStamp Base URL und ein gültiger Bearer Token. Alle Endpoints verwenden den Basispfad /signApi/... bzw. /xmlSignApi/....

Für eine Einführung in Workflows und Ablauflogik siehe „eStamp: Workflow-Anleitungen für das Signieren und Validieren von PDF-Dokumenten".

Ergänzend steht eine maschinenlesbare OpenAPI 3.1 Spezfikation zur Verfügung. Sie kann für automatische Client-Gnerierung, Validierung oder den Import in Tools wie Swagger UI/Postman verwendet werden.

Konfiguration und Discovery

Diese eStamp-Endpoints liefern Informationen über die Konfiguration der aktuellen eStamp-Instanz. Sie sind der empfohlene Startpunkt für jede neue Integration.

GET /signApi/parameterInfos

Beschreibung

Gibt die Liste aller konfigurierten Signaturhandler der eStamp-Instanz zurück. Die parameterId-Werte aus dieser Antwort sind Pflichtparameter bei allen Seal-Endpoints.

Request

Authentifizierung

Bearer Token erforderlich

# eStamp: Verfügbare Signaturhandler abfragen
# Endpoint: GET /signApi/parameterInfos
# Rückgabe: JSON-Array aller konfigurierten Signaturhandler

curl -X GET "https://<base-url>/signApi/parameterInfos" \
  -H "Authorization: Bearer <token>"

Request-Parameter: keine

bash

curl -X GET "https://<base-url>/signApi/parameterInfos" \
  -H "Authorization: Bearer <token>"

Response

Erfolgreiche Antwort (200 OK):

[
  {
    "parameterId": "amtssignatur",
    "displayName": "Amtssignatur",
    "maxNumberOfDocuments": 100,
    "signatureHandlerType": "SOFTWARE_KEY"
  }
]

Antwortfelder:

[!NOTE] Die aufgelisteten parameterId-Werte sind instanzspezifisch. Es werden ausschließlich jene Parameter aufgelistet, die in der Konfiguration der eStamp-Instanz hinterlegt sind. Deprecated Parameter werden nicht gesondert markiert.

GET /signApi/signatureAppearanceInfos

Beschreibung

Gibt das Mapping aller serverseitig hinterlegten Appearance-IDs auf ihre signatureAppearance-Konfiguration zurück. Dieser Endpoint wird verwendet, um verfügbare appearanceId-Werte für die Endpoints sealSingleWithAppearanceParam und addDocumentWithAppearanceParam abzufragen.

Request

Authentifizierung: Bearer Token erforderlich

# eStamp: Verfügbare Appearance-Konfigurationen abfragen
# Endpoint: GET /signApi/signatureAppearanceInfos
# Rückgabe: JSON-Mapping von Appearance-IDs auf signatureAppearance-Konfigurationen

curl -X GET "https://<base-url>/signApi/signatureAppearanceInfos" \
  -H "Authorization: Bearer <token>"

[!NOTE] Serverseitige Appearance-Konfigurationen werden in der eStamp-Instanz als YAML hinterlegt und referenzieren JSON-Konfigurationsdateien. Die Verwaltung erfolgt durch das XiTrust Support Team beim Deployment.

Response

Erfolgreiche Antwort (200 OK):

JSON-Mapping von Appearance IDs auf signatureAppearance Konfigurationen.

{
  "appearance1": {
    "signatureImageId": "amtsSignatur",
    "signaturePageId": "default",
    "lastPage": -1,
    "onEveryPage": false,
    "x": 100,
    "y": 100,
    "width": 400,
    "height": 270
  },
  "appearance2": {
    "signatureImageId": "imageOnly",
    "signatureFieldId": "Signatur2"
  }
}

[!NOTE] Serverseitige Appearance-Konfigurationen werden in der eStamp-Instanz als YAML hinterlegt und referenzieren JSON-Konfigurationsdateien. Die Verwaltung erfolgt durch das XiTrust Support Team beim Deployment.

GET /signApi/paraphenInfos

Beschreibung

Gibt das Mapping aller serverseitig hinterlegten Paraphen-IDs auf ihre ParaphenAppearance-Konfiguration zurück. Dieser Endpoint wird verwendet, um verfügbare paraphImageId- und paraphenAppearanceId-Werte abzufragen.

Request

Authentifizierung: Bearer Token erforderlich

# eStamp: Verfügbare Paraphen-Konfigurationen abfragen
# Endpoint: GET /signApi/paraphenInfos
# Rückgabe: JSON-Mapping von Paraphen-IDs auf ParaphenAppearance-Konfigurationen

curl -X GET "https://<base-url>/signApi/paraphenInfos" \
  -H "Authorization: Bearer <token>"

Erfolgreiche Antwort (200 OK):

JSON-Mapping von Paraphen IDs auf ParaphenAppearance-Konfigurationen

{
  "paraphen1": {
    "paraphImageId": "picture1",
    "x": 10,
    "y": 800,
    "width": 50,
    "height": 22
  },
  "paraphen2": {
    "paraphImageId": "picture2",
    "x": 20,
    "y": 750,
    "width": 50,
    "height": 22
  }
}

Synchrone Seal-Endpoints (Single Document)

Die synchronen eStamp-Seal-Endpoints versiegeln ein einzelnes PDF-Dokument pro Aufruf und geben das signierte Dokument direkt als Binary zurück. Es sind keine Sessions erforderlich.

POST /signApi/sealSingle

Beschreibung

Versiegelt ein einzelnes PDF-Dokument ohne Signaturvisualisierung (siehe Abbildung 1). Der einfachste eStamp-Seal-Endpoint.

Request
Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: PDF versiegeln ohne Visualisierung
# Endpoint: POST /signApi/sealSingle
# Rückgabe: signiertes PDF als Binary

curl -X POST "https://<base-url>/signApi/sealSingle" \
  -H "Authorization: Bearer <token>" \
  -H "accept: application/pdf" \
  -F "parameterId=amtssignatur" \
  -F "documentToSign=@./eingabe.pdf;type=application/pdf" \
  --output ./signiert.pdf

Request-Parameter:

Response

Erfolgreiche Antwort (200 OK): Signiertes PDF als Binary (application/pdf); Dateiname im Response-Header (Content-Disposition).

Sig_OhneVisualisierung.pdf

Abbildung 1: Ergebnis ist ein PDF-Dokument ohne visuelle Signaturdarstellung
(mit einem Klick auf die Datei können Sie sich das Ergebnis anzeigen lassen)

POST /signApi/sealSingleWithAppearance

Beschreibung

Versiegelt ein einzelnes PDF-Dokument und fügt eine visuelle Signaturdarstellung ein. Die signatureAppearance-Konfiguration wird als JSON-Datei im Request mitgesendet.

Request
Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: PDF versiegeln mit Signaturvisualisierung (Appearance als JSON-Datei)
# Endpoint: POST /signApi/sealSingleWithAppearance
# Rückgabe: signiertes PDF mit Visualisierung als Binary

curl -X POST "https://<base-url>/signApi/sealSingleWithAppearance" \
  -H "Authorization: Bearer <token>" \
  -H "accept: application/pdf" \
  -F "parameterId=amtssignatur" \
  -F "documentToSign=@./eingabe.pdf;type=application/pdf" \
  -F "signatureAppearance=@./appearance.json;type=application/json" \
  --output ./signiert.pdf

Request-Parameter:

Response
Erfolgreiche Antwort (200 OK): Signiertes PDF mit Visualisierung als Binary (application/pdf); Dateiname im Response-Header.

Sig_MitVisualisierung.pdf

Abbildung 2: Ergebnis ist ein PDF-Dokument mit einer visuellen Signaturdarstellung
(mit einem Klick auf die Datei können Sie sich das Ergebnis anzeigen lassen)

POST /signApi/sealSingleWithAppearanceParam

Beschreibung

Versiegelt ein einzelnes PDF-Dokument mit einer serverseitig hinterlegten Visualisierungskonfiguration (siehe Abbildung 3). Statt einer JSON-Datei wird die appearanceId als Query-Parameter übergeben.

Request

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: PDF versiegeln mit serverseitiger Appearance-ID
# Endpoint: POST /signApi/sealSingleWithAppearanceParam
# appearanceId: Query-Parameter (serverseitig konfiguriert)
# Rückgabe: signiertes PDF als Binary

curl -X POST "https://<base-url>/signApi/sealSingleWithAppearanceParam?appearanceId=<appearanceId>" \
  -H "Authorization: Bearer <token>" \
  -H "accept: application/pdf" \
  -F "parameterId=amtssignatur" \
  -F "documentToSign=@./eingabe.pdf;type=application/pdf" \
  --output ./signiert.pdf

Request-Parameter:

Response

Erfolgreiche Antwort (200 OK): Signiertes PDF mit Visualisierung als Binary (application/pdf)

Sig_MitVisualisierung.pdf

Sig_MitVisualisierung.pdf

Abbildung 3: Ergebnis ist ein PDF-Dokument mit einer visuellen Signaturdarstellung
(mit einem Klick auf die Datei können Sie sich das Ergebnis anzeigen lassen)

Session-basierte Seal-Endpoints (Batch)

Die session-basierten eStamp-Endpoints verarbeiten mehrere Dokumente in einer mehrstufigen Session. Die Reihenfolge der Aufrufe ist zwingend einzuhalten: startSession → addDocument → seal → getDocument → closeSession.

POST /signApi/startSession

Startet eine neue eStamp-Batch-Signing-Session und gibt die sessionId zurück, die bei allen Folgeaufrufen als Pfadparameter verwendet wird.

Request
Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: Batch-Signing-Session starten
# Endpoint: POST /signApi/startSession
# Rückgabe: sessionId als JSON-String

curl -X POST "https://<base-url>/signApi/startSession" \
  -H "Authorization: Bearer <token>" \
  -F "parameterId=amtssignatur"

Response
Erfolgreiche Antwort (200 OK): JSON-String mit der sessionId

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Request-Parameter:

Fehlercodes:

[!NOTE] Fehlerantworten werden derzeit als reiner Text im Response-Body zurückgegeben, nicht als strukturiertes JSON.

POST /signApi/{sessionId}/addDocument

Beschreibung
Fügt ein Dokument zur bestehenden eStamp-Session hinzu. Gibt eine documentId zurück, die für getDocument benötigt wird. Kann bis zu 100 Mal pro Session aufgerufen werden.

Request
Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: Dokument zur Session hinzufügen
# Endpoint: POST /signApi/{sessionId}/addDocument
# Rückgabe: documentId als Integer

curl -X POST "https://<base-url>/signApi/<sessionId>/addDocument" \
  -H "Authorization: Bearer <token>" \
  -F "documentToSign=@./dokument.pdf;type=application/pdf"

Pfadparameter:

Request-Parameter:

Response

Erfolgreiche Antwort (200 OK): documentId als Integer (JSON)

1

Antwortfelder:

Fehlercodes:

[!NOTE] Einmal zur Session hinzugefügte Dokumente können nicht entfernt oder ersetzt werden. Bei einem fehlerhaft hinzugefügten Dokument muss eine neue Session über POST /signApi/startSession gestartet werden.

Verhalten bei fehlgeschlagenem addDocument (HTTP ist nicht 200):
Bei einem Fehlerfall bleibt die Session grundsätzlich offen und weiterhin verwendbar. Das fehlgeschlagene Dokument wird nicht zur Session hinzugefügt. Der Client kann entweder:

• die Session mit anderen Dokumenten fortsetzen oder

• die Session explizit über POST/signApi/{sessionId}/closeSession schließen, um Ressourcen sofort freizugeben.

Eine Ausnahme bildet HTTP 412 (Illegal session id): In diesem Fall existiert die Session serverseitig bereits nicht mehr (z. B. wegen Ablauf nach 40 Minuten). Ein closeSession-Aufruf ist dann nicht mehr nötig; der Client muss eine neue Session über startSession starten.

POST /signApi/{sessionId}/addDocumentWithAppearance

Beschreibung

Fügt ein Dokument mit einer signatureAppearance-Konfiguration zur eStamp-Session hinzu. Die Visualisierungskonfiguration wird als JSON-Datei übergeben.

Request

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: Dokument mit Appearance-Konfiguration zur Session hinzufügen
# Endpoint: POST /signApi/{sessionId}/addDocumentWithAppearance

curl -X POST "https://<base-url>/signApi/<sessionId>/addDocumentWithAppearance" \
  -H "Authorization: Bearer <token>" \
  -F "documentToSign=@./dokument.pdf;type=application/pdf" \
  -F "signatureAppearance=@./appearance.json;type=application/json"

Request-Parameter:

Response
Erfolgreiche Antwort (200 OK): JSON-Antwort mit einem Integer-Wert (documentId)

2

POST /signApi/{sessionId}/addDocumentWithAppearanceParam

Beschreibung
Fügt ein Dokument mit einer serverseitig hinterlegten Appearance-ID zur eStamp-Session hinzu.

Request
Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: Dokument mit serverseitiger Appearance-ID zur Session hinzufügen
# Endpoint: POST /signApi/{sessionId}/addDocumentWithAppearanceParam

curl -X POST "https://<base-url>/signApi/<sessionId>/addDocumentWithAppearanceParam?appearanceId=<appearanceId>" \
  -H "Authorization: Bearer <token>" \
  -F "documentToSign=@./dokument.pdf;type=application/pdf"

Request-Parameter:

Response

Erfolgreiche Antwort (200 OK): JSON-Antwort mit einem Integer-Wert (documentId)

Fehlercodes:

POST /signApi/{sessionId}/seal

Beschreibung
Löst die Signierung aller zur eStamp-Session hinzugefügten Dokumente aus. Der Aufruf blockiert, bis alle Dokumente signiert sind (maximal 60–120 Sekunden bei größeren Batches). Eine asynchrone Variante existiert nicht; die eStamp-Architektur ist bereits synchron ausgelegt. Für Integrationen, deren Infrastruktur (Proxy, API-Gateway, Firewall) Timeouts unter 60 Sekunden erzwingt, empfiehlt sich die Aufteilung in kleinere Batches (z. B. mehrere parallele Sessions mit wenigen Dokumenten pro Session) statt einer einzigen großen Session. Die Batch-Größe pro Session kann bis auf ein Dokument reduziert werden; in diesem Fall verhält sich die Session-Variante vergleichbar zu sealSingle und bleibt innerhalb üblicher Proxy-Timeouts. Gibt keinen Body zurück.

Request
Authentifizierung: Bearer Token erforderlich

# eStamp: Alle Dokumente der Session versiegeln
# Endpoint: POST /signApi/{sessionId}/seal
# Rückgabe: kein Body (leere 200-Antwort bei Erfolg)

curl -X POST "https://<base-url>/signApi/<sessionId>/seal" \
  -H "Authorization: Bearer <token>"

Response
Erfolgreiche Antwort (200 OK): Kein Body (leere 200-Antwort)

[!NOTE] Aus der Sicht der HTTP-Semantik wäre ein 204 No Contentbei leerem Body üblich. Aktuell gibt eStamp 200 OK mit leerem Body zurück. Der STatuscode ist zur Zeit geplant als 200 dokumentiert.

Fehlercodes:

[!WARNING] getDocument darf erst nach erfolgreichem seal-Aufruf aufgerufen werden. Ein getDocument-Aufruf vor seal gibt 404 Not Found zurück.

GET /signApi/{sessionId}/getDocument/{documentId}

Beschreibung
Ruft ein einzelnes signiertes Dokument aus der eStamp-Session ab. Muss für jede documentId separat aufgerufen werden (siehe Abbildung 4).

Authentifizierung: Bearer Token erforderlich

# eStamp: Signiertes Dokument aus Session abrufen
# Endpoint: GET /signApi/{sessionId}/getDocument/{documentId}
# Rückgabe: signiertes PDF als Binary

curl -X GET "https://<base-url>/signApi/<sessionId>/getDocument/<documentId>" \
  -H "Authorization: Bearer <token>" \
  --output ./signiert-dokument.pdf

Pfadparameter:

Response
Erfolgreiche Antwort (200 OK): Signiertes PDF als Binary (application/pdf); Dateiname im Response-Header (Content-Disposition).

Der Response-Body enthält ausschließlich die PDF-Binärdaten. Es wird kein JSON und kein Multipart-Reponse zurückgegeben.

json

Sig_OhneVisualisierung.pdf

Sig_MitVisualisierung.pdf
Abbildung 4: Ergebnis ist je nachdem, was abgerufen wird, entweder ein PDF-Dokument mit einer visuellen Signaturdarstellung oder ohne. (mit einem Klick auf die Dateien können Sie sich das Ergebnis anzeigen lassen)

Fehlercodes:

POST /signApi/{sessionId}/closeSession

Beschreibung
Beendet eine eStamp-Batch-Signing-Session und gibt alle zugehörigen Ressourcen frei. Gibt keinen Body zurück.

Request
Authentifizierung: Bearer Token erforderlich

# eStamp: Batch-Signing-Session schließen
# Endpoint: POST /signApi/{sessionId}/closeSession
# Rückgabe: kein Body

curl -X POST "https://<base-url>/signApi/<sessionId>/closeSession" \
  -H "Authorization: Bearer <token>"

Der Endpoint erwartet keine Request-Parameter über den Pfadparameter sessionId hinaus.

Response
Erfolgreiche Antwort (200 OK): Kein Body

[!NOTE] Nicht manuell geschlossene eStamp-Sessions werden nach 40 Minuten automatisch bereinigt. Das manuelle Schließen über closeSession ist dennoch empfohlen, um Ressourcen sofort freizugeben

Signaturfeld-Endpoints

POST /signApi/signatureFieldNames

Beschreibung
Gibt die IDs aller vorhandenen Signaturfelder eines PDF-Dokuments zurück. Wird verwendet, um signatureFieldId-Werte für die signatureAppearance-Konfiguration zu ermitteln.

Request
Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: Signaturfeld-IDs eines PDFs abfragen
# Endpoint: POST /signApi/signatureFieldNames
# Rückgabe: JSON-Array der Signaturfeld-IDs im Dokument

curl -X POST "https://<base-url>/signApi/signatureFieldNames" \
  -H "Authorization: Bearer <token>" \
  -F "document=@./eingabe.pdf;type=application/pdf"

Request-Parameter:

Response
Erfolgreiche Antwort (200 OK): JSON-Array der Signaturfeld-IDs im Dokument.

["Signatur1", "Signatur2", "Signatur3"]

Die zurückgegebenen Werte können direkt als signatureFieldId in der signatureAppearance-Konfiguration verwendet werden. Wenn signatureFieldId gesetzt ist, werden x, y, width, height, firstPage, lastPage und onEveryPage nicht benötigt.

Validierungs-Endpoints

POST /signApi/validatePdf

Beschreibung
Validiert die Signatur eines bestehenden PDF-Dokuments und gibt einen Validierungsreport zurück.

Request
Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: PDF-Signatur validieren
# Endpoint: POST /signApi/validatePdf
# Rückgabe: Validierungsreport als XML oder PDF Binary

curl -X POST "https://<base-url>/signApi/validatePdf" \
  -H "Authorization: Bearer <token>" \
  -F "reportType=xml" \
  -F "documentToSign=@./signiert.pdf;type=application/pdf" \
  --output ./validierungsreport.xml

Request-Parameter:

Response
Erfolgreiche Antwort (200 OK): Validierungsreport als XML (application/xml) oder PDF (application/pdf) Binary; Dateiname im Response-Header.
Beispiel bei reportType=pdf: xmlReport.pdf

POST /xmlSignApi/validateXml

Beschreibung
Validiert die Signatur eines bestehenden XML-Dokuments und gibt einen Validierungsreport zurück.

Request
Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data

# eStamp: XML-Signatur validieren
# Endpoint: POST /xmlSignApi/validateXml
# reportType: "xml" (Standard) oder "pdf"
# Rückgabe: Validierungsreport als XML oder PDF Binary

curl -X POST "https://<base-url>/xmlSignApi/validateXml" \
  -H "Authorization: Bearer <token>" \
  -F "reportType=pdf" \
  -F "documentToSign=@./signiert.xml" \
  --output ./validierungsreport.pdf

Request-Parameter:

Response
Erfolgreiche Antwort (200 OK): Validierungsreport als XML oder PDF Binary.

Beispiel bei reportType=xml: xmlReport.xml

signatureAppearance: vollständige Feldreferenz

Die signatureAppearance-Konfiguration steuert die visuelle Darstellung der Signatur im PDF. Sie wird immer im JSON-Format übergeben — entweder als Datei oder als serverseitig hinterlegte Konfiguration (referenziert über appearanceId).

Pflichtfelder

Optionale Felder

Unterstützte signatureAttributes (X.509)

[!NOTE] Der linke Wert (z. B. subjectDn) ist der technisch fixe Schlüssel. Der rechte Wert (z. B. "Subject") ist der frei wählbare Anzeigetext in der Visualisierung.

[!WARNING] Folgende Feldkombinationen in der signatureAppearance sind nicht unterstützt und führen zu Fehlern: signaturePageId zusammen mit onEveryPage: true (400 Bad Request), und visualizationAutomation zusammen mit signatureAttributes (nicht unterstützte Kombination).

visualizationAutomation: Pflichtfelder

Wenn visualizationAutomation gesetzt ist, positioniert eStamp die Signaturvisualisierung automatisch am Ende des letzten Textzeichens der letzten Seite. Folgende drei Felder sind innerhalb des visualizationAutomation-Blocks Pflicht:

[!WARNING] Bei Verwendung von visualizationAutomation muss signaturePageId auf einen gültigen Wert gesetzt sein. signatureAttributes darf nicht gleichzeitig gesetzt werden.

paraphenImage: Feldreferenz

Die Paraphen-Konfiguration steuert die Darstellung eines kleinen Signaturbilds (Paraphe) auf definierten Seiten des Dokuments. Sie wird als optionaler JSON-Parameter bei Seal-Endpoints übergeben.

Pflichtfelder

Beispielkonfiguration:

{
  "paraphImageId": "picture1",
  "width": 50,
  "height": 22,
  "x": 10,
  "y": 800
}

Endpunkt-Übersicht

Alle eStamp REST-API-Endpoints auf einen Blick: