eStamp: Workflow-Anleitungen für das Signieren und Validieren von PDF-Dokumenten

Inhalt

Dieses Dokument beschreibt die verfügbaren Workflow-Typen der eStamp REST-API v2 und erklärt Schritt für Schritt, wie PDF-Dokumente signiert, versiegelt und validiert werden. Voraussetzung für alle Workflows: eine gültige eStamp Base URL und ein gültiger Bearer Token (siehe „eStamp: Aufbau, Nutzung und Authentifizierung").

Übersicht: Welche Workflow-Typen gibt es?

Die eStamp REST-API bietet zwei Haupt-Workflow-Typen für das Signieren von Dokumenten sowie einen separaten Workflow für die Validierung:

Synchroner Workflow (Single Request): Ein einzelner API-Aufruf liefert sofort das signierte Dokument zurück. Geeignet für einzelne Dokumente ohne Zwischenspeicherung. Drei Varianten verfügbar: sealSingle, sealSingleWithAppearance, sealSingleWithAppearanceParam.

Session-basierter Workflow (Batch): Mehrere Dokumente werden innerhalb einer Session verarbeitet. Läuft in mehreren Schritten ab: startSession → addDocument → seal → getDocument → closeSession. Geeignet für Batch-Verarbeitung von bis zu 100 Dokumenten pro Session.

Validierungs-Workflow: Prüft die Signatur eines bestehenden PDF- oder XML-Dokuments und liefert einen Validierungsreport zurück.

[!NOTE] eStamp ist kein asynchrones System. Es gibt keine Hintergrundjobs, keine Status-Endpoints, kein Polling und keine Webhooks. Jeder API-Aufruf blockiert, bis er abgeschlossen ist, und liefert das Ergebnis direkt zurück.

Workflow 1: Synchrones Signieren (Single Request)

Der synchrone Signier-Workflow der eStamp REST-API verarbeitet ein einzelnes Dokument pro API-Aufruf und gibt das signierte Dokument sofort als Binary zurück. Es gibt keine Sessions, kein Zwischenspeichern und keinen Status zu prüfen.

Variante 1a: Signieren ohne Visualisierung (sealSingle)

Versiegelt ein PDF-Dokument ohne visuelle Signaturdarstellung im Dokument.

# eStamp: PDF versiegeln ohne Signaturvisualisierung
# Endpoint: POST /signApi/sealSingle
# Authentifizierung: Bearer Token erforderlich
# Rückgabe: signiertes PDF als Binary

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

Parameter:

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

Variante 1b: Signieren mit Signaturvisualisierung als Datei (sealSingleWithAppearance)

Versiegelt ein PDF-Dokument und fügt eine visuelle Signaturdarstellung an der konfigurierten Position ein. Die Visualisierungskonfiguration wird als JSON-Datei übergeben.

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

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

Beispiel appearance.json (Pflicht- und optionale Felder):

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

Variante 1c: Signieren mit Signaturvisualisierung als ID (sealSingleWithAppearanceParam)

Versiegelt ein PDF-Dokument mit einer serverseitig hinterlegten Visualisierungskonfiguration. Statt einer JSON-Datei wird nur die appearanceId als Query-Parameter übergeben. Die Konfiguration liegt serverseitig und muss nicht bei jedem Aufruf mitgesendet werden.

# eStamp: PDF versiegeln mit Signaturvisualisierung (Appearance als serverseitige ID)
# Endpoint: POST /signApi/sealSingleWithAppearanceParam
# Authentifizierung: Bearer Token erforderlich
# Rückgabe: signiertes PDF mit Visualisierung als Binary

curl -X POST "https://<base-url>/signApi/sealSingleWithAppearanceParam?appearanceId=<appearanceId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -F "parameterId=<parameterId>" \
  -F "file=@./eingabe.pdf;type=application/pdf" \
  --output ./signiert.pdf

Signaturvisualisierung (signatureAppearance): Konfigurationsreferenz

Die signatureAppearance-Konfiguration steuert, wie die Signatur optisch im PDF dargestellt wird – Position, Größe, verwendetes Signaturbild und Seitenbereich. Die Konfiguration wird immer im JSON-Format übergeben.

[!NOTE] Die signatureAppearance-Konfiguration ist nur relevant, wenn die Endpoints sealSingleWithAppearance oder addDocumentWithAppearance verwendet werden. Für sealSingle ohne Visualisierung wird keine signatureAppearance benötigt.

Pflichtfelder der signatureAppearance

Optionale Felder der signatureAppearance

[!WARNING] signaturePageId und onEveryPage: true dürfen nicht gleichzeitig gesetzt werden. Diese Kombination führt zu einem 400 Bad Request-Fehler.

Sonderfall: Automatische Positionierung (visualizationAutomation)

visualizationAutomation positioniert die Signaturvisualisierung automatisch am Ende des letzten Textzeichens der letzten Seite. Eine manuelle Koordinatenangabe entfällt.

{
  "signatureImageId": "amtsSignatur",
  "signaturePageId": "default",
  "x": 100,
  "width": 400,
  "height": 250,
  "visualizationAutomation": {
    "footerHeight": 6,
    "margin": 10,
    "signaturePageMargin": 60
  }
}

Pflichtfelder innerhalb von visualizationAutomation:

[!WARNING] Bei Verwendung von visualizationAutomation gelten zwei Pflichtbedingungen: signaturePageId muss auf einen gültigen Wert gesetzt sein, und signatureAttributes darf nicht gesetzt sein. Die Kombination beider Sonderfälle (visualizationAutomation und signatureAttributes) ist nicht unterstützt.

Sonderfall: Signatur in vorhandenes PDF-Signaturfeld platzieren

Wenn ein PDF bereits Signaturfelder enthält, kann die Visualisierung direkt in ein vorhandenes Feld platziert werden. Koordinaten, Seitenangaben und Größe werden dann nicht benötigt.

{
  "signatureImageId": "imageOnly",
  "signatureFieldId": "Signatur2"
}

Die folgenden Felder der signatureAppearance werden bei Verwendung von signatureFieldId nicht benötigt: firstPage, lastPage, onEveryPage, x, y, width, height.

Um die vorhandenen Signaturfeld-IDs eines PDF-Dokuments abzufragen, verwenden Sie folgenden Endpoint:

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

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

Workflow 2: Session-basiertes Signieren (Batch)

Der session-basierte Signier-Workflow der eStamp REST-API verarbeitet mehrere Dokumente innerhalb einer Session. Der Ablauf ist mehrstufig und muss in der angegebenen Reihenfolge ausgeführt werden.

Vollständiger Ablauf:

POST /startSession
  → POST /{sessionId}/addDocument  (1–100 Mal)
  → POST /{sessionId}/seal
  → GET  /{sessionId}/getDocument/{documentId}  (für jedes Dokument)
  → POST /{sessionId}/closeSession

[!WARNING] Die Reihenfolge der Session-Schritte ist zwingend einzuhalten. Ein getDocument-Aufruf vor seal gibt einen 404 Not Found-Fehler zurück. Ein addDocument-Aufruf nach seal gibt einen 400 Bad Request-Fehler zurück.

Schritt 1: Session starten (startSession)

# 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>" \
  -H "Content-Type: multipart/form-data" \
  -F "parameterId=<parameterId>"

Erfolgreiche Antwort (200 OK):

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Die zurückgegebene sessionId ist bei allen Folgeaufrufen als Pfadparameter erforderlich.

Schritt 2: Dokumente hinzufügen (addDocument)

# eStamp: Dokument zur Session hinzufügen
# Endpoint: POST /signApi/{sessionId}/addDocument
# Rückgabe: documentId als Integer (JSON)
# Dieser Schritt wird für jedes Dokument einzeln wiederholt (max. 100 pro Session)

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

Erfolgreiche Antwort (200 OK):

1

Die zurückgegebene documentId wird in Schritt 4 (getDocument) benötigt. Für jedes hinzugefügte Dokument wird eine eigene documentId vergeben.

[!NOTE] Einmal hinzugefügte Dokumente können innerhalb einer Session nicht ersetzt oder entfernt werden. Wenn ein falsches Dokument hinzugefügt wurde, muss eine neue Session gestartet werden.

Alternativ stehen folgende addDocument-Varianten zur Verfügung:

Schritt 3: Alle Dokumente versiegeln (seal)

# eStamp: Alle Dokumente der Session versiegeln
# Endpoint: POST /signApi/{sessionId}/seal
# Rückgabe: kein Body (leere 200-Antwort)
# Timeout: 60–120 Sekunden für den gesamten Seal-Vorgang

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

Der seal-Aufruf blockiert, bis alle Dokumente der Session signiert sind, und gibt keine Inhaltsdaten zurück. Die signierten Dokumente werden anschließend über getDocument abgerufen.

Schritt 4: Signierte Dokumente abrufen (getDocument)

# eStamp: Signiertes Dokument aus Session abrufen
# Endpoint: GET /signApi/{sessionId}/getDocument/{documentId}
# Rückgabe: signiertes PDF als Binary
# Dieser Schritt wird für jede documentId einzeln ausgeführt

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

Schritt 5: Session schließen (closeSession)

# 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. Eine Session, die 40 Minuten überschreitet, gibt bei Folgeaufrufen den Fehler 412 Precondition Failed (Illegal session id) zurück.

Workflow 3: Signaturvalidierung

Der Validierungs-Workflow der eStamp REST-API prüft die Signatur eines bestehenden PDF- oder XML-Dokuments und gibt einen Validierungsreport zurück.

PDF-Signatur validieren

# eStamp: PDF-Signatur validieren
# Endpoint: POST /signApi/validatePdf
# Parameter 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

XML-Signatur validieren

# eStamp: XML-Signatur validieren
# Endpoint: POST /xmlSignApi/validateXml
# Parameter 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

Verfügbare reportType-Werte:

FAQ: Workflows und häufige Fragen

Was ist der Unterschied zwischen synchronem und session-basiertem Workflow?

Der synchrone Workflow der eStamp REST-API verarbeitet ein einzelnes Dokument pro API-Aufruf und gibt das Ergebnis sofort zurück — keine Sessions, kein Zwischenspeichern. Der session-basierte Workflow ermöglicht die Batch-Verarbeitung von bis zu 100 Dokumenten pro Session in einem mehrstufigen Ablauf. Für einzelne Dokumente ist der synchrone Workflow einfacher; für Stapelverarbeitung ist der session-basierte Workflow notwendig.

Wie viele Dokumente können pro Session verarbeitet werden?

Pro eStamp-Batch-Session können maximal 100 Dokumente verarbeitet werden. Wenn mehr als 100 Dokumente signiert werden müssen, sind mehrere Sessions zu starten. Die Anzahl der parallel laufenden Sessions ist nicht limitiert.

Wie lange ist eine eStamp-Session gültig?

Eine eStamp-Batch-Session ist 40 Minuten ab dem startSession-Aufruf gültig. Nicht abgeschlossene Sessions werden nach 40 Minuten automatisch bereinigt. Ein einzelner API-Aufruf innerhalb einer Session darf maximal 30 Sekunden dauern; bei Überschreitung wird der Call abgebrochen.

Kann ich den Fortschritt eines laufenden seal-Aufrufs abfragen?

Nein. eStamp bietet keine Status-Endpoints, kein Polling und keine Webhooks. Der seal-Aufruf blockiert, bis alle Dokumente der Session signiert sind (maximal 60–120 Sekunden), und gibt danach eine leere 200-Antwort zurück.

Kann ich Dokumente nach dem Hinzufügen aus einer Session entfernen?

Nein. Einmal zur Session hinzugefügte Dokumente können weder entfernt noch ersetzt werden. Wenn ein falsches Dokument hinzugefügt wurde, muss eine neue eStamp-Session über startSession gestartet werden.

Gibt es Partial Failure bei der Session-Verarbeitung?

Nein. eStamp unterstützt kein Partial Failure. Ein Batch-Vorgang ist entweder vollständig erfolgreich oder schlägt vollständig fehl. Es gibt keine teilweise Verarbeitung einzelner Dokumente innerhalb einer Session.

Was passiert, wenn eine Session abläuft oder ein Timeout auftritt?

Bei Ablauf der 40-Minuten-Session-Gültigkeit gibt eStamp bei Folgeaufrufen 412 Precondition Failed zurück. Bei Timeout eines einzelnen API-Aufrufs (30 Sekunden) wird der Call abgebrochen und eine Fehlermeldung zurückgegeben. In beiden Fällen erfolgt keine teilweise Verarbeitung. Abgelaufene Sessions werden automatisch bereinigt.