eStamp: FAQ zu Authentifizierung, Workflows, Limits und Fehlercodes

Inhalt

Dieses Dokument beantwortet häufig gestellte Fragen zur eStamp REST-API, gegliedert nach Themenbereich. Jede Frage ist als eigenständige Einheit formuliert und enthält den vollständigen Kontext für die Antwort. Voraussetzung für die Nutzung der eStamp REST-API: eine gültige, kundenspezifische eStamp Base URL und ein gültiger Bearer Token (OAuth 2.0 oder Basic Authorization).

1. Architektur und Grundkonzepte

Welche Base URL erhält eine eStamp-Instanz?

Jede eStamp-Instanz erhält beim Deployment eine eigene, kundenspezifische Base URL. Das Format ist https://estamp.<kundenname>.xitrust.cloud/estamp. Die Base URL wird vom XiTrust Support Team festgelegt und beim Deployment kommuniziert. Ohne korrekte eStamp Base URL schlagen alle API-Aufrufe mit 404 Not Found fehl. Wenn ein eStamp-Service nicht erreichbar ist, ist die Base URL der erste zu prüfende Punkt.

Hat eStamp ein Mandantenmodell?

eStamp kennt kein Mandantenmodell. Es gibt innerhalb einer eStamp-Instanz keine getrennten Mandanten. Unterschiedliche Konfigurationen — zum Beispiel verschiedene Zertifikate, Signaturtypen oder Signatur-Visualisierungen — werden über Signaturhandler innerhalb einer Instanz abgebildet. Mehrere Organisationseinheiten können dadurch unterschiedlich konfiguriert arbeiten, ohne eine eigene Instanz zu benötigen. Für vollständige technische Trennung wird eine separate eStamp-Instanz empfohlen.

Gibt es eine API-Versionierung in eStamp?

eStamp verwendet keine URL-basierte API-Versionierung wie /api/v1/ oder /api/v2/. Stattdessen garantiert XiTrust, dass keine Breaking Changes an der eStamp REST-API durchgeführt werden. Bestehende Integrationen bleiben nach Updates weiterhin funktionsfähig. Die letzten zwei eStamp-Versionen werden aktiv supportet. Ein spezielles Kompatibilitätsmanagement ist daher nicht erforderlich.

Was ist die eStamp REST-API und welche Protokolle werden verwendet?

Die eStamp REST-API ist die Schnittstelle, über die alle Signier-, Siegel- und Validierungsoperationen ausgeführt werden. Die Kommunikation erfolgt ausschließlich über HTTPS mit den Standard-HTTP-Methoden GET (Informationen abrufen) und POST (Dokument senden, Signatur auslösen). Es werden keine proprietären oder exotischen Protokolle verwendet. Der Basispfad aller eStamp-Signatur-Endpoints ist /signApi/....

2. Authentifizierung und Sicherheit

Welche Authentifizierungsmethoden unterstützt eStamp?

eStamp unterstützt zwei Authentifizierungsmethoden: OAuth 2.0 und Basic Authorization. Beide Methoden schützen alle eStamp-Endpoints, die Dokumente verarbeiten. Ohne gültige Authentifizierung werden keine Signier- oder Seal-Vorgänge akzeptiert. OAuth 2.0 ist die empfohlene Methode für alle neuen eStamp-Integrationen.

Was ist der eStamp Bearer Token und wie wird er verwendet?

Der eStamp Bearer Token ist ein Zugriffstoken, das über den OAuth-2.0-Flow (Grant Type: Client Credentials) vom konfigurierten Authentifizierungsserver bezogen wird. Der Bearer Token wird bei jedem eStamp-API-Aufruf im Authorization-Header mitgesendet: Authorization: Bearer <token>. Der Token hat eine begrenzte Gültigkeitsdauer (expires_in). Nach Ablauf gibt die eStamp API 451 Unavailable for Legal Reasons zurück. Integrationen sollten eine automatische Token-Erneuerung vor Ablauf der Gültigkeitsdauer implementieren.

[!IMPORTANT] Der eStamp Bearer Token ist wie ein Passwort zu behandeln. client_id, client_secret und Bearer Token dürfen niemals im Quellcode, in Klartext-Konfigurationsdateien oder in Versionskontrollsystemen gespeichert werden. Empfohlene Ablage: Secret Manager (z. B. HashiCorp Vault, Keycloak, AWS Secrets Manager).

Welche TLS-Version erfordert eStamp?

eStamp erfordert mindestens TLS 1.2. Der Standard ist TLS 1.3. Verbindungsversuche mit älteren TLS-Versionen werden abgelehnt. Alle Verbindungen zur eStamp REST-API sind damit verschlüsselt und entsprechen aktuellen Sicherheitsstandards.

Sind alle eStamp-Endpoints gleich geschützt?

Nein, eStamp unterscheidet zwischen geschützten und ungeschützten Endpoints. Ungeschützt erreichbar sind ausschließlich Lizenzinformations-Endpoints, da diese Informationen nicht sicherheitsrelevant sind. Alle Endpoints, die Dokumente verarbeiten — also Signieren, Sealen und Session-Operationen — sind mit OAuth 2.0 oder Basic Authorization geschützt. Jeder gültig authentifizierte Client kann alle geschützten eStamp-Endpoints verwenden; es gibt keine RBAC, keine User-Rollen und keine unterschiedlichen Berechtigungsstufen.

3. Workflows: Synchron und Session-basiert

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

Der synchrone eStamp-Workflow verarbeitet ein einzelnes Dokument pro API-Aufruf: Das Dokument wird gesendet und das signierte Ergebnis sofort zurückgegeben — ohne Sessions, Zwischenspeicherung oder Statusabfragen. Der session-basierte Workflow ermöglicht die Batch-Verarbeitung mehrerer Dokumente in einem mehrstufigen Ablauf (startSession → addDocument → seal → getDocument → closeSession). Der synchrone Workflow ist für einzelne Dokumente einfacher; der session-basierte Workflow ist für Stapelverarbeitung bis zu 100 Dokumenten pro Session notwendig.

Gibt es in eStamp Hintergrundprozesse oder einen Status-Endpoint?

eStamp arbeitet nicht mit Hintergrundprozessen, Status-Endpoints, Polling oder Webhooks. Jeder eStamp-API-Aufruf blockiert, bis er vollständig abgeschlossen ist, und liefert das Ergebnis direkt zurück. Das gilt sowohl für synchrone Aufrufe als auch für den seal-Schritt im session-basierten Workflow.

Wie viele Dokumente können pro eStamp-Session verarbeitet werden?

Pro eStamp-Batch-Session können maximal 100 Dokumente verarbeitet werden. Dasselbe Limit gilt pro einzelnem REST-Aufruf. Wenn mehr als 100 Dokumente signiert werden müssen, sind mehrere Sessions zu starten. Die Anzahl gleichzeitig laufender Sessions ist nicht limitiert. Pro REST-Aufruf kann nur eine Session gestartet werden.

Ist der eStamp session-basierte Workflow ein echtes Async-Modell?

Nein, der session-basierte eStamp-Workflow ist kein asynchrones Modell. Jeder Aufruf — einschließlich seal — blockiert, bis er abgeschlossen ist. Es gibt keinen Status-Endpoint, keine Job-ID und kein Webhook. Wenn seal abgeschlossen ist, kann getDocument aufgerufen werden.

Wie lange ist eine eStamp-Session gültig?

Eine eStamp-Batch-Session ist ab dem startSession-Aufruf 40 Minuten gültig. Wird die Session innerhalb dieser Zeit nicht mit closeSession beendet, läuft sie automatisch ab. Ein einzelner API-Aufruf innerhalb der Session darf maximal 30 Sekunden dauern. Wird diese Zeit überschritten, wird der Aufruf abgebrochen und eine Fehlermeldung zurückgegeben. Ein Timeout bedeutet nicht zwingend, dass das Dokument beschädigt ist, sondern dass der Aufruf zu lange gedauert hat.

Was passiert bei Timeout oder Abbruch eines eStamp-API-Aufrufs?

Bei Timeout oder Abbruch eines eStamp-API-Aufrufs wird der Prozess beendet und eine Fehlermeldung zurückgegeben. Es erfolgt keine teilweise Verarbeitung. Abgelaufene oder nicht abgeschlossene eStamp-Sessions werden automatisch bereinigt — es ist kein manueller Cleanup erforderlich.

Können Dokumente nach dem Hinzufügen aus einer eStamp-Session entfernt oder ersetzt werden?

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

Gibt es Partial Failure bei der eStamp-Batch-Verarbeitung?

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.

4. Limits und Performance

Welche technischen Limits gelten für die eStamp REST-API?

Für die eStamp REST-API gelten folgende Limits: maximal 100 Dokumente pro Session und pro REST-Aufruf, ein Timeout von 30 Sekunden pro einzelnem API-Aufruf, eine Session-Gültigkeit von 40 Minuten ab startSession, und eine maximale Dateigröße die instanzspezifisch in der Systemkonfiguration definiert ist. Die maximale Dateigröße ist nicht fest vorgegeben und kann je nach eStamp-Instanz unterschiedlich sein.

Welche Rate Limits gibt es bei eStamp?

eStamp definiert keine öffentlich festgelegte Rate-Limit-Grenze (z. B. „X Requests pro Sekunde"). Bei zu vielen gleichzeitigen Anfragen kann es zu verlängerten Antwortzeiten, Timeouts oder HTTP 429 Too Many Requests kommen. eStamp ist für kontrollierte, sequenzielle API-Aufrufe konzipiert und kein Streaming-System. Aggressive Parallelisierung sollte vermieden werden.

Was bedeutet HTTP 429 bei eStamp und wie reagiert man darauf?

HTTP 429 Too Many Requests signalisiert, dass zu viele Anfragen in kurzer Zeit gesendet wurden, oder dass das Dokumentlimit einer Session erreicht wurde. Die empfohlene Retry-Strategie: eine Wartezeit von 2–5 Sekunden einlegen und den Request erneut senden. Batch-Verarbeitungen sollten bei hohem Volumen gestaffelt werden.

5. Datei-Upload und Dateiformate

Welche Dateiformate akzeptiert eStamp für Uploads?

eStamp akzeptiert für Dokument-Uploads ausschließlich application/pdf. Andere Formate wie application/octet-stream, XML oder sonstige Dokumenttypen werden für PDF-Signatur-Endpoints nicht akzeptiert und führen zu 415 Unsupported Media Type. XML-Dokumente können über den separaten Endpoint POST /xmlSignApi/validateXml validiert werden.

Gibt es eine maximale Dateigröße bei eStamp?

Ja, aber die maximale Dateigröße ist nicht global fest vorgegeben. Sie ist in der Systemkonfiguration der jeweiligen eStamp-Instanz definiert und kann daher je nach Deployment unterschiedlich sein. Überschreitet ein hochgeladenes Dokument das konfigurierte Limit, gibt eStamp 413 Payload Too Large zurück.

Welche Einschränkungen gelten für hochzuladende PDF-Dokumente?

eStamp schränkt weder die Seitenanzahl noch die PDF-Variante ein. Alle gängigen PDF-Varianten — darunter PDF und PDF/A — werden verarbeitet. Temporäre Dateien werden während der Verarbeitung verschlüsselt abgelegt.

6. Signatursteuerung und Visualisierung

Welcher Parameter steuert das Signaturverhalten in eStamp?

Das Signaturverhalten in eStamp wird durch die parameterId gesteuert. Die parameterId ist bei jedem Seal-Aufruf ein Pflichtfeld und bestimmt, welcher Signaturhandler verwendet wird, welches Zertifikat zum Einsatz kommt und welches Sealing-Verhalten greift. Die verfügbaren parameterId-Werte einer eStamp-Instanz werden über GET /signApi/parameterInfos abgefragt.

Wie wird die Signaturvisualisierung (signatureAppearance) an eStamp übergeben?

Die signatureAppearance-Konfiguration kann auf zwei Arten übergeben werden: als JSON-Datei beim Aufruf von sealSingleWithAppearance oder addDocumentWithAppearance, oder als serverseitig hinterlegte ID (appearanceId) beim Aufruf von sealSingleWithAppearanceParam oder addDocumentWithAppearanceParam. Das Format der signatureAppearance-Konfiguration ist immer JSON.

Sind Signaturattribute (signatureAttributes) in eStamp konfigurierbar?

Ja, über das optionale Feld signatureAttributes können zusätzliche X.509-Zertifikatsattribute in der Signaturvisualisierung angezeigt werden — zum Beispiel subjectDn, serialNumber oder notAfter. Die signatureAttributes sind an die Amtssignatur gekoppelt und ergeben nur bei Amtssignaturen einen sinnvollen Einsatz. Bei anderen Signaturtypen sollte das Feld nicht gesetzt werden.

Welche Einheit verwendet das Koordinatensystem der eStamp-Signaturvisualisierung?

Die Positionsangaben x und y beschreiben die Koordinaten der Signaturvisualisierung auf der PDF-Seite. Die Größenangaben width und height werden in pt (Punkten) angegeben. Standardwerte: width = 400, height = 270.

7. Fehlercodes und Debugging

Welche HTTP-Statuscodes verwendet eStamp?

eStamp verwendet Standard-HTTP-Statuscodes. Die folgende Tabelle zeigt die wichtigsten Codes, ihre Bedeutung und typische Ursachen:

Wie sehen eStamp-Fehlerantworten aus?

eStamp gibt Fehler mit einem HTTP-Statuscode und einer Fehlermeldung zurück. Es gibt kein zusätzliches einheitliches JSON-Fehler-Schema — die Fehlerinformation ist im HTTP-Statuscode und der zugehörigen Nachricht enthalten.

Wie debugge ich eStamp-Fehler über Response-Header?

eStamp-Anfragen können über die Request-ID im Response-Header nachverfolgt werden. Die Request-ID ermöglicht die interne Zuordnung zu Log-Einträgen, enthält aber selbst keine inhaltliche Fehlerinformation. Für Supportanfragen sind folgende Angaben hilfreich: Timestamp der Anfrage, verwendeter Endpoint, sessionId (falls vorhanden) und vollständiger HTTP-Statuscode.

Was sind die häufigsten Fehlerursachen bei eStamp?

In der Mehrzahl der Fälle sind eStamp-Fehler auf vier Ursachen zurückzuführen: eine falsche oder ungültige parameterId (400), einen abgelaufenen oder fehlenden Bearer Token (401/451), ein zu großes Dokument (413) oder ein ungültiges bzw. beschädigtes PDF (422). Die Kurzdiagnose für Betrieb und Administration: 400er-Fehler deuten auf Konfigurationsprobleme hin, 401/403 auf Authentifizierungsprobleme, 413 auf Dateigröße und 500 auf Systemprobleme.

Was tun bei HTTP 500 Internal Server Error von eStamp?

HTTP 500 Internal Server Error signalisiert einen unerwarteten Systemfehler in eStamp — zum Beispiel ein Infrastrukturproblem, ein Zertifikatsproblem oder eine fehlgeschlagene Signaturerstellung. Prüfen Sie die eStamp-Server-Logs anhand des Timestamps und der sessionId. Wenn das Problem nicht selbst lösbar ist, kontaktieren Sie das XiTrust Support Team unter servicedesk@xitrust.com mit Timestamp, Endpoint, sessionId und HTTP-Statuscode.

Kurzreferenz: Schnelldiagnose bei eStamp-Fehlern

Wenn ein eStamp-API-Aufruf fehlschlägt, empfiehlt sich folgende Reihenfolge für die Fehlerdiagnose:

1. HTTP-Statuscode prüfen — gibt den Fehlertyp an (siehe Tabelle oben)

2. Bearer Token prüfen — ist der Token gültig und nicht abgelaufen?

3. parameterId prüfen — existiert der Wert in GET /signApi/parameterInfos?

4. Base URL prüfen — ist die kundenspezifische eStamp Base URL korrekt?

5. Dateigröße prüfen — überschreitet das Dokument das konfigurierte Limit?

6. Logs prüfen — anhand Timestamp und sessionId in den eStamp-Server-Logs nachverfolgen