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".

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

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

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>"

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

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.

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.

Erfolgreiche Antwort (200 OK):

json

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

GET /signApi/paraphenInfos

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.

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

{
  "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

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

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: Signiertes PDF als Binary (application/pdf); Dateiname im Response-Header

# 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:

[!NOTE] documentToSign und file sind synonyme Feldbezeichnungen mit identischer Bedeutung. Beide Varianten werden von der eStamp REST-API akzeptiert.

Erfolgreiche Antwort (200 OK):

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

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

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: Signiertes PDF mit Visualisierung als Binary (application/pdf)

# 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:

Erfolgreiche Antwort (200 OK):

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

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

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: Signiertes PDF mit Visualisierung als Binary (application/pdf)

# 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 "file=@./eingabe.pdf;type=application/pdf" \
  --output ./signiert.pdf

Request-Parameter:

Erfolgreiche Antwort (200 OK):

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.

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: sessionId als JSON-String

# 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"

Erfolgreiche Antwort (200 OK):

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Request-Parameter:

Fehlercodes:

POST /signApi/{sessionId}/addDocument

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.

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: documentId als Integer (JSON)

# 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"

Erfolgreiche Antwort (200 OK):

1

Request-Parameter:

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.

POST /signApi/{sessionId}/addDocumentWithAppearance

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

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: documentId als Integer (JSON)

# 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:

Erfolgreiche Antwort (200 OK):

json

2

POST /signApi/{sessionId}/addDocumentWithAppearanceParam

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

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: documentId als Integer (JSON)

# 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 "file=@./dokument.pdf;type=application/pdf"

Request-Parameter:

Fehlercodes:

POST /signApi/{sessionId}/seal

Löst die Signierung aller zur eStamp-Session hinzugefügten Dokumente aus. Der Aufruf blockiert, bis alle Dokumente signiert sind (maximal 60–120 Sekunden). Gibt keinen Body zurück.

Authentifizierung: Bearer Token erforderlich
Rückgabe: Kein Body (leere 200-Antwort)

# 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>"

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}

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
Rückgabe: Signiertes PDF als Binary (application/pdf); Dateiname im Response-Header

# 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

Fehlercodes:

Erfolgreiche Antwort (200 OK):

json

$body

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)

POST /signApi/{sessionId}/closeSession

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

Authentifizierung: Bearer Token erforderlich
Rückgabe: Kein Body

# 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>"

[!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.

Erfolgreiche Antwort (200 OK)

Signaturfeld-Endpoints

POST /signApi/signatureFieldNames

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

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: JSON-Array der Signaturfeld-IDs

# 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"

Beispiel-Antwort (200 OK):

["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

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

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: Validierungsreport als XML oder PDF Binary; Dateiname im Response-Header

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

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

Request-Parameter:

Erfolgreiche Antwort:
Wenn der reportType ein pdf ist, dann sieht die Rückgabe so aus: xmlReport.pdf

POST /xmlSignApi/validateXml

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

Authentifizierung: Bearer Token erforderlich
Content-Type: multipart/form-data
Rückgabe: Validierungsreport als XML oder PDF Binary

# 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 "file=@./signiert.xml" \
  --output ./validierungsreport.pdf

Request-Parameter:

Erfolgreiche Antwort:

Wenn der reportType ein xml ist, dann sieht die Rückgabe so aus: 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: