Für Entwickler

Die Signido API

Eine versionierte REST-API über den vollen Funktionsumfang: Dokumente hochladen, Empfänger und Felder setzen, versenden, Status verfolgen, fertiges Dokument abholen. Mit Testmodus, Idempotenz auf jedem Schreibzugriff und signierten Webhooks.

Zur Dokumentation Ein Aufruf

REST über /api/v1
Bearer-API-Schlüssel
OpenAPI-Dokument
Test- und Live-Modus getrennt

Ein Aufruf

So sieht eine Signaturanfrage aus

Drei Aufrufe: anlegen, Empfänger ergänzen, versenden. Ein Schlüssel im Authorization-Header, ein Idempotenzschlüssel je Schritt.

Anlegen → Empfänger → Versandcurl

# 1. Auftrag anlegen — das hochgeladene Dokument hängt direkt mit dran.
curl https://api.signido.de/api/v1/signature-requests \
  -H "Authorization: Bearer $SIGNIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: auftrag-4711" \
  -d '{ "title": "Rahmenvertrag 2026", "documentIds": ["doc_..."] }'

# 2. Empfänger ergänzen.
curl https://api.signido.de/api/v1/signature-requests/req_.../recipients \
  -H "Authorization: Bearer $SIGNIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: auftrag-4711-empfaenger-1" \
  -d '{ "email": "max@example.de", "firstName": "Max", "lastName": "Mustermann" }'

# 3. Versenden. Derselbe Aufruf mit demselben Schlüssel liefert dieselbe
#    Antwort und verschickt nichts ein zweites Mal.
curl https://api.signido.de/api/v1/signature-requests/req_.../send \
  -H "Authorization: Bearer $SIGNIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: auftrag-4711-versand" \
  -d '{}'

Der Idempotency-Key ist auf jedem schreibenden Aufruf zulässig — es gibt nichts pro Route zu aktivieren. Der Grund ist nicht Bequemlichkeit: Eine Verbindung kann abbrechen, nachdem der Server geschrieben hat und bevor die Antwort ankommt, und kein Client kann diesen Fall von einer Anfrage unterscheiden, die nie ankam. Ohne Schlüssel ist ein Wiederholungsversuch auf /send eine zweite Kopie derselben Vereinbarung in einem fremden Postfach.

Die vier Dinge, die man zuerst wissen will

Authentifizierung, Modi, Wiederholungen, Grenzen

API-Schlüssel: Als Authorization: Bearer. Der Schlüssel wird nach dem Anlegen einmal im Klartext gezeigt und danach nie wieder — gespeichert wird nur sein Hash. Jeder Schlüssel trägt Scopes, und ein Aufruf außerhalb seiner Scopes wird abgelehnt.
Testmodus: Ein Testschlüssel und ein Live-Schlüssel sehen getrennte Daten. Die Trennung wird beim Anlegen eines Vorgangs festgeschrieben und ist danach Teil jeder Abfrage — ein Testschlüssel kann einen Live-Vorgang nicht lesen und nicht ändern.
Idempotenz: Gleicher Schlüssel und gleicher Body: die gespeicherte Antwort wird wiederholt, mit Idempotency-Replayed: true. Gleicher Schlüssel, anderer Body: eine Ablehnung, weil ein stilles Wiederholen die falsche Frage beantworten würde.
Rate Limits: Gezählt wird pro Schlüssel und pro Organisation in einem gleitenden Fenster. X-RateLimit-Limit und X-RateLimit-Remaining stehen auf jeder Antwort, bei einer Ablehnung zusätzlich Retry-After.

Alle vier sind in der Dokumentation im Einzelnen beschrieben — mit den genauen Fehlercodes, den Formatregeln für den Idempotenzschlüssel und der vollständigen Endpunktreferenz aus dem OpenAPI-Dokument.

Ereignisse

Webhooks, die sich prüfen lassen

Signido ruft Ihre URL auf, wenn etwas passiert. Jeder Aufruf ist signiert.

Signatur prüfenTypeScript

import { verifyWebhookSignature } from '@signido/sdk';

// payload ist der ROHE Text des Bodys, nicht das wieder serialisierte
// Objekt: JSON.stringify(JSON.parse(x)) ist nicht x, und die Signatur
// wurde über x gebildet.
const result = await verifyWebhookSignature({
  payload: await request.text(),
  signatureHeader: request.headers.get('signido-signature'),
  secret: process.env.SIGNIDO_WEBHOOK_SECRET,
});

if (!result.ok) return new Response(null, { status: 400 });

Die Signatur wird über den unveränderten Rohtext des Bodys gebildet. Wer den Body erst einliest und dann neu serialisiert, prüft eine andere Zeichenfolge und bekommt eine Fehlermeldung, die aussieht wie ein falsches Geheimnis. Das SDK nimmt den Rohtext entgegen und macht diesen Fehler deshalb nicht.

Zustellung

Jede Zustellung läuft über die Warteschlange und wird bei einem Fehler mit wachsendem Abstand wiederholt.
Ziel-URLs werden gegen Anfragen ins interne Netz geprüft, bevor der erste Aufruf hinausgeht.
Jeder Versuch ist in den API-Logs sichtbar — mit Statuscode, Dauer und Antwort.

Einbetten

Die Signaturseite im eigenen Produkt

Was eingebettet werden kann, ist die Seite, auf der unterschrieben wird.

Für einen Empfänger lässt sich eine kurzlebige Sitzung erzeugen, die an genau diesen Empfänger und an genau die Herkunft gebunden ist, in der der Frame läuft. Das zugehörige JavaScript-SDK meldet die Ereignisse des Vorgangs an die einbettende Seite und prüft dabei die Herkunft in beide Richtungen. Eine Sitzung gilt einmal und läuft nach kurzer Zeit ab.

Nicht eingebettet werden kann der Editor — also das Hochladen, das Setzen der Felder und das Auslösen des Versands. Das wäre eine Sitzung mit Schreibrechten auf die gesamte Organisation und damit eine ganz andere Vertrauensstufe als „diese eine Person unterschreibt dieses eine Dokument". Diese Funktion ist nicht gebaut, und diese Seite kündigt sie nicht an. Über die API lässt sich derselbe Ablauf natürlich vollständig steuern.

Häufige Fragen

Gibt es ein SDK?

Ja, für TypeScript, samt Webhook-Prüfung und automatisch erzeugten Idempotenzschlüsseln. Für jede andere Sprache gibt es das OpenAPI-Dokument; die Endpunktreferenz wird daraus erzeugt und kann deshalb nicht von der tatsächlichen API abweichen.

Kann ich im Testmodus vollständig entwickeln?

Ja. Ein Testschlüssel durchläuft denselben Ablauf mit denselben Zuständen und denselben Webhooks. Was ein Testvorgang nicht erzeugt, ist eine rechtlich wirksame Signatur — Testergebnisse sind als solche gekennzeichnet und werden nie als echtes Signaturniveau ausgewiesen.

Was passiert, wenn mein Webhook-Endpunkt ausfällt?

Die Zustellung wird wiederholt. Weil jeder Vorgang zusätzlich über die API abfragbar ist, ist ein Webhook eine Beschleunigung und keine einzige Quelle der Wahrheit — ein Abgleich beim Start Ihres Dienstes fängt auch eine längere Störung auf.

Gibt es einen MCP-Server?

Ja — und er ist selbst ein Client dieser API. Jeder Werkzeugaufruf läuft mit dem OAuth-Token des Aufrufers durch dieselbe Rechteprüfung, dieselben Rate Limits und dieselben Protokolleinträge wie ein direkter Aufruf; einen zweiten Datenweg gibt es nicht.

Der Endpunkt ist https://mcp.signido.de/mcp. Ausgehandelt wird die Protokollrevision 2025-11-25, ältere Revisionen bis 2024-10-07 werden ebenfalls gesprochen. Die aktuelle Revision 2026-07-28 spricht dieser Stand nicht. In der Dokumentation steht dazu bislang nichts — die Angaben hier sind alles, was es öffentlich gibt.

Weiterlesen

Mit einem Testschlüssel anfangen

Konto anlegen, Testschlüssel erzeugen, ersten Vorgang auslösen — ohne dass dabei eine Mail an einen echten Empfänger geht.

Konto anlegen Dokumentation