Skip to main content
Skip table of contents

eStamp Glossar: Begriffe und Konzepte der Dokumentensignierung

Inhalt

Dieses Glossar definiert alle Fachbegriffe, die in der eStamp-Dokumentation verwendet werden. Es dient als verbindliche Terminologie-Referenz für alle weiteren eStamp-Dokumente. Begriffe sind thematisch gruppiert und jeweils eigenständig verständlich – jeder Eintrag enthält Produktkontext, Definition und Querverweise.

Zielgruppe: Entwickler:innen und Administrator:innen, die neu mit der eStamp REST-API arbeiten. Supportanfragen bitte an das XiTrust Support Team unter servicedesk@xitrust.com.


A: Architektur & Betrieb

Dieser Abschnitt erklärt die grundlegenden Architektur- und Betriebskonzepte von eStamp.

eStamp (Produkt)

eStamp ist ein XiTrust-Service zum automatischen Signieren und Siegeln von Dokumenten über eine REST-API oder einen Webclient. Dokumente werden als PDF an die eStamp-API gesendet, signiert oder versiegelt und als signiertes PDF zurückgegeben. Typische Einsatzbereiche sind Behörden (Bescheide), Versicherungen (Polizzen) und Unternehmen (automatisierte Dokumentenprozesse).

Synonyme im System: eStamp wird intern auch als „Seal-Service" bezeichnet. In der API ist der Basispfad /signApi/....

→ Siehe: [eStamp Aufbau, Nutzung und Authentifizierung für PDF-Signaturen: Was ist eStamp?]

Base URL (eStamp-Instanz-Adresse)

Die eStamp-Base-URL ist die kundenspezifische Webadresse, über die eine eStamp-Instanz erreichbar ist. Sie wird beim Deployment festgelegt und ist Voraussetzung für jeden API-Aufruf.

Format:

CODE
https://estamp.<kundenname>.xitrust.cloud/estamp

Beispiel:

CODE
https://estamp.acc.xitrust.cloud/estamp

[!WARNING] Die Base URL ist individuell pro Kunde. Ohne korrekte Base URL schlagen alle API-Aufrufe fehl. Wenn der Service nicht erreichbar ist, ist die Base URL der erste Prüfpunkt.

→ Siehe: [eStamp Aufbau, Nutzung udn Authentifizierung für PDF-Signaturen: eStamp Base URL]

eStamp-Instanz

Eine eStamp-Instanz ist eine eigenständige Bereitstellung von eStamp, entweder als Cloud-Variante (durch XiTrust gehostet) oder als On-Premises-Installation (in der Kundeninfrastruktur betrieben). Jede Instanz hat eine eigene Base URL und eine eigene Konfiguration.

Deployment-Varianten:

Variante

Betrieb durch

Server erforderlich

Cloud

XiTrust Support Team

Nein

On-Premises

Kunde selbst

Ja

[!NOTE] Für vollständige technische Trennung zwischen Organisationseinheiten (z.B. Konzernstrukturen) wird eine separate eStamp-Instanz empfohlen. Merksatz: Technische Trennung = eigene Instanz.

Mandantenmodell (eStamp)

eStamp kennt kein Mandantenmodell. Es gibt innerhalb einer eStamp-Instanz keine getrennten Mandanten wie bei anderen Systemen. Unterschiedliche Konfigurationen (z.B. verschiedene Zertifikate, Signaturtypen, Visualisierungen) werden stattdessen über Signaturhandler innerhalb einer Instanz abgebildet.

Signaturhandler (eStamp)

Ein eStamp-Signaturhandler ist eine Softwarekomponente, die den technischen Ablauf eines Signaturvorgangs steuert. Er bestimmt, welches Zertifikat verwendet wird und welches Seal-Verhalten greift. Ein Signaturhandler wird über die parameterId in jedem Seal-Aufruf ausgewählt.

Verfügbare Handler abfragen:

CODE
# eStamp-API: Alle konfigurierten Signaturhandler abrufen
GET /signApi/parameterInfos
Authorization: Bearer <token>

Beispiel-Response:

CODE
[
  {
    "parameterId": "software",
    "displayName": "software",
    "maxNumberOfDocuments": 100,
    "signatureHandlerType": "SOFTWARE_KEY"
  }
]

→ Siehe: [eStamp API Referenz und Endpunkt-Katalog: GET /signApi/parameterInfos]


B: Authentifizierung & Sicherheit

Dieser Abschnitt erklärt alle Authentifizierungskonzepte der eStamp REST-API. Ohne gültige Authentifizierung gibt die eStamp-API HTTP 401 zurück und verweigert alle Signatur- und Seal-Operationen.

Basic Authorization (eStamp)

Basic Authorization ist eine einfache Authentifizierungsmethode für die eStamp-API, bei der klassische Zugangsdaten (Benutzername + Passwort) als Base64-kodierter HTTP-Header übergeben werden.

[!NOTE] Basic Authorization wird für eStamp unterstützt, ist aber weniger empfohlen als OAuth 2.0. Für Produktionsumgebungen sollte OAuth 2.0 mit Client Credentials verwendet werden.

OAuth 2.0 (eStamp-Authentifizierung)

OAuth 2.0 ist die empfohlene Authentifizierungsmethode für die eStamp REST-API. eStamp verwendet ausschließlich den Grant Type Client Credentials – das bedeutet, eine Maschine oder ein System authentifiziert sich, kein menschlicher Benutzer. Es gibt keine Benutzerkonten, Passwörter oder Rollen.

Pflichtfelder für die OAuth-2.0-Konfiguration in eStamp:

Feld

Beschreibung

Festgelegt durch

issuer-uri

Heimatadresse des Authentifizierungsservers (Identity Provider, z.B. Keycloak)

XiTrust

client-id

„Benutzername" der Anwendung beim Auth-Server

Kunde

client-secret

„Passwort" der Anwendung (geheimer Schlüssel)

Kunde

auth-server-url

Konkrete URL für Token-Anfragen

XiTrust

grant_type

Immer client_credentials

XiTrust

Token anfordern (cURL):

CODE
# eStamp OAuth 2.0: Bearer Token anfordern
# Endpoint: POST /token am Auth-Server (auth-server-url)
# Voraussetzung: client-id und client-secret vom Deployment erhalten

curl -X POST "<auth-server-url>/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<client-id>" \
  -d "client_secret=<client-secret>"

# Erfolgreiche Response (200 OK):
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
#   "token_type": "Bearer",
#   "expires_in": 3600
# }
#
# Fehler 401: client-id oder client-secret falsch
# Fehler 404: auth-server-url falsch

→ Details: [eStamp Aufbau, Nutzung und Authentifizierung für PDF-Signaturen: OAuth 2.0]

Bearer Token (eStamp-Zugriffstoken)

Der eStamp-Bearer-Token ist ein OAuth-2.0-Zugriffstoken, das bei jedem eStamp-API-Aufruf im Authorization-Header mitgesendet werden muss. Es ist der einzige Authorization Header, der von der eStamp-API benötigt wird.

Verwendung:

CODE
Authorization: Bearer <token>

Gültigkeitsdauer: Im expires_in-Feld der Token-Response angegeben (typisch: 3600 Sekunden = 1 Stunde). Nach Ablauf gibt die eStamp-API HTTP 401 zurück.

[!WARNING] Sicherheitsregel: Den eStamp-Bearer-Token wie ein Passwort behandeln. Niemals im Quellcode speichern oder in Klartext ablegen. Empfohlene Speicherorte: Keycloak, HashiCorp Vault oder ein vergleichbarer Secret Store.

Best Practices:

  • Token nur für autorisierte Systeme zugänglich machen

  • Ablaufzeit (expires_in) überwachen und Token proaktiv erneuern

  • Bei HTTP 401: Zuerst Token-Gültigkeit prüfen, dann OAuth-Konfiguration

Client ID / Client Secret (eStamp OAuth)

client_id und client_secret sind die Identifikationsdaten einer Anwendung gegenüber dem eStamp-Authentifizierungsserver.

  • client_id: Der „Benutzername" der Anwendung – der Name, unter dem sie beim Auth-Server registriert ist.

  • client_secret: Das „Passwort" der Anwendung – ein geheimer Schlüssel, den nur die Anwendung und der Auth-Server kennen. Zusammen mit der client_id beweist er die Identität der Anwendung.

[!WARNING] Das client_secret darf niemals im Quellcode oder in versionierten Konfigurationsdateien gespeichert werden.

issuer-uri / auth-server-url (eStamp OAuth)

  • issuer-uri: Die Adresse des Identity Providers (z.B. Keycloak), der eStamp-Tokens ausstellt. Identifiziert eindeutig, wer die Tokens autorisiert.

  • auth-server-url: Die konkrete URL, an die Token-Anfragen gesendet werden. Oft ähnlich wie issuer-uri, kann aber leicht abweichen.

Beide Werte werden von XiTrust beim Deployment festgelegt und kommuniziert.

TLS (eStamp-Verbindungssicherheit)

eStamp verwendet ausschließlich HTTPS-Verbindungen. Unterstützte TLS-Versionen:

Version

Status

TLS 1.3

✅ Standard

TLS 1.2

✅ Unterstützt

TLS 1.1 und älter

❌ Nicht akzeptiert


C: API-Konzepte & Workflows

Dieser Abschnitt erklärt die grundlegenden API-Konzepte und Workflow-Typen der eStamp REST-API. Alle Endpunkte sind unter dem Basispfad /signApi/... erreichbar.

eStamp REST-API

Die eStamp REST-API ist die standardisierte HTTP-Schnittstelle zur Kommunikation mit dem eStamp-Signierservice. Alle Aufrufe erfolgen über HTTPS. Es gibt zwei HTTP-Methoden:

  • GET – Konfigurationsinformationen abrufen (z.B. verfügbare parameterId-Werte)

  • POST – Dokumente senden und Signiervorgänge auslösen

Kein exotisches Protokoll: Wer bereits mit REST-Webservices gearbeitet hat, kennt das Prinzip.

Synchroner Workflow (eStamp)

Ein eStamp-synchroner Workflow ist ein einzelner API-Aufruf, der ein PDF-Dokument entgegennimmt, sofort signiert und das signierte Dokument direkt zurückgibt. Es gibt keine Session, kein Zwischenspeichern und keinen Status-Endpoint.

Ablauf:

  1. PDF + parameterId per POST senden

  2. eStamp signiert synchron

  3. Signiertes PDF als Binary-Response empfangen

Verfügbare Endpunkte:

Endpunkt

Wann verwenden

POST /signApi/sealSingle

Signieren ohne Visualisierung

POST /signApi/sealSingleWithAppearance

Signieren mit individueller Visualisierung (JSON-Datei)

POST /signApi/sealSingleWithAppearanceParam

Signieren mit serverseitig vordefinierter Visualisierung (ID)

→ Siehe: [eStamp Workflow-Anleitungen: Synchrones Signieren (Single Request)]

Session-basierter Workflow / Batch-Workflow (eStamp)

Ein eStamp-session-basierter Workflow (auch: Batch-Workflow) ist ein mehrstufiger Prozess zur gleichzeitigen Verarbeitung mehrerer Dokumente innerhalb einer Sitzung (Session). Er wird verwendet, wenn mehr als ein Dokument auf einmal signiert werden soll.

Reihenfolge der Aufrufe (bindend):

Schritt

Methode

Endpunkt

Beschreibung

1

POST

/signApi/startSession

Neue Session starten, sessionId erhalten

2

POST

/{sessionId}/addDocument

Dokument(e) hinzufügen (wiederholbar, max. 100)

3

POST

/{sessionId}/seal

Signiervorgang für alle Dokumente auslösen

4

GET

/{sessionId}/getDocument/{documentId}

Signierte Dokumente abrufen

5

POST

/{sessionId}/closeSession

Session beenden

[!WARNING] Die Reihenfolge ist bindend. getDocument vor seal gibt HTTP 404 zurück. Alle Dokumente vor closeSession abrufen – danach sind sie nicht mehr verfügbar.

→ Siehe: [eStamp Workflow-Anleitungen für das Signieren und Validieren von PDF-Dokumenten: Session-basiertes Signieren (Batch)]

Session (eStamp)

Eine eStamp-Session ist ein temporärer Verarbeitungskontext für einen Batch-Signiervorgang. Sie wird über eine sessionId referenziert, die bei POST /signApi/startSession zurückgegeben wird.

Wichtige Session-Eigenschaften:

Eigenschaft

Wert

Gültigkeitsdauer

40 Minuten

Max. Dokumente pro Session

100

Dokumente nachträglich entfernen

❌ Nicht möglich

Automatische Bereinigung

✅ Ja (abgelaufene Sessions werden automatisch gelöscht)

[!NOTE] Wenn ein falsches Dokument hinzugefügt wurde, muss eine neue Session gestartet werden – Dokumente können nach dem Hinzufügen nicht mehr entfernt werden.

parameterId (eStamp-Pflichtfeld)

Die parameterId ist ein Pflichtfeld bei jedem eStamp-Seal-Aufruf. Sie steuert, welcher Signaturhandler verwendet wird, welches Zertifikat genutzt wird und welches Sealing-Verhalten greift. Ohne gültige parameterId gibt die eStamp-API HTTP 400 zurück.

Verfügbare parameterId-Werte abfragen:

CODE
# eStamp-API: Verfügbare parameterId-Werte abrufen
# Dieser Aufruf sollte vor dem ersten Seal-Vorgang ausgeführt werden

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

# Erfolgreiche Response (200 OK):
# [{ "parameterId": "seal", "displayName": "...", ... }]
#
# Fehler 404: Bearer Token fehlt oder Base URL falsch

multipart/form-data (eStamp Upload-Format)

multipart/form-data ist das HTTP-Übertragungsformat, das von den meisten eStamp-Endpunkten für Datei-Uploads verwendet wird. Dabei werden PDF-Dokumente, JSON-Konfigurationen und String-Parameter in einem einzigen HTTP-Request gebündelt.

Wichtig: Dokumente müssen mit Content-Type: application/pdf übergeben werden. Andere Formate (application/octet-stream, XML etc.) werden von der eStamp-API abgelehnt (HTTP 415).


D: Signaturvisualisierung

Dieser Abschnitt erklärt alle Konzepte der eStamp-Signaturvisualisierung – also wie eine Signatur optisch in einem PDF-Dokument dargestellt wird. Die Konfiguration erfolgt über das signatureAppearance-JSON-Objekt.

[!WARNING] Es gibt zwei Sonderfälle (VisualizationAutomation und signatureFieldId), die sich gegenseitig ausschließen und nicht kombiniert werden dürfen.

signatureAppearance (eStamp)

Die eStamp-signatureAppearance ist eine JSON-Konfiguration, die festlegt, wie eine Signatur optisch im PDF dargestellt wird – Position, Größe, Signaturbild und Seitenbereich. Sie kann auf zwei Arten übergeben werden:

  1. Als JSON-Datei direkt im Request (sealSingleWithAppearance, addDocumentWithAppearance)

  2. Als serverseitig vordefinierte ID (appearanceId) als Query-Parameter (sealSingleWithAppearanceParam, addDocumentWithAppearanceParam)

Welchen Modus verwenden?

Situation

Empfohlener Modus

Position und Seite individuell pro Aufruf festlegen

JSON-Datei direkt übergeben

Standardisierte Firmen-Visualisierung wiederverwenden

appearanceId als Query-Parameter

PDF hat bereits definierte Signaturfelder

Sonderfall: signatureFieldId

Signatur automatisch ans Dokumentende setzen

Sonderfall: VisualizationAutomation

Pflichtfelder (Standardfall):

Feld

Typ

Beschreibung

signatureImageId

string

ID des serverseitig hinterlegten Signaturbilds

lastPage

int

Letzte Seite mit Signatur (-1 = letzte Seite des Dokuments)

onEveryPage

boolean

true = Signatur auf jeder Seite im Bereich

x

int

Horizontale Position in pt

y

int

Vertikale Position in pt

Optionale Felder (Standardfall):

Feld

Typ

Standard

Beschreibung

signaturePageId

string

ID einer zusätzlichen Signaturseite

firstPage

int

1

Erste Seite, auf der die Signatur erscheint

width

int

400

Breite der Visualisierung in pt

height

int

270

Höhe der Visualisierung in pt

signatureAttributes

object

Zertifikatsattribute (nur Amtssignatur)

[!NOTE] Koordinatensystem: x/y sind Koordinaten, width/height werden in pt (Punkten) angegeben – gleiche Logik wie in MOXIS.

Vollständiges Beispiel-JSON (Standardfall):

CODE
{
  "signatureImageId": "amtsSignatur",
  "signaturePageId": "default",
  "firstPage": 1,
  "lastPage": -1,
  "onEveryPage": true,
  "x": 100,
  "y": 100,
  "width": 400,
  "height": 250,
  "signatureAttributes": {
    "subjectDn": "Aussteller"
  }
}

[!WARNING] Wenn onEveryPage: true gesetzt ist, darf signaturePageId nicht gesetzt werden.

→ Siehe: [eStamp API Referenz und Endpunkte: SignatureAppearance]

signatureImageId (eStamp-Pflichtfeld)

signatureImageId ist ein Pflichtfeld in jeder eStamp-signatureAppearance-Konfiguration. Es referenziert das serverseitig hinterlegte Signaturbild, das im PDF angezeigt werden soll. Ohne dieses Feld funktioniert die Visualisierung nicht.

Der Wert muss einer der serverseitig konfigurierten Bild-IDs entsprechen. Verfügbare IDs werden über GET /signApi/signatureAppearanceInfos abgefragt.

signaturePageId (eStamp)

signaturePageId ist ein optionales Feld in der eStamp-signatureAppearance. Es verweist auf eine zusätzliche Signaturseite, die ans Dokument angehängt wird.

[!WARNING] signaturePageId darf nicht zusammen mit onEveryPage: true verwendet werden. Bei VisualizationAutomation muss signaturePageId gesetzt und gültig sein.

signatureFieldId (eStamp – Sonderfall)

signatureFieldId ist ein optionales Feld für den Sonderfall, dass ein PDF bereits vordefinierte Signaturfelder enthält. Wenn gesetzt, wird die Signaturvisualisierung direkt in das angegebene Signaturfeld platziert – ohne manuelle Koordinatenangabe.

Wenn signatureFieldId gesetzt ist, entfallen diese Felder: firstPage, lastPage, onEveryPage, x, y, width, height

Minimal-JSON mit signatureFieldId:

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

Signaturfeld-Namen eines PDFs abfragen:

CODE
# eStamp-API: Vorhandene Signaturfelder eines PDFs ermitteln
POST /signApi/signatureFieldNames
# Parameter: document (binary PDF)
# Response: JSON-Array der signatureFieldId-Werte

[!NOTE] Wenn signatureFieldId nicht gesetzt ist, wird die Position automatisch aus dem ersten Signaturfeld des PDFs übernommen.

VisualizationAutomation (eStamp – Sonderfall)

VisualizationAutomation ist ein Sonderfall der eStamp-signatureAppearance, bei dem die Signaturvisualisierung automatisch am Ende des letzten Textzeichens der letzten Seite platziert wird. Wenn kein Platz oberhalb der Fußzeile vorhanden ist, wird automatisch eine neue Signaturseite erzeugt.

Pflichtfelder im visualizationAutomation-Block:

Feld

Typ

Beschreibung

footerHeight

int

Höhe der Fußzeile in pt

margin

int

Abstand zwischen letztem Textzeichen und Signaturbild in pt

signaturePageMargin

int

Abstand oberhalb der Signaturseite bei automatischem Seitenumbruch in pt

Beispiel-JSON:

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

[!WARNING] Bei VisualizationAutomation müssen folgende Bedingungen erfüllt sein:

  • signaturePageId muss gesetzt und gültig sein

  • signatureAttributes darf nicht gesetzt sein

  • Darf nicht mit signatureFieldId kombiniert werden

signatureAttributes (eStamp – Amtssignatur)

signatureAttributes ist ein optionales Feld in der eStamp-signatureAppearance, das zusätzliche X.509-Zertifikatsattribute in der Signaturvisualisierung anzeigt.

[!NOTE] signatureAttributes ist nur sinnvoll bei Amtssignaturen. Bei anderen Signaturtypen hat dieses Feld keine Wirkung.

Verfügbare Zertifikatsattribute:

Schlüssel (technisch, fix)

Anzeigetext (frei wählbar)

subjectDn

z.B. "Aussteller"

issuerDn

z.B. "Zertifizierungsstelle"

notBefore

z.B. "Erstellungsdatum"

notAfter

z.B. "Ablaufdatum"

serialNumber

z.B. "Seriennummer"

sigAlgName

z.B. "Signaturalgorithmus"

sigAlgOID

z.B. "Signatur OID"

signatureDate?datetime?iso_utc

z.B. "Signierdatum (UTC)"

type

z.B. "Typ"

version

z.B. "Version"

[!TIP] Der linke Wert (Schlüssel) ist technisch vorgegeben und darf nicht geändert werden. Der rechte Wert (Anzeigetext) kann frei gewählt werden.


E – Paraphen

Dieser Abschnitt erklärt die Paraphen-Funktion der eStamp-API. Eine Paraphe ist ein kleines Signaturbild, das ergänzend zur Hauptsignatur auf Seiten eines Dokuments platziert wird.

Paraphe (eStamp)

Eine eStamp-Paraphe ist ein kleines Signaturbild, das auf Seiten eines Dokuments platziert wird – typischerweise als seitliche Abzeichnung. Die Konfiguration erfolgt über eine eigene JSON-Konfiguration (paraphenImage-Parameter), die optional zu jedem Seal-Aufruf hinzugefügt werden kann.

paraphImageId (eStamp-Pflichtfeld)

paraphImageId ist ein Pflichtfeld der eStamp-Paraphen-Konfiguration. Es referenziert das serverseitig hinterlegte Paraphenbild.

Pflichtfelder der Paraphen-Konfiguration:

Feld

Pflicht

Beschreibung

paraphImageId

✅ Ja

ID des serverseitig hinterlegten Paraphenbilds

width

✅ Ja

Breite der Paraphe in pt

height

✅ Ja

Höhe der Paraphe in pt

x

✅ Ja

Horizontale Position in pt

y

✅ Ja

Vertikale Position in pt

Beispiel-JSON:

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

ParaphenAppearance (eStamp)

Die eStamp-ParaphenAppearance ist die serverseitige Konfiguration des Paraphen-Erscheinungsbilds (YAML). Sie ist analog zur signatureAppearance, aber für Paraphen. Verfügbare Paraphen-IDs werden über GET /signApi/paraphenInfos abgefragt.

Serverseitige YAML-Konfiguration (Beispiel):

CODE
estamp:
  paraphen-image:
    picture1: classpath:/paraphenImages/picture1.jpg
    picture2: classpath:/paraphenImages/picture2.png
  paraphen-appearance:
    paraphen1: classpath:/paraphenAppearance/paraphenAppearance1.json
    paraphen2: classpath:/paraphenAppearance/paraphenAppearance2.json

F – Fehlercodes & Betrieb

Dieser Abschnitt erklärt alle HTTP-Statuscodes, Timeouts und Betriebskonzepte der eStamp REST-API. Für jede Fehlersituation sind Ursachen und konkrete Lösungsschritte angegeben.

HTTP-Statuscodes (eStamp – Übersicht)

Code

Bedeutung

Typische Ursache

200

OK – Anfrage erfolgreich

400

Bad Request

Ungültige parameterId, fehlende Pflichtfelder, falsches PDF-Format

401

Unauthorized

Bearer Token fehlt, ungültig oder abgelaufen

403

Forbidden

Falsche Authentifizierungsmethode

404

Not Found

Falsche Base URL, unbekannte sessionId, Handler nicht gefunden

406

Not Acceptable

Fehlerhafte Appearance-Konfiguration, Zertifikatsproblem

412

Precondition Failed

Ungültige sessionId

413

Payload Too Large

Datei überschreitet konfiguriertes Limit

415

Unsupported Media Type

Falscher Content-Type (erwartet: application/pdf)

422

Unprocessable Entity

Ungültiges oder beschädigtes PDF, fehlerhafte JSON-Konfiguration

429

Too Many Requests

Dokumentlimit der Session erreicht (max. 100) oder zu viele parallele Requests

451

Unavailable for Legal Reasons

JWT-Token abgelaufen

500

Internal Server Error

Unerwarteter Systemfehler, Zertifikatsproblem, Infrastrukturproblem

HTTP 400 – Bad Request (eStamp)

Die eStamp-API gibt HTTP 400 zurück, wenn der Request ungültig ist.

Häufige Ursachen:

  • parameterId existiert nicht → GET /signApi/parameterInfos aufrufen

  • Pflichtfelder in signatureAppearance fehlen

  • Ungültige Session-Operation (z.B. addDocument nach seal)

Lösungsschritte: parameterId prüfen, JSON-Konfiguration gegen Pflichtfelder validieren.

HTTP 401 – Unauthorized (eStamp)

Die eStamp-API gibt HTTP 401 zurück, wenn die Authentifizierung fehlschlägt.

Häufige Ursachen:

  • Authorization: Bearer <token>-Header fehlt im Request

  • Bearer Token ist abgelaufen (expires_in überschritten)

  • Token wurde mit falschen client_id/client_secret-Werten generiert

Lösungsschritte:

  1. Prüfen, ob der Authorization-Header korrekt gesetzt ist

  2. expires_in aus der Token-Response prüfen und ggf. neuen Token anfordern

  3. OAuth-Konfiguration (issuer-uri, client-id) verifizieren

HTTP 404 – Not Found (eStamp)

Die eStamp-API gibt HTTP 404 zurück, wenn ein Endpunkt oder eine Ressource nicht gefunden wird.

Häufige Ursachen:

  • Falsche Base URL oder falscher Endpunkt-Pfad

  • Unbekannte oder abgelaufene sessionId

  • getDocument vor seal aufgerufen

Lösungsschritte: Base URL prüfen, Groß-/Kleinschreibung im Pfad prüfen, Session-Status prüfen.

HTTP 422 – Unprocessable Entity (eStamp)

Die eStamp-API gibt HTTP 422 zurück, wenn das PDF-Dokument oder die JSON-Konfiguration ungültig ist.

Häufige Ursachen:

  • PDF ist beschädigt oder kein gültiges PDF/A

  • Pflichtfelder in signatureAppearance fehlen

  • Unerlaubte Kombination von Sonderfällen (z.B. VisualizationAutomation + signatureAttributes)

Lösungsschritte:

  1. PDF mit POST /signApi/validatePdf validieren

  2. JSON-Konfiguration gegen Pflichtfelder prüfen

  3. Sonderfall-Kombination prüfen: signatureFieldId und VisualizationAutomation schließen sich gegenseitig aus

HTTP 500 – Internal Server Error (eStamp)

Die eStamp-API gibt HTTP 500 zurück, wenn ein unerwarteter Systemfehler aufgetreten ist.

Mögliche Ursachen: Infrastrukturproblem, Zertifikatsproblem, Signaturerstellung schlägt intern fehl.

Lösungsschritte: Logs prüfen, Support kontaktieren unter servicedesk@xitrust.com mit: Timestamp der Anfrage, Endpunkt, sessionId (falls vorhanden) und vollständigem HTTP-Statuscode.

Timeout (eStamp)

Die eStamp-API kennt zwei Zeitgrenzen, die häufig verwechselt werden:

Zeitgrenze

Wert

Beschreibung

API-Call-Timeout

~30 Sekunden

Maximale Dauer eines einzelnen API-Aufrufs. Bei Überschreitung: Abbruch + Fehlermeldung.

Session-Gültigkeit

40 Minuten

Gesamtgültigkeitsdauer einer Batch-Session. Nach Ablauf: Session ungültig, Prozess neu starten.

[!NOTE] Ein Timeout bedeutet nicht, dass das Dokument beschädigt ist – nur, dass der Request zu lange gedauert hat.

Retry-Strategie (eStamp)

Bei HTTP 429 (Too Many Requests) oder Timeout empfiehlt sich folgende Retry-Strategie für die eStamp-API:

CODE
1. Kurze Wartezeit einlegen: 2–5 Sekunden
2. Request erneut senden
3. Aggressive Parallelisierung vermeiden
4. Bei Batch-Verarbeitung: Requests staffeln

[!TIP] eStamp ist kein Streaming-System, sondern für kontrollierte, sequenzielle API-Aufrufe ausgelegt.

sessionId (eStamp)

Die eStamp-sessionId ist die eindeutige Kennung einer Batch-Signing-Session. Sie wird bei POST /signApi/startSession als JSON-String zurückgegeben und bei allen Folgeaufrufen als Pfadparameter verwendet (/{sessionId}/addDocument etc.).

Wichtig für Support-Anfragen: Bei Problemen mit dem Batch-Workflow immer sessionId, Timestamp und HTTP-Statuscode bereithalten.


G – Tools & Hilfskonzepte

Dieser Abschnitt erklärt unterstützende Tools und übergreifende Konzepte rund um die eStamp-API.

Swagger (eStamp API-Testoberfläche)

Swagger ist eine interaktive API-Dokumentationsplattform auf Basis der OpenAPI-Spezifikation, die das direkte Testen von eStamp-Endpunkten im Browser ermöglicht. Sie unterstützt den gesamten API-Entwicklungslebenszyklus von Design bis Test.

Swagger mit OAuth 2.0 verwenden:

  1. Swagger-UI der eStamp-Instanz öffnen

  2. Auf [Authorize]-Button klicken

  3. client_id und client_secret eingeben – Bearer Token wird automatisch gesetzt

  4. API-Aufrufe direkt ausführen

Partial Failure (eStamp)

eStamp unterstützt kein Partial Failure. Bei einem Batch-Vorgang gilt: Entweder werden alle Dokumente erfolgreich signiert, oder der gesamte Prozess schlägt fehl. Es gibt keine teilweise Verarbeitung einzelner Dokumente innerhalb einer Session.

Backward Compatibility (eStamp)

eStamp führt keine Breaking Changes durch. Bestehende Integrationen bleiben nach Updates weiterhin funktionsfähig. Es gibt keine Versionsabhängigkeiten, keine versteckten Systemkopplungen und keine komplizierten Upgrade-Szenarien. Die letzten 3 Versionen werden aktiv supportet.


Bei Fragen kontatkieren Sie bitte unseren Support:
XiTrust Support Team | servicedesk@xitrust.com | Service Desk Ticket erstellen

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.