imported>TechCorner-Redaktion: Neuer Artikel: API-Schlüssel, Einreichungen per API, Webhook-Ereignisse, HMAC-Prüfung, n8n, MCP-Server

2026-10-17T00:00:00Z

Neuer Artikel: API-Schlüssel, Einreichungen per API, Webhook-Ereignisse, HMAC-Prüfung, n8n, MCP-Server

Neue Seite

{{Steckbrief
| gilt_fuer = DocuSeal 3.3.x selbst gehostet (Open Source); REST-API unter /api, Webhooks, MCP-Server; Bibliotheken für JavaScript, Python, PHP, Ruby, C#, Java und Go
| bereich = Server-Software
| dauer = erster API-Aufruf ca. 15 Minuten; Integration je nach System
| rechte = Administrator in DocuSeal; Entwickler- bzw. Admin-Zugang zum anzubindenden System
| stand = Oktober 2026
}}
'''DocuSeal per API und Webhooks automatisieren''' bedeutet, Unterschriftsprozesse direkt aus anderen Systemen zu starten und ihre Ergebnisse zurückzuschreiben: Das Personalsystem verschickt den Arbeitsvertrag, das CRM den Kundenauftrag, und sobald alle unterschrieben haben, landet das PDF automatisch in der Akte. Die selbst gehostete Open-Source-Version enthält API und Webhooks ohne Aufpreis. Diese Anleitung zeigt Authentifizierung, die wichtigsten Endpunkte, den sicheren Empfang von Webhooks, Beispiele mit n8n und den MCP-Server für KI-Assistenten.

[[Datei:DocuSeal-API.png|thumb|center|750px|DocuSeal-API und Webhooks: Anwendung wie Personal- oder CRM-System ruft die REST-API unter https://sign.firma.de/api mit dem Header X-Auth-Token auf, legt Vorlagen aus PDF, DOCX oder HTML an und erstellt Einreichungen mit Empfängern und vorausgefüllten Feldern; DocuSeal versendet die E-Mails; Webhooks melden form.viewed, form.started, form.completed, form.declined sowie submission.created, submission.completed, submission.expired an den Empfänger, signiert mit HMAC-SHA256 im Header X-Docuseal-Signature, Wiederholung bis 48 Stunden; danach signierte Dokumente abrufen und archivieren; MCP-Server für KI-Assistenten.]]

== Überblick: Schnittstellen von DocuSeal ==
{| class="wikitable"
! Baustein !! Zweck !! Einstellung in DocuSeal
|-
| '''REST-API''' || Vorlagen und Einreichungen anlegen, abfragen, archivieren; Dokumente herunterladen || ''Einstellungen › API''
|-
| '''Webhooks''' || DocuSeal meldet Ereignisse aktiv an eine URL || ''Einstellungen › Webhooks''
|-
| '''MCP-Server''' || KI-Assistenten (z. B. Claude Desktop, VS Code) suchen Vorlagen und versenden Dokumente || ''Einstellungen › MCP''
|-
| '''Eingebettetes Signieren und eingebetteter Editor''' || Formulare in eigene Webanwendungen einbauen || nur Pro
|}
Hintergrund: [[API]], [[Webhook]].

== Schritt 1: API-Schlüssel ==
# ''Einstellungen › API'' öffnen und den '''API-Schlüssel''' anzeigen bzw. kopieren.
# Den Schlüssel wie ein Administratorpasswort behandeln: Er hat alle Rechte des Kontos. Nur im Secret-Speicher der aufrufenden Anwendung ablegen, nie im Quellcode oder in Tickets.
# Bei Verdacht auf Missbrauch neu erzeugen.
Die Basisadresse der selbst gehosteten API ist <code>https://sign.firma.de/api</code> (statt <code>https://api.docuseal.com</code> in der Cloud-Dokumentation). Jeder Aufruf trägt den Header <code>X-Auth-Token</code>.

<syntaxhighlight lang="bash">
# Vorlagen auflisten
curl -s https://sign.firma.de/api/templates \
-H "X-Auth-Token: $DOCUSEAL_TOKEN"
</syntaxhighlight>

== Schritt 2: Dokument per API zur Unterschrift senden ==
<syntaxhighlight lang="bash">
curl -s -X POST https://sign.firma.de/api/submissions \
-H "X-Auth-Token: $DOCUSEAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template_id": 12,
"send_email": true,
"order": "preserved",
"submitters": [
{ "role": "Mitarbeiter", "email": "max.muster@example.de", "name": "Max Muster",
"values": { "Personalnummer": "4711", "Eintrittsdatum": "2026-11-01" } },
{ "role": "Personalabteilung", "email": "personal@firma.de" }
]
}'
</syntaxhighlight>
* <code>role</code> entspricht dem Namen der Partei in der Vorlage, <code>values</code> füllt Felder anhand ihres Namens vor.
* Mit <code>"send_email": false</code> verschickt DocuSeal keine Mail; die Antwort enthält dann die Unterschriftslinks (<code>embed_src</code>) zur eigenen Weitergabe.
* Weitere wichtige Endpunkte:
{| class="wikitable"
! Endpunkt !! Funktion
|-
| <code>GET /api/submissions</code>, <code>GET /api/submissions/{id}</code> || Einreichungen und Status abfragen
|-
| <code>GET /api/submissions/{id}/documents</code> || Links zu den signierten PDFs
|-
| <code>POST /api/submissions/pdf</code>, <code>/docx</code>, <code>/html</code> || Einreichung direkt aus einem Dokument ohne gespeicherte Vorlage
|-
| <code>POST /api/templates/pdf</code>, <code>/docx</code>, <code>/html</code> || Vorlage aus Dokument mit Feld-Tags erzeugen
|-
| <code>PUT /api/submitters/{id}</code> || Empfänger ändern, Felder vorbelegen, E-Mail erneut senden
|-
| <code>DELETE /api/submissions/{id}</code> || Einreichung archivieren
|}
* Offizielle Bibliotheken gibt es für JavaScript/TypeScript, Python, PHP, Ruby, C#, Java und Go. Die vollständige Beschreibung liegt als OpenAPI-Datei im Repository.
* Der '''Testmodus''' trennt Testvorlagen und -einreichungen vom Produktivbestand.

== Schritt 3: Webhooks einrichten ==
# ''Einstellungen › Webhooks'' öffnen, Ziel-URL eintragen (nur HTTPS) und die gewünschten Ereignisse wählen.
# Ein '''Webhook-Geheimnis''' anlegen bzw. die HMAC-Signatur aktivieren.
# Mit ''Test'' eine Beispielnachricht senden und im Zielsystem prüfen.

{| class="wikitable"
! Ereignis !! Auslöser
|-
| <code>form.viewed</code> || Empfänger öffnet das Formular zum ersten Mal
|-
| <code>form.started</code> || Empfänger beginnt mit dem Ausfüllen
|-
| <code>form.completed</code> || eine Partei hat fertig unterschrieben
|-
| <code>form.declined</code> || Empfänger lehnt ab
|-
| <code>submission.created</code>, <code>submission.completed</code>, <code>submission.expired</code>, <code>submission.archived</code> || Einreichung angelegt, von allen abgeschlossen, abgelaufen, archiviert
|-
| <code>template.created</code>, <code>template.updated</code>, <code>template.archived</code> || Änderungen an Vorlagen
|}
* Nicht beantwortete oder fehlerhafte Zustellungen (Status 4xx/5xx) wiederholt DocuSeal mehrfach innerhalb von 48 Stunden.
* Für den Abschluss eines Vorgangs mit mehreren Parteien <code>submission.completed</code> verwenden; <code>form.completed</code> kommt je Partei.

=== Webhooks prüfen (HMAC) ===
DocuSeal sendet im Header <code>X-Docuseal-Signature</code> den Wert <code>Zeitstempel.Signatur</code>. Die Signatur ist ein HMAC-SHA256 über <code>Zeitstempel + "." + Rohdaten des Body</code>. Der Empfänger sollte Nachrichten verwerfen, deren Signatur nicht passt oder deren Zeitstempel mehr als fünf Minuten abweicht:
<syntaxhighlight lang="python">
import hmac, hashlib, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
ts, _, sig = header.partition(".")
if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig)
</syntaxhighlight>
Grundlagen: [[HMAC]]. Zusätzlich kann die Webhook-URL eigene Header (z. B. ein festes Token) verlangen.

== Beispiel: Personalprozess mit n8n ==
# '''Auslöser''': Im Personalsystem wird ein neuer Mitarbeiter angelegt → n8n erhält die Daten.
# '''HTTP-Request-Knoten''' ruft <code>POST /api/submissions</code> mit Vorlage, Partei-Rollen und vorbelegten Feldern auf.
# '''Webhook-Knoten''' in n8n empfängt <code>submission.completed</code>, prüft die Signatur und lädt über die Dokument-URLs das signierte PDF samt Prüfprotokoll.
# Ablage in der digitalen Personalakte bzw. im DMS, Benachrichtigung an die Personalabteilung.
Gleiches funktioniert mit Make, Zapier oder eigenem Code. Arbeitsverträge mit Befristung brauchen trotzdem Schriftform, siehe [[DocuSeal: Elektronische Signatur – Rechtslage in Deutschland]].

== MCP-Server für KI-Assistenten ==
* Unter ''Einstellungen › MCP'' den '''MCP-Server aktivieren''' und ein Token erzeugen. DocuSeal zeigt die Konfiguration für den MCP-Client an.
* Der Assistent kann dann Vorlagen und Dokumente suchen, Vorlagen anlegen, Felder vorbelegen und Dokumente versenden.
* '''Vorsicht''': Ein KI-Assistent mit Versandrechten verschickt rechtlich relevante Dokumente. Nur für ausgewählte Benutzer freigeben, Token getrennt halten und die Funktion deaktivieren, wenn sie nicht genutzt wird – beim Deaktivieren werden alle MCP-Verbindungen sofort beendet.

== Hinweise ==
* '''Dokument-Links laufen ab''': Die Download-Links der API gelten standardmäßig 40 Minuten (<code>FILE_URLS_EXPIRE_MINUTES</code>). Dokumente sofort nach dem Webhook abholen.
* '''Firewall''': Webhooks gehen vom DocuSeal-Server aus. Ausgehende Verbindungen nur zu den bekannten Zielen erlauben.
* '''Fehlerbehandlung''': Ereignisse können mehrfach ankommen – Empfänger idempotent bauen, z. B. über die ID der Einreichung.
* Bei Integration von DocuSeal in Fachanwendungen, Portale und Workflows unterstützt Sie die [https://www.max-it.de/development/individuelle-softwareentwicklung/ individuelle Softwareentwicklung von m.a.x. it].

== Siehe auch ==
* [[DocuSeal]] – Überblick und alle Artikel der Reihe
* [[DocuSeal: Vorlagen erstellen und Dokumente zur Unterschrift senden]]
* [[DocuSeal: Absichern, Backup und Betrieb]]
* [[Webhook]]

== Links und Quellen ==
* [https://www.docuseal.com/docs/api DocuSeal API-Dokumentation]
* [https://www.max-it.de/development/individuelle-softwareentwicklung/ Individuelle Softwareentwicklung von m.a.x. it]

{{Uebermax}}
[[Kategorie:Server-Software]]

DocuSeal: API, Webhooks und Automatisierung - Versionsgeschichte

imported>TechCorner-Redaktion: Neuer Artikel: API-Schlüssel, Einreichungen per API, Webhook-Ereignisse, HMAC-Prüfung, n8n, MCP-Server