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:
https://estamp.<kundenname>.xitrust.cloud/estamp
Beispiel:
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:
# eStamp-API: Alle konfigurierten Signaturhandler abrufen
GET /signApi/parameterInfos
Authorization: Bearer <token>
Beispiel-Response:
[
{
"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 |
|---|---|---|
| Heimatadresse des Authentifizierungsservers (Identity Provider, z.B. Keycloak) | XiTrust |
| „Benutzername" der Anwendung beim Auth-Server | Kunde |
| „Passwort" der Anwendung (geheimer Schlüssel) | Kunde |
| Konkrete URL für Token-Anfragen | XiTrust |
| Immer | XiTrust |
Token anfordern (cURL):
# 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:
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 erneuernBei 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 derclient_idbeweist er die Identität der Anwendung.
[!WARNING] Das
client_secretdarf 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 wieissuer-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ügbareparameterId-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:
PDF +
parameterIdperPOSTsendeneStamp signiert synchron
Signiertes PDF als Binary-Response empfangen
Verfügbare Endpunkte:
Endpunkt | Wann verwenden |
|---|---|
| Signieren ohne Visualisierung |
| Signieren mit individueller Visualisierung (JSON-Datei) |
| 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 |
| Neue Session starten, |
2 | POST |
| Dokument(e) hinzufügen (wiederholbar, max. 100) |
3 | POST |
| Signiervorgang für alle Dokumente auslösen |
4 | GET |
| Signierte Dokumente abrufen |
5 | POST |
| Session beenden |
[!WARNING] Die Reihenfolge ist bindend.
getDocumentvorsealgibt HTTP 404 zurück. Alle Dokumente vorcloseSessionabrufen – danach sind sie nicht mehr verfügbar.
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:
# 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 (
VisualizationAutomationundsignatureFieldId), 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:
Als JSON-Datei direkt im Request (
sealSingleWithAppearance,addDocumentWithAppearance)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 |
|
PDF hat bereits definierte Signaturfelder | Sonderfall: |
Signatur automatisch ans Dokumentende setzen | Sonderfall: |
Pflichtfelder (Standardfall):
Feld | Typ | Beschreibung |
|---|---|---|
| string | ID des serverseitig hinterlegten Signaturbilds |
| int | Letzte Seite mit Signatur ( |
| boolean |
|
| int | Horizontale Position in pt |
| int | Vertikale Position in pt |
Optionale Felder (Standardfall):
Feld | Typ | Standard | Beschreibung |
|---|---|---|---|
| string | – | ID einer zusätzlichen Signaturseite |
| int | 1 | Erste Seite, auf der die Signatur erscheint |
| int | 400 | Breite der Visualisierung in pt |
| int | 270 | Höhe der Visualisierung in pt |
| object | – | Zertifikatsattribute (nur Amtssignatur) |
[!NOTE] Koordinatensystem:
x/ysind Koordinaten,width/heightwerden in pt (Punkten) angegeben – gleiche Logik wie in MOXIS.
Vollständiges Beispiel-JSON (Standardfall):
{
"signatureImageId": "amtsSignatur",
"signaturePageId": "default",
"firstPage": 1,
"lastPage": -1,
"onEveryPage": true,
"x": 100,
"y": 100,
"width": 400,
"height": 250,
"signatureAttributes": {
"subjectDn": "Aussteller"
}
}
[!WARNING] Wenn
onEveryPage: truegesetzt ist, darfsignaturePageIdnicht 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]
signaturePageIddarf nicht zusammen mitonEveryPage: trueverwendet werden. BeiVisualizationAutomationmusssignaturePageIdgesetzt 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:
{
"signatureImageId": "imageOnly",
"signatureFieldId": "Signatur2"
}
Signaturfeld-Namen eines PDFs abfragen:
# eStamp-API: Vorhandene Signaturfelder eines PDFs ermitteln
POST /signApi/signatureFieldNames
# Parameter: document (binary PDF)
# Response: JSON-Array der signatureFieldId-Werte
[!NOTE] Wenn
signatureFieldIdnicht 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 |
|---|---|---|
| int | Höhe der Fußzeile in pt |
| int | Abstand zwischen letztem Textzeichen und Signaturbild in pt |
| int | Abstand oberhalb der Signaturseite bei automatischem Seitenumbruch in pt |
Beispiel-JSON:
{
"signatureImageId": "amtsSignatur",
"signaturePageId": "default",
"x": 100,
"width": 400,
"height": 250,
"visualizationAutomation": {
"footerHeight": 6,
"margin": 10,
"signaturePageMargin": 60
}
}
[!WARNING] Bei
VisualizationAutomationmüssen folgende Bedingungen erfüllt sein:
signaturePageIdmuss gesetzt und gültig sein
signatureAttributesdarf nicht gesetzt seinDarf nicht mit
signatureFieldIdkombiniert werden
signatureAttributes (eStamp – Amtssignatur)
signatureAttributes ist ein optionales Feld in der eStamp-signatureAppearance, das zusätzliche X.509-Zertifikatsattribute in der Signaturvisualisierung anzeigt.
[!NOTE]
signatureAttributesist nur sinnvoll bei Amtssignaturen. Bei anderen Signaturtypen hat dieses Feld keine Wirkung.
Verfügbare Zertifikatsattribute:
Schlüssel (technisch, fix) | Anzeigetext (frei wählbar) |
|---|---|
| z.B. |
| z.B. |
| z.B. |
| z.B. |
| z.B. |
| z.B. |
| z.B. |
| z.B. |
| z.B. |
| z.B. |
[!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 |
|---|---|---|
| ✅ Ja | ID des serverseitig hinterlegten Paraphenbilds |
| ✅ Ja | Breite der Paraphe in pt |
| ✅ Ja | Höhe der Paraphe in pt |
| ✅ Ja | Horizontale Position in pt |
| ✅ Ja | Vertikale Position in pt |
Beispiel-JSON:
{
"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):
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 |
401 | Unauthorized | Bearer Token fehlt, ungültig oder abgelaufen |
403 | Forbidden | Falsche Authentifizierungsmethode |
404 | Not Found | Falsche Base URL, unbekannte |
406 | Not Acceptable | Fehlerhafte Appearance-Konfiguration, Zertifikatsproblem |
412 | Precondition Failed | Ungültige |
413 | Payload Too Large | Datei überschreitet konfiguriertes Limit |
415 | Unsupported Media Type | Falscher Content-Type (erwartet: |
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:
parameterIdexistiert nicht →GET /signApi/parameterInfosaufrufenPflichtfelder in
signatureAppearancefehlenUngültige Session-Operation (z.B.
addDocumentnachseal)
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 RequestBearer Token ist abgelaufen (
expires_inüberschritten)Token wurde mit falschen
client_id/client_secret-Werten generiert
Lösungsschritte:
Prüfen, ob der
Authorization-Header korrekt gesetzt istexpires_inaus der Token-Response prüfen und ggf. neuen Token anfordernOAuth-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
sessionIdgetDocumentvorsealaufgerufen
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
signatureAppearancefehlenUnerlaubte Kombination von Sonderfällen (z.B.
VisualizationAutomation+signatureAttributes)
Lösungsschritte:
PDF mit
POST /signApi/validatePdfvalidierenJSON-Konfiguration gegen Pflichtfelder prüfen
Sonderfall-Kombination prüfen:
signatureFieldIdundVisualizationAutomationschließ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:
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:
Swagger-UI der eStamp-Instanz öffnen
Auf [Authorize]-Button klicken
client_idundclient_secreteingeben – Bearer Token wird automatisch gesetztAPI-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