/
sproof Sign: Die richtige Integrationsstrategie finden (API)

sproof Sign: Die richtige Integrationsstrategie finden (API)

Hallo Entwickler:in,

die nahtlose Integration von elektronischen Signaturen in Ihre bestehende Softwarelandschaft ist ein entscheidender Schritt zur Digitalisierung Ihrer Prozesse. Die sproof Sign API bietet Ihnen hierfür maximale Flexibilität – doch mit vielen Möglichkeiten stellt sich oft die Frage: Welcher Weg ist der effizienteste für mein Szenario?

Die Wahl der richtigen Strategie hängt nicht nur davon ab, wo im Dokument unterschrieben werden muss oder wer die handelnde Person ist. Ein oft unterschätzter Faktor ist das Wann:

  • Wann stehen die Empfängerdaten fest? Kennen Sie den Unterzeichner bereits während der PDF-Generierung oder erst beim Versand?

  • Wann steht das Layout fest? Ist das Dokument statisch oder wird es dynamisch erzeugt?

Möchten Sie die Logik direkt in das PDF „einbrennen“, Koordinaten programmieren oder maximale Flexibilität durch die Trennung von Dokument und Prozess erreichen?

Dieses Modul dient als Entscheidungshilfe für Ihre API-Architektur. Wir stellen Ihnen die vier gängigen Integrations-Muster vor, mit denen Sie Signaturpositionen und Empfängerlogik steuern können. Anhand Ihrer Anforderungen an Flexibilität, Dokumentenstruktur (statisch vs. dynamisch) und Compliance finden Sie hier den passenden Ansatz.

Wir unterscheiden dabei vier Hauptstrategien:

  1. Der programmatische Ansatz: Volle Kontrolle über Koordinaten (X/Y) im Code.

  2. Der eingebettete Logik-Ansatz: Das Dokument steuert den Prozess durch smarte Platzhalter.

  3. Der kombinierte Ansatz (Workflow): Trennung von Layout (Dokument) und Prozess-Logik (sproof Sign Dashboard).

  4. Der manuelle Ansatz: Der Mensch finalisiert den Entwurf vor dem Versand.

Lassen Sie uns die Methoden im Detail betrachten, damit Sie die beste Wahl für Ihr System treffen können.

https://vimeo.com/1164370246/e0baa49fd0

1. Signaturposition im Request Body (API-Payload)

„Der programmatische Ansatz“

Sie definieren die exakte Position (X/Y-Koordinaten und Seitennummer) direkt im JSON-Body der API-Anfrage beim Senden des Dokuments.

  • Funktionsweise: Die Koordinaten sind entweder fest im Code hinterlegt oder werden berechnet.

  • Beste Verwendung: Statische Dokumente (z. B. genormte Formulare), bei denen das Layout starr ist und sich nie ändert.

  • Vorteil: Das PDF-Dokument muss nicht verändert werden; es bleibt „sauber“.

  • Nachteil: Fehleranfällig bei Layout-Änderungen.

🔗 API-Dokumentation: POST /documents/signature

📘 Weiterführender Artikel:

 

2. Signaturposition durch "Smarte" Text-Platzhalter

„Der eingebettete Logik-Ansatz“

Sie betten die Empfängerdaten und die Position direkt als spezifischen Text-String in das Dokument ein. sproof Sign scannt das PDF, liest diesen String aus, erstellt den Empfänger automatisch und ersetzt den Text durch das Unterschriftenfeld.

  • Funktionsweise: Im PDF wird ein String in einer definierten Syntax platziert. Beim API-Aufruf (Create Signature Request) muss das Flag usePlaceholders auf true gesetzt werden.

  • Syntax: {sproof{first_name, last_name, email_address, signing_order, [optional] doNotSendEmail}sproof}

  • Beispiel: {sproof{Max, Mustermann, max@beispiel.at, 1}sproof}

  • Besonderheit: Das Dokument selbst bringt die „Intelligenz“ für das Routing mit. Der Text wird oft weiß (unsichtbar) formatiert. Wenn ein solches Dokument im sproof Sign Interface geöffnet wird, werden die Empfänger bereits in einem Dialog angezeigt und können mit einem Klick eingeladen werden.

  • Beste Verwendung: Dynamische Dokumente aus Drittsystemen (CRM/ERP), bei denen die Empfängerlogik direkt im generierten PDF verankert sein soll.

🔗 API-Dokumentation:

 

3. Signaturposition durch Workflow-Platzhalter

„Der kombinierte Ansatz“

Bei diesem Verfahren nutzen Sie eine strikte Arbeitsteilung: Die Position der Unterschrift wird im Dokument markiert, während die Einstellungen des Einladeprozesses und der Empfänger (z. B. Signaturgüte oder Signaturreihenfolgen) zentral im Workflow verwaltet werden.

  • Funktionsweise:

    • Position (im Dokument): Die Definition, wo unterschrieben wird, erfolgt ausschließlich im PDF selbst. Sie platzieren dort eine eindeutige Textzeichenfolge (Text-Anker, z. B. {{signer1}}). Der Workflow im Dashboard hat keine Informationen über die Position.

    • Regelwerk (im Workflow): Im sproof Dashboard definieren Sie lediglich die logischen „Personen-Platzhalter“ mit ihren Einstellungen (z. B. „Muss qualifiziert unterschreiben“, „Ist an zweiter Stelle dran“). Diesen Platzhaltern wird ein Index (z. B. 1) zugewiesen.

    • Verknüpfung (via API): Beim Versand „mergen“ Sie diese beiden Welten. Sie senden den Empfänger (E-Mail) und sagen der API: „Nimm die Position von Text-Anker {{signer1}} und wende die Regeln von Workflow-Index 1 an.“

  • Strategischer Vorteil: Sie trennen das visuelle Layout von der Compliance-Logik. Wenn sich das Layout Ihres Vertrags ändert und der Text-Anker verrutscht, müssen Sie den Workflow nicht anfassen – die Unterschrift wandert automatisch mit. Gleichzeitig können Sie im Workflow zentral den Signaturstandard (z. B. von FES auf QES) ändern, ohne tausende PDF-Templates oder Ihren API-Code anfassen zu müssen.

  • Beste Verwendung: Für Prozesse, bei denen Dokumente dynamisch erstellt werden (variable Positionen), aber immer denselben strengen Compliance-Vorgaben folgen müssen (statische Regeln).

🔗 API-Dokumentation:

📘 Weiterführender Artikel: sproof Sign Einholen von Signaturen inkl. Workflow API

 

4. Signaturposition durch den Benutzer (Entwurfs-Modus)

„Der manuelle Ansatz“

Das Dokument wird über die API hochgeladen und vorbereitet, aber nicht direkt versendet.

  • Funktionsweise: Das Dokument erscheint im sproof Sign Dashboard des Users als Entwurf. Der Benutzer kann über eine editorUrl in den Editor geleitet werden, um letzte Anpassungen vorzunehmen und die Unterschriftenfelder manuell per Drag & Drop zu platzieren oder zu prüfen.

  • Beste Verwendung: Einzelfälle oder komplexe Dokumente, bei denen eine automatische Platzierung zu riskant ist und eine menschliche Prüfung (4-Augen-Prinzip) vor dem Versand erfolgen soll.

🔗 API-Dokumentation: POST /documents/prepare

📘 Weiterführender Artikel: sproof Sign Vorbereiten von Signaturanfragen API