Überblick

Die SecureSign API ermöglicht die vollständige Automatisierung von Unterschriftenprozessen – vom Hochladen eines Dokuments über das Erstellen und Versenden einer Unterschriftenmappe bis hin zum Abruf des signierten Ergebnisses. Die API basiert auf REST und kommuniziert ausschließlich über HTTPS.

SecureSign stellt zwei API-Versionen bereit:

• API v6 – aktuell, für alle Neuintegrationen empfohlen

• API v5 – wird weiterhin unterstützt, für bestehende Integrationen verfügbar

  Basis-URL: https://esign.securecloud.de/api
  Swagger UI: https://esign.securecloud.de/swagger/
  OpenAPI-Spezifikation (v6): https://esign.securecloud.de/swagger/jsons/swagger.v6.json

  ---

Grundkonzepte

Bevor Sie mit der API arbeiten, sollten Sie die folgenden Kernbegriffe kennen:

Authentifizierung

Jeder API-Aufruf erfordert einen API-Token, den Sie in SecureSign unter Einstellungen › API-Tokens und Apps erstellen. Der Token wird als HTTP-Header übergeben:

apiToken: IHR_API_TOKEN

Alternativ als Bearer-Token:

Authorization: Bearer IHR_API_TOKEN

Erstellen Sie für jede Integration einen eigenen Token. So können Sie einzelne Integrationen bei Bedarf deaktivieren, ohne andere zu beeinträchtigen.

Sicherheitshinweis: Speichern Sie API-Tokens niemals im Quellcode. Verwenden Sie Umgebungsvariablen oder ein Secret-Management-System.

v5 vs. v6

Die beiden Versionen koexistieren – der Datei-Upload läuft weiterhin über v5, während für alle anderen Operationen v6 empfohlen wird. Die zurückgegebene fileId aus v5 ist direkt in v6-Aufrufen verwendbar.

Swagger UI und API-Referenz

Alle verfügbaren Endpunkte können direkt im Browser getestet werden:

1. Öffnen Sie https://esign.securecloud.de/swagger/ .
2. Klicken Sie auf „Authorize" und geben Sie Ihren API-Token ein.
3. Wählen Sie einen Endpunkt, klicken Sie auf „Try it out" und führen Sie den Request aus.

Typische Anwendungsfälle

Unterschriftenmappe automatisiert versenden

Der häufigste Anwendungsfall: Ein Dokument wird hochgeladen und direkt als Mappe versendet – alles in zwei API-Aufrufen.

Schritt 1 – Dokument hochladen (POST /api/v5/file/upload)
Das Dokument wird als Multipart-Formular hochgeladen. Die Antwort enthält eine fileId.

Schritt 2 – Mappe erstellen und versenden (POST /api/v6/envelope/send)
Mit der fileId, den Empfängerdaten und der gewünschten Konfiguration wird die Mappe direkt versendet. Die Antwort enthält die envelopeId der neu erstellten Mappe.

{
  "Documents": [
    {
      "FileId": "IHRE_FILE_ID",
      "DocumentNumber": 0
    }
  ],
  "Name": "Arbeitsvertrag – Max Mustermann",
  "EmailConfiguration": {
    "Subject": "Bitte unterzeichnen Sie den beiliegenden Vertrag",
    "Message": "Hallo, bitte unterzeichnen Sie die beigefügte Mappe."
  },
  "ReminderConfiguration": {
    "Enabled": true,
    "FirstReminderInDays": 3,
    "ReminderResendIntervalInDays": 2,
    "BeforeExpirationInDays": 2
  },
  "ExpirationConfiguration": {
    "ExpirationInSecondsAfterSending": 1209600
  },
  "CallbackConfiguration": {
    "CallbackUrl": "https://ihr-system.de/callback/fertig",
    "StatusUpdateCallbackUrl": "https://ihr-system.de/callback/status"
  },
  "Activities": [
    {
      "Action": {
        "Sign": {
          "RecipientConfiguration": {
            "ContactInformation": {
              "Email": "[email protected]",
              "GivenName": "Max",
              "Surname": "Mustermann",
              "LanguageCode": "de"
            },
            "SendEmails": true,
            "AllowDelegation": false
          },
          "Elements": {
            "Signatures": [
              {
                "ElementId": "sig_1",
                "Required": true,
                "DocumentNumber": 0,
                "AllowedSignatureTypes": {
                  "ClickToSign": {}
                },
                "FieldDefinition": {
                  "Position": {
                    "PageNumber": 1,
                    "X": 100,
                    "Y": 700
                  },
                  "Size": {
                    "Width": 200,
                    "Height": 50
                  }
                }
              }
            ]
          }
        }
      }
    }
  ]
}

Mappe mehrstufig vorbereiten (Draft-Workflow)

Wenn die Konfiguration einer Mappe in mehreren Schritten zusammengestellt wird – z. B. weil Empfängerdaten erst zur Laufzeit bekannt sind – bietet sich der Draft-Workflow an:

POST /api/v6/draft/create    → liefert draftId
POST /api/v6/draft/update    → Konfiguration ergänzen oder anpassen
POST /api/v6/draft/send      → Mappe versenden

Ein Draft bleibt solange im System, bis er versendet oder explizit gelöscht wird.

Signierseite einbetten (Viewer-Link)

Soll der Signiervorgang direkt in eine eigene Anwendung eingebettet werden, können über /api/v6/envelope/{envelopeId}/viewerlinks direkte Links für aktive Unterzeichner abgerufen werden – ohne dass die Unterzeichner eine E-Mail erhalten müssen.

Fertige Dokumente automatisch archivieren (Callback)

Um signierte Dokumente automatisch in einem Drittsystem zu speichern, konfigurieren Sie eine Callback-URL beim Erstellen der Mappe:

"CallbackUrl": "https://ihr-system.de/callback/fertig"

SecureSign sendet einen HTTP POST an diese URL, sobald die Mappe einen Endzustand erreicht (abgeschlossen, abgelaufen, abgelehnt). Ihr Endpunkt muss mit HTTP 200 antworten – bei ausbleibendem 200 wird der Aufruf bis zu 30 Mal wiederholt.

Daneben gibt es einen StatusUpdateCallbackUrl, der bei jedem Einzelereignis innerhalb der Mappe ausgelöst wird (z. B. Öffnen, Unterschreiben, Erinnern).

Fehlerbilder

401 Unauthorized – Token fehlt oder ist ungültig

Der API-Token wurde nicht mitgegeben oder ist abgelaufen. Prüfen Sie, ob der Header korrekt gesetzt ist und der Token in SecureSign noch aktiv ist.

403 Forbidden – fehlende Berechtigung

Der Token ist gültig, aber der zugehörige Benutzer hat nicht die nötige Rolle für diese Operation. Für API-Aufrufe ist die Rolle API User erforderlich. Prüfen Sie die Rollenzuweisung unter Einstellungen › Benutzer.

400 Bad Request – ungültige Konfiguration

Die Antwort enthält einen errorCode und eine errorInfo mit Details zum Problem – z. B. fehlende Pflichtfelder, ungültige E-Mail-Adressen oder eine nicht vorhandene fileId. Lesen Sie die errorInfo aus, bevor Sie den Request erneut senden.

{
  "errorCode": "INVALID_CONFIGURATION",
  "errorInfo": "The recipient email address is missing."
}

404 Not Found – Ressource nicht gefunden

Eine referenzierte envelopeId, draftId oder fileId existiert nicht. Häufige Ursachen: falsche ID, bereits gelöschte Ressource oder falscher API-Endpunkt (v5 vs. v6).

Mappe bleibt in Status „InProgress" – Callback schlägt fehl

Wenn eine Mappe nach Abschluss aller Unterschriften dauerhaft im Status „InProgress" verbleibt, liegt meist ein Callback-Problem vor. SecureSign wartet auf eine HTTP-200-Antwort Ihres Endpunkts und versucht es bis zu 30 Mal. Prüfen Sie Ihre Callback-URL auf Erreichbarkeit und korrekte Rückgabe.

Viewer-Link ist leer – Mappe noch nicht bereit

Wenn viewerlinks einen leeren Link zurückgibt, befindet sich die Mappe noch im Status „Started" und der erste Workflow-Schritt wurde noch nicht aktiviert. Warten Sie, bis der Status auf „InProgress" wechselt, bevor Sie die Links abrufen.

Bei Fragen steht Ihnen das SecureCloud-Support-Team gerne zur Verfügung.