Sandbox starten: der kürzeste Weg zur ersten Antwort
Die meisten Integrationen scheitern nicht an der Technik, sondern an der Zeit bis zum ersten Erfolgserlebnis. Wer drei Wochen braucht, bis ein Testdokument signiert ist, verliert Rückhalt im Team und im Management. Deshalb ist unser Ziel für den Developer Hub einfach: Ein Entwickler soll innerhalb eines Nachmittags von der Registrierung zur ersten erfolgreichen Anfrage kommen. Die Sandbox ist der Ort dafür, eine Testumgebung, in der Sie Abläufe ausprobieren können, ohne reale Vorgänge auszulösen.
Beginnen Sie mit den Voraussetzungen. Sie benötigen einen Zugang zum Developer Hub, Zugangsdaten für die Sandbox, einen Weg, HTTP-Anfragen zu senden, und ein einfaches Testdokument. Ein PDF mit einer Seite genügt. Die genauen Schritte zur Anmeldung, die Zugangsverfahren und die aktuellen Endpunkte finden Sie in der Dokumentation des Developer Hub, und wir beschreiben sie hier bewusst nicht im Detail, damit dieser Beitrag nicht veraltet, wenn sich Einzelheiten ändern.
Ein kluger erster Schritt ist ein Verbindungstest: eine einfache Anfrage, die nur prüft, ob Ihre Zugangsdaten gültig sind und die Umgebung antwortet. Das klingt banal und erspart Ihnen später stundenlange Fehlersuche, weil Sie Authentifizierungs- und Netzwerkprobleme von Fachproblemen trennen. Notieren Sie sich die Antwortzeiten und die Struktur der Antworten, denn Ihr eigener Code wird sie später verarbeiten müssen. Viele Teams sparen Zeit, indem sie die ersten Aufrufe in einem Werkzeug wie einem API-Client ausprobieren, bevor sie Code schreiben. Speichern Sie die funktionierenden Aufrufe als Sammlung, die Sie mit Kolleginnen und Kollegen teilen können. So entsteht ohne großen Aufwand ein lebendiges Handbuch für Ihr Team, und neue Mitglieder starten nicht wieder bei null. Ergänzen Sie jede Anfrage um eine kurze Notiz, wozu sie dient und welche Fehler Sie dabei gesehen haben. Diese Notizen sind später Gold wert, wenn jemand ein ähnliches Problem debuggen muss und nicht weiß, wo er beginnen soll.
Legen Sie außerdem von Anfang an Konfiguration und Geheimnisse sauber ab. Zugangsdaten gehören nicht in den Quellcode und nicht in Chat-Nachrichten, sondern in eine Geheimnisverwaltung oder zumindest in Umgebungsvariablen. Trennen Sie Sandbox- und Produktionszugänge strikt, und benennen Sie Konfigurationen so, dass Verwechslungen unwahrscheinlich sind. Das ist Standardhygiene, aber bei Signaturdaten besonders wichtig, weil sie vertrauliche Verträge betreffen. Orientierung zu sicherer Konfiguration bietet das BSI.
Ein Wort zur Erwartung: Die Sandbox bildet das Verhalten der Produktionsumgebung ab, ist aber nicht in jedem Detail identisch. Einzelne Verfahren, etwa Identifizierungen oder Schritte, die einen Partner erfordern, verhalten sich in Tests anders oder sind vereinfacht. Das ist normal und gewollt, denn echte Identifizierungen in Testumgebungen wären weder sinnvoll noch datenschutzgerecht. Planen Sie deshalb einen separaten Abnahmetest, bevor Sie live gehen. Was in der Sandbox genau möglich ist, entnehmen Sie der Dokumentation.
Die erste Envelope: vom Dokument zur Einladung
Im Zentrum jeder Integration steht der Signaturvorgang, den wir im Alltag auch Envelope nennen: ein Container, der Dokumente, Unterzeichner, Reihenfolge, Stufe und Einstellungen bündelt. Die erste Envelope sollte so einfach wie möglich sein: ein Dokument, ein Unterzeichner, einfache Signatur (SES) oder fortgeschrittene (AES), keine Sonderregeln. Ziel ist nicht Funktionsumfang, sondern ein durchlaufender Vorgang, an dem Sie das Zusammenspiel verstehen.
Konzeptionell besteht die Anlage aus vier Schritten. Erstens legen Sie den Vorgang an und geben Ihre eigene Referenz mit, damit Sie ihn später wiederfinden. Zweitens fügen Sie das Dokument hinzu und definieren, wo signiert werden soll. Drittens hinterlegen Sie die Unterzeichner mit Namen, Kontaktweg und Rolle. Viertens starten Sie den Vorgang, woraufhin die Einladung versendet wird. Die genauen Aufrufe, Felder und Antwortformate stehen in der API-Referenz. Halten Sie sich daran, statt aus Beispielen anderer Anbieter zu raten.
Nach dem Start empfehlen wir, den Vorgang als Unterzeichner zu durchlaufen. Öffnen Sie die Einladung, lesen Sie die Texte, klicken Sie durch die Schritte und signieren Sie. Dieser Blickwechsel ist unterschätzt: Entwickler kennen oft nur die API-Seite und sind überrascht, wie sich der Ablauf für Nutzer anfühlt. Notieren Sie Auffälligkeiten, etwa unklare Texte, zu viele Klicks oder Fehlermeldungen. Diese Beobachtungen fließen später in Ihre Gestaltung ein, besonders wenn Sie die Strecke in Ihre Oberfläche einbetten.
Dann lohnt der Blick auf das Ergebnis: Welche Informationen erhalten Sie am Ende? Das signierte Dokument, Angaben zum Ablauf, Zeitpunkte, gegebenenfalls Nachweise. Prüfen Sie, wo Sie diese Daten abrufen, wie lange sie verfügbar sind und in welchem Format. Legen Sie fest, wo Ihr System das signierte Dokument speichert, und prüfen Sie, ob die Prüfsumme dem übergebenen Original entspricht. So erkennen Sie früh, ob Ihre Ablage die Anforderungen erfüllt.
Wenn die erste Envelope läuft, erweitern Sie schrittweise: mehrere Unterzeichner, Reihenfolge, Erinnerungen, Fristen, Vorlagen. Erweitern Sie immer nur eine Sache auf einmal und testen Sie sie, bevor Sie die nächste hinzunehmen. So wissen Sie bei einem Fehler, woran er liegt. Wer fünf Funktionen gleichzeitig einbaut, sucht bei Problemen in fünf Richtungen. Wie sich Strecken später ohne Medienbruch in Ihr Produkt einbetten lassen, beschreibt der Beitrag White-label Signatur-API ohne Medienbruch.
Webhooks anbinden: Ihr System erfährt, was passiert
Ohne Rückkanal ist Ihre Integration blind. Nach dem Start der Envelope weiß Ihr System nicht, ob der Unterzeichner geöffnet, signiert oder abgelehnt hat. Webhooks schließen diese Lücke, indem die Signaturstrecke Zustandswechsel aktiv an einen Endpunkt in Ihrer Anwendung meldet. In der Sandbox lässt sich das gut üben, weil Fehler dort folgenlos bleiben.
Für den Start brauchen Sie einen erreichbaren Endpunkt. Bei lokaler Entwicklung ist das die erste praktische Hürde, weil Ihr Rechner aus dem Internet nicht erreichbar ist. Hilfsmittel, die lokale Ports vorübergehend nach außen verfügbar machen, oder ein einfacher Testserver in der Cloud lösen das. Achten Sie darauf, solche Zugänge nur für Tests zu nutzen und danach abzuschalten. Registrieren Sie den Endpunkt gemäß Dokumentation und lösen Sie anschließend Ereignisse aus, indem Sie die Testvorgänge durchlaufen.
Der erste Endpunkt sollte nur empfangen und protokollieren: die Nachricht prüfen, in eine Tabelle oder Datei schreiben und mit einem Erfolgscode antworten. Mehr nicht. Schauen Sie sich die Nutzlast genau an: Welche Felder enthält sie, wie sehen Ereignistypen aus, wie sind Zeitangaben formatiert, welche Referenzen kommen zurück? Dieses Wissen ist Grundlage Ihres Zustandsmodells. Erst danach bauen Sie Logik auf, mit Idempotenz, Zustandsautomat und Wiederholungen, wie wir sie im Beitrag Webhook State Management für E-Signatur-Events beschreiben.
Testen Sie auch Fehlerfälle. Was passiert, wenn Ihr Endpunkt einen Fehlercode zurückgibt? Wird die Nachricht wiederholt? Wie reagiert Ihr System auf doppelte Zustellung? Was geschieht, wenn Sie Ereignisse in anderer Reihenfolge verarbeiten? Die Sandbox ist der richtige Ort, solche Situationen bewusst herbeizuführen. Wer sie erst in der Produktion kennenlernt, lernt sie unter Druck kennen. Legen Sie einen kleinen Satz an Testfällen an und führen Sie ihn bei jeder größeren Änderung erneut aus.
Vergessen Sie die Authentizität nicht. Ihr Endpunkt sollte prüfen, dass Nachrichten tatsächlich von der Signaturstrecke stammen, wie es die Dokumentation beschreibt. Das gehört von Anfang an in den Code, nicht in eine spätere Härtungsphase, denn ein Endpunkt, der ungeprüft alles akzeptiert, ist ein Einfallstor. Auch in der Sandbox sollten Sie so arbeiten, wie Sie es in der Produktion tun werden, damit der Übergang keine Überraschungen bringt.
Den QES-Pfad vorbereiten: was zusätzlich zu klären ist
Die qualifizierte elektronische Signatur (QES) unterscheidet sich von SES und AES nicht in der Grundstruktur Ihrer Integration, wohl aber in den Beteiligten. Sign2x ist kein qualifizierter Vertrauensdiensteanbieter, und für QES arbeiten wir mit Partner-QTSPs wie Sign8 zusammen. Das heißt für Ihre Vorbereitung: Neben der technischen Anbindung müssen organisatorische und vertragliche Fragen geklärt werden, und sie brauchen oft mehr Zeit als der Code. Beginnen Sie deshalb früh damit.
Zuerst die fachliche Frage: Für welche Dokumenttypen brauchen Sie QES wirklich? Eine Hilfe zur Einordnung bietet der Beitrag AES vs QES per API. Dann die Verfahrensfrage: Welche Identifikationsverfahren sollen Ihre Nutzer verwenden, und welche sind für Ihre Zielgruppe praktikabel? Dann die Vertragsfrage: Welche Vereinbarungen sind mit Sign2x und dem Partner nötig, und wie werden Verantwortlichkeiten und Datenflüsse geregelt? Und schließlich die Betriebsfrage: Wer unterstützt Nutzer, wenn die Identifikation scheitert?
Technisch ändert sich vor allem dreierlei. Erstens wird die Stufe in der Anlage des Vorgangs gesetzt, und die Strecke enthält zusätzliche Schritte. Zweitens kommen neue Ereignisse hinzu, besonders zur Identifikation, und Ihr Zustandsmodell sollte sie abbilden. Drittens verlängert sich die Dauer: Identifikation und Zertifikatserstellung brauchen Zeit, und Nutzer unterbrechen. Ihre Oberfläche sollte Wartezustände, Erinnerungen und Wiederaufnahme unterstützen. Ob und in welcher Form ein QES-Durchlauf in der Sandbox möglich ist, besprechen Sie mit uns, weil echte Identifikationen in Testumgebungen nicht sinnvoll sind.
Rechtlich ist QES nicht für jeden Vorgang zulässig oder nötig. Prüfen Sie mit Ihrer Rechtsberatung, ob für Ihren Vorgang eine Form vorgeschrieben ist, die QES erfordert, und ob die elektronische Form überhaupt zugelassen ist. Die Grundlagen der Signaturstufen finden Sie in der eIDAS-Verordnung. Bei Geschäften mit geldwäscherechtlichem Bezug kommen Anforderungen an die Identifizierung hinzu, die wir im Beitrag GwG-konforme Signatur-API für ISVs einordnen.
Ein Pilot mit realen Nutzern ist bei QES unverzichtbar. Wählen Sie eine kleine Gruppe, etwa interne Mitarbeitende oder wohlgesinnte Kunden, und begleiten Sie sie. Beobachten Sie, wo sie zögern, wo sie abbrechen und welche Fragen sie stellen. Aus diesen Beobachtungen entstehen bessere Texte, bessere Hinweise und manchmal eine andere Reihenfolge. Rechnen Sie dafür einige Wochen ein, und erwarten Sie nicht, dass die erste Version perfekt ist. Hosting-Fragen beantwortet Sign2x mit dem Betrieb auf der Open Sovereign Cloud (OSC) von T-Systems, unter europäischem Recht, was Sie in Ihrer Dokumentation festhalten können.
Typische Stolpersteine und wie Sie sie umgehen
Aus der Begleitung von Entwicklerteams kennen wir wiederkehrende Stolpersteine. Der erste ist Dokumentenänderung nach Start: Ein Dokument wird verändert, nachdem der Vorgang begonnen hat, und die Prüfsumme stimmt nicht mehr. Lösung: Dokumente vor dem Start finalisieren und Prüfsumme speichern. Der zweite ist fehlende Referenz: Ohne eigene Kennung im Vorgang können Sie Webhooks nicht zuordnen. Lösung: Immer Ihre Referenz mitgeben, bei mandantenfähigen Systemen samt Mandantenkennung.
Der dritte Stolperstein ist Polling statt Webhooks: Aus Gewohnheit fragen Teams regelmäßig Zustände ab, statt Ereignisse zu empfangen. Das funktioniert im Test und bricht bei Volumen. Lösung: Webhooks von Anfang an einplanen, ein Abgleich als Sicherheitsnetz genügt. Der vierte ist fehlende Idempotenz: Doppelte Zustellung führt zu doppelten Folgeprozessen. Lösung: Ereignis-ID speichern, Eindeutigkeit absichern, Zustand und Historie in einer Transaktion schreiben.
Der fünfte Stolperstein ist die Vermischung von Sandbox und Produktion. Zugangsdaten werden verwechselt, Testvorgänge landen in echten Systemen oder umgekehrt. Lösung: getrennte Konfigurationen, klare Benennung, Schutzmechanismen, die Produktion in Testumgebungen verhindern. Der sechste ist unterschätzte Nutzerführung: Die Technik läuft, aber Nutzer verstehen den Ablauf nicht. Lösung: Texte testen, Schritte erklären, Hilfe bereitstellen, etwa über das Help Center.
Der siebte Stolperstein betrifft Erwartungen an Leistung und Verfügbarkeit. Wer in der Sandbox Antwortzeiten misst und daraus Produktionswerte ableitet, irrt. Testumgebungen haben andere Lastprofile. Planen Sie Lasttests für Ihren eigenen Anwendungsfall in Abstimmung mit uns, und verlassen Sie sich nicht auf pauschale Zahlen. Wir nennen keine, weil sie ohne Ihren Kontext keine Aussagekraft haben. Wenn Sie hohe Volumen planen, hilft der Beitrag Bulk-Signatur-API für Unternehmen.
Zum Schluss ein Vorgehensvorschlag für die ersten zwei Wochen. In Woche eins: Sandbox einrichten, Verbindungstest, erste Envelope, Durchlauf als Unterzeichner, Webhook-Endpunkt mit Protokollierung. In Woche zwei: Zustandsmodell, Idempotenz, erste Oberflächenintegration, Fehlerfälle, Übergabe an Fachbereich zum Test. Danach entscheiden Sie, ob und wann Sie QES und Bulk-Szenarien angehen. Wenn Sie auf dem Weg Unterstützung brauchen, nutzen Sie die Dokumentation im Developer Hub, die Fachbeiträge im Sign2x Blog, Beispiele unter Use Cases oder fragen Sie uns über Kontakt. Für eine erste Einschätzung dient außerdem das Sign2x Quiz.
Sandbox im Developer Hub starten
Weiterführend: Silent Tech: Signatur in ERP-Oberflächen und DORA Artikel 30 und der Signatur-Audit-Trail. Rechtliche Hintergründe zur Datenverarbeitung in der DSGVO.
Häufige Fragen
Wie schnell komme ich zur ersten Signatur in der Sandbox?
Mit gültigen Zugangsdaten und einem Testdokument oft innerhalb eines Nachmittags. Die genauen Schritte stehen in der Dokumentation des Developer Hub.
Brauche ich Webhooks schon für den ersten Test?
Für den ersten Durchlauf nicht, für eine echte Integration schon. Üben Sie sie früh in der Sandbox, mit Protokollierung, Idempotenz und Fehlerfällen.
Kann ich QES in der Sandbox vollständig testen?
Echte Identifikationen sind in Testumgebungen nicht sinnvoll. Welche Teile des QES-Pfads sich testen lassen, besprechen wir mit Ihnen. Sign2x ist kein QTSP, QES läuft über einen Partner wie Sign8.
Welche Signaturstufen unterstützt Sign2x?
SES, AES und QES. Starten Sie mit der einfachsten Stufe, die Ihr Vorgang rechtlich trägt, und erweitern Sie später.
Wo wird Sign2x gehostet?
Auf der Open Sovereign Cloud (OSC) von T-Systems, einem europäischen Betrieb unter europäischem Recht.
