REST-API von e-Signature.eu — elektronische Signaturen (SES, AES, QES)

1. Überblick

Mit der REST-API von e-Signature.eu sendet Ihre Anwendung Dokumente zur elektronischen Signatur (einfach SES, fortgeschritten AES oder qualifiziert QES nach eIDAS), ohne unsere Website zu nutzen. Sie senden das PDF und die Unterzeichner; wir übernehmen die Identitätsprüfung, die Signatur und die Nachverfolgung; Sie erhalten das signierte Dokument über die API oder einen Callback.

Diese Dokumentation beschreibt die API v3. Sie nutzen bereits die API v2 (https://api.e-signature.eu/v2/signature/)? Siehe Changelog.

2. Authentifizierung

Ihre Zugangsdaten finden Sie unter Mein Konto > API-Signaturen, sobald Sie bei e-signature.eu angemeldet sind:

• User ID: in der URL als Parameter userid jedes Aufrufs;
• API token: im HTTP-Header x-api-key jedes Aufrufs.

curl -X GET "https://api.e-signature.eu/v3/signature/requestBalance?userid=123" \
  -H "x-api-key: YOUR_API_TOKEN"

Halten Sie Ihr Token geheim: Es gewährt über die API vollen Zugriff auf Ihr Konto. Aufrufe müssen von Ihrem Server erfolgen, nie aus einem Browser oder einer mobilen App.

3. Konventionen

Anfragen und Antworten

• Nur HTTPS. Request-Bodies sind JSON (Content-Type: application/json).
• Jede Antwort ist JSON, in einer dieser beiden Formen:

{ "success": true,  "result": { ... } }
{ "success": false, "error": "Readable error message" }

Limits

4. Guthaben

Anfragen werden mit Ihrem Prepaid-Guthaben bei e-signature.eu bezahlt. Den Preis einer Methode liefert getMethods (Ihre individuellen Preise werden berücksichtigt). Ihr Guthaben liefern requestBalance und jedes Anfrageobjekt (credits_balance).

Automatische Aufladung des Guthabens

Damit Ihnen nie das Guthaben ausgeht, kann sich Ihr Konto automatisch aufladen. Dies wird einmalig unter Mein Konto > API-Signaturen eingerichtet, nicht über die API:

1. Wählen Sie einen Schwellenwert (in Credits) und das zu bestellende Guthabenpaket.
2. Speichern Sie eine Zahlungsmethode bei unserem Zahlungsanbieter Mollie (Karte oder SEPA-Lastschrift über Bancontact, iDEAL…). Einmalig wird eine Verifizierungszahlung von 0,01 € verlangt.
3. Jedes Mal, wenn Guthaben abgebucht wird und Ihr Saldo unter den Schwellenwert fällt, wird eine Bestellung des gewählten Pakets erstellt und automatisch mit der gespeicherten Zahlungsmethode bezahlt. Die Rechnung erhalten Sie per E-Mail.

5. Ablauf einer Signaturanfrage

1. Sie erstellen die Anfrage mit dem PDF, den Unterzeichnern und den zugelassenen Signaturmethoden. Das Guthaben wird belastet.
2. Jeder Unterzeichner erhält eine E-Mail mit einem persönlichen Signaturlink (oder Sie senden den signature_link selbst, wenn send_email false ist).
3. Der Unterzeichner bestätigt seine Identität mit einer der zugelassenen Methoden (itsme®, Evrotrust, Veriff, OTP…) und signiert.
4. Wenn alle signiert haben, ist die Anfrage finished: Das signierte PDF (PAdES) ist über getRequest verfügbar und wird im Callback gesendet.

Signaturreihenfolge

Standardmäßig signieren alle Unterzeichner parallel. Um eine Reihenfolge festzulegen, setzen Sie sign_first: true bei den Unterzeichnern der ersten Gruppe: Sie werden sofort eingeladen, gegebenenfalls mehrere parallel. Die übrigen Unterzeichner werden erst eingeladen, wenn die gesamte erste Gruppe signiert hat. Höchstens zwei Gruppen.

Zwei Integrationsmodi

Fragen Sie die API nicht in Schleife ab

Rufen Sie getRequest nicht wiederholt auf, um den Status einer Anfrage zu verfolgen: Nutzen Sie die Callbacks, die bei jeder Änderung automatisch gesendet werden. Übermäßige Aufrufe lösen eine automatische Drosselung aus, die die Verarbeitung Ihrer Anfragen vorübergehend aussetzt.

6. Eine Signaturanfrage erstellen

{
  "title": "Sales agreement 2026-114",
  "lang": "en",
  "methods": [
    "itsme-qes-signature",
    "evrotrust-signature"
  ],
  "signature_place": "position_auto",
  "reminder": 3,
  "send_email": true,
  "email_notification": false,
  "note_html": "Please sign the agreement before Friday.",
  "signature_redirect": "https://www.example.com/thank-you",
  "external_reference": "QUOTE-2026-114",
  "metadata": {
    "crm_deal_id": 8812
  },
  "callback_url": "https://erp.example.com/hooks/esignature",
  "signers": [
    {
      "firstname": "Ann",
      "lastname": "Peeters",
      "email": "[email protected]",
      "phone": "+32475111222",
      "sign_first": true
    },
    {
      "firstname": "Marc",
      "lastname": "Dubois",
      "email": "[email protected]",
      "sign_first": false
    }
  ],
  "pdf_file_base64": "JVBERi0xLjcKJeLjz9MK..."
}

Signaturmethoden

Dies sind die Standardpreise: getMethods liefert die verfügbaren Methoden und die Preise für Ihr Konto. Nur eine qualifizierte elektronische Signatur (QES) ist nach der eIDAS-Verordnung einer handschriftlichen Unterschrift rechtlich gleichgestellt. otp-email-non-qualified umfasst E-Mail und SMS: Der Code wird per SMS gesendet, wenn der Unterzeichner eine phone hat, sonst per E-Mail, zum gleichen Preis.

Felder des Request-Body

Felder eines Unterzeichners

Kosten

Preis der teuersten Methode in methods × Anzahl der Unterzeichner. Das Guthaben wird beim Erstellen der Anfrage belastet. Das Guthaben von Unterzeichnern, die nicht signiert haben, wird erstattet, wenn die Anfrage storniert oder beendet wird.

Antwort 201 Created

{
  "success": true,
  "result": {
    "id_sign": 4521,
    "lang": "en",
    "doc_name": "Sales-agreement-2026-114",
    "send_email": true,
    "from_api": true,
    "signature_redirect": "https://www.example.com/thank-you",
    "status_id": "pending",
    "date_status": "2026-10-20 10:15:02",
    "last_reminder": null,
    "timezone": "Europe/Brussels",
    "credits": 2,
    "credits_balance": 38.4,
    "signers": {
      "1": {
        "firstname": "Ann",
        "lastname": "Peeters",
        "email": "[email protected]",
        "phone": "+32475111222",
        "sign_first": true,
        "status": "pending",
        "signature_link": "https://www.e-signature.eu/en/sign/?key=…"
      },
      "2": {
        "firstname": "Marc",
        "lastname": "Dubois",
        "email": "[email protected]",
        "sign_first": false,
        "status": "pending",
        "signature_link": "https://www.e-signature.eu/en/sign/?key=…"
      }
    },
    "external_reference": "QUOTE-2026-114",
    "metadata": {
      "crm_deal_id": 8812
    }
  }
}

7. Platzierung der Signaturen

position_auto (Standard)

Setzen Sie die Markierungen #SIG01, #SIG02… (auch zulässig: #SIG01#) als Text in Ihr Dokument, dort, wo jeder Unterzeichner signieren soll (#SIG01 = erster Unterzeichner des Arrays signers). Die Signatur wird oben links an der Markierung platziert. Kommt dieselbe Markierung mehrmals vor, gilt ihr erstes Vorkommen. Eine Markierung wird übersprungen, wenn ihr Signaturbereich eine bereits platzierte (oder vorhandene) Signatur überdecken würde: Der Unterzeichner erhält dann die nächste freie Markierung. Eine Markierung, die so nah am Seitenrand liegt, dass die Signatur verschoben werden muss, wird nur als letzte Möglichkeit verwendet.

Noch nicht signiertes Dokument

Enthält das Dokument keine Markierung oder fehlt die Markierung eines Unterzeichners, wird am Ende des Dokuments eine Signaturseite mit den Markierungen angefügt, und alle Signaturen werden auf dieser Seite platziert (6 Unterzeichner auf der ersten angefügten Seite, danach 10 pro weiterer Seite).

Bereits signiertes Dokument

Einem bereits elektronisch signierten PDF kann keine Seite hinzugefügt werden: Das würde die vorhandenen Signaturen ungültig machen. Mit position_auto werden die Signaturen auf den freien Markierungen platziert, also den Markierungen, deren Signaturbereich keine vorhandene Signatur überdeckt. Freie Markierungen werden den Unterzeichnern der Reihe nach zugewiesen (#SIG01, #SIG02…).

position_manual

Geben Sie für jeden Unterzeichner die Position der Signatur in Zentimetern an:

{ "lastname": "Peeters", "email": "[email protected]", "sign_page": 3, "sign_left": 2.5, "sign_bottom": 6 }

sign_left und sign_bottom geben die obere linke Ecke der Signatur an. Die Signatur wird unterhalb und rechts dieses Punkts platziert.

Die Grenzen hängen von der tatsächlichen Seitengröße und der Größe des sichtbaren Stempels ab: Die gesamte Signatur muss mindestens 2 cm von jedem Seitenrand entfernt bleiben. Sind mehrere Signaturmethoden zugelassen, gilt der größte Stempel. Liegt ein Wert außerhalb der Grenzen, nennt die Fehlermeldung den zulässigen Bereich für diese Seite.

Eine Signatur darf weder eine andere Signatur der Anfrage noch eine vorhandene Signatur überdecken, wenn das Dokument bereits signiert ist.

8. Das Objekt Signaturanfrage

Zurückgegeben von request, getRequest, cancel, skip, remind, delete und in den Callbacks gesendet.

Unterzeichner

{
  "1": {
    "firstname": "Ann",
    "lastname": "Peeters",
    "email": "[email protected]",
    "status": "signed",
    "signing_time": "2026-10-20 11:02:47",
    "signing_method": "itsme-qes-signature",
    "verified_firstname": "Ann",
    "verified_lastname": "Peeters"
  }
}

9. Weitere Endpoints

Alle Endpoints erhalten userid in der URL und x-api-key in den Headern. id_sign wird in der URL übergeben.

Anfragen auflisten

status_id (optional): pending, finished oder skipped. external_reference (optional): nur die Anfragen mit dieser Referenz.

{
  "success": true,
  "result": [
    {
      "id_sign": 4521,
      "status_id": "pending",
      "external_reference": "QUOTE-2026-114"
    },
    {
      "id_sign": 4498,
      "status_id": "finished"
    }
  ]
}

Eine Anfrage abrufen

Liefert das Objekt Signaturanfrage, mit dem signierten PDF nach Abschluss der Anfrage. Nutzen Sie zur Statusverfolgung die Callbacks statt wiederholter Aufrufe.

Eine Erinnerung senden

Sendet eine Erinnerungs-E-Mail an die Unterzeichner mit status: pending der aktuell eingeladenen Gruppe (zuerst die Gruppe sign_first). Nur für Anfragen pending. Funktioniert auch bei Anfragen mit send_email: false.

Eine Anfrage beenden (bereits geleistete Signaturen bleiben erhalten)

Möglich, wenn mindestens ein Unterzeichner signiert hat und mindestens einer nicht. Die Anfrage wird skipped, das teilweise signierte PDF ist verfügbar und das Guthaben der Nicht-Unterzeichner wird erstattet.

Eine Anfrage stornieren

Möglich, solange niemand signiert hat; um eine teilweise signierte Anfrage zu beenden, verwenden Sie skip. Die Antwort enthält die Anfrage mit status_id: cancelled; danach werden Anfrage und Dokument aus Ihrem Dashboard entfernt, die Signaturlinks funktionieren nicht mehr und das Guthaben wird erstattet.

Eine Anfrage löschen

Nur Anfragen finished oder skipped. Löscht die Dokumente und die Anfrage. Die Antwort enthält die Anfrage ein letztes Mal, mit status_id: deleted: Laden Sie das signierte PDF vor dem Löschen herunter.

Den Audit-Trail herunterladen

Nicht verfügbar, solange die Anfrage läuft (HTTP 412). Liefert das Anfrageobjekt mit audit_trail_base64: ein PDF mit dem Verlauf der Anfrage (Daten, Methoden, geprüfte Identitäten).

Das Guthaben abrufen

{ "success": true, "result": { "credits_balance": 38.4 } }

Signaturmethoden auflisten

In methods zugelassene Methoden mit dem Preis in Guthaben pro Unterzeichner für Ihr Konto. lang (optional) übersetzt die Bezeichnungen.

{
  "success": true,
  "result": [
    {
      "id": "itsme-qes-signature",
      "label": "itsme® | QES",
      "credits": 1
    },
    {
      "id": "evrotrust-signature",
      "label": "Evrotrust | QES",
      "credits": 1
    },
    {
      "id": "veriff-advanced-signature",
      "label": "Veriff | AES",
      "credits": 0.7
    },
    {
      "id": "otp-email-non-qualified",
      "label": "OTP by Email/SMS | SES",
      "credits": 0.4
    }
  ]
}

10. Callbacks (Webhooks)

Legen Sie Ihre Callback-URL unter Mein Konto > API-Signaturen fest (HTTPS, öffentlich erreichbar). Sie können zusätzlich eine callback_url pro Anfrage angeben. Der Callback ist ein POST mit einem JSON-Body, der den vollständigen aktuellen Status der Anfrage enthält (gleiches Format wie getRequest), gesendet für über die API erstellte Anfragen.

Ereignisfelder

Ereignistypen

Der Body enthält stets den vollständigen aktuellen Status: Ihre Integration kann sich auf status_id und den Status jedes Unterzeichners stützen statt nur auf den Ereignistyp.

Header

Die Signatur prüfen

Ihr Signaturgeheimnis wird unter Mein Konto > API-Signaturen angezeigt und kann dort neu erstellt werden. v1 ist der HMAC-SHA256 von "<t>.<raw request body>" mit Ihrem Geheimnis, hexadezimal kodiert. Verwenden Sie den unveränderten Body vor jedem JSON-Parsing und lehnen Sie Callbacks ab, die älter als 5 Minuten sind.

PHP

$body   = file_get_contents( 'php://input' );
$header = $_SERVER['HTTP_X_ESIG_SIGNATURE'] ?? '';
preg_match( '/t=(\d+),v1=([a-f0-9]{64})/', $header, $m );
$valid = $m
    && abs( time() - (int) $m[1] ) <= 300
    && hash_equals( hash_hmac( 'sha256', $m[1] . '.' . $body, $secret ), $m[2] );

Node.js

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

C# (.NET)

using System.Security.Cryptography; using System.Text; using System.Text.RegularExpressions;
static bool Verify(string rawBody, string header, string secret) {
    var m = Regex.Match(header ?? "", @"t=(\d+),v1=([a-f0-9]{64})");
    if (!m.Success || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(m.Groups[1].Value)) > 300) return false;
    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(m.Groups[1].Value + "." + rawBody))).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(m.Groups[2].Value));
}

Antworten und Wiederholungen

• Antworten Sie mit HTTP 2xx, sobald der Callback eingegangen ist, und verarbeiten Sie ihn bei Bedarf asynchron.
• Bei Netzwerkfehler, Zeitüberschreitung (30 s), HTTP 429 oder 5xx wird der Callback stündlich mit derselben event_id erneut gesendet, bis zu 24 Versuche. Andere 4xx-Antworten gelten als endgültig. Ändert sich die Anfrage vor einer erfolgreichen Zustellung erneut, enthält der nächste Callback ein neues Ereignis und den vollständigen aktuellen Status. Der aktuelle Status bleibt jederzeit über getRequest abrufbar.
• Weiterleitungen werden befolgt (die Methode POST bleibt erhalten). localhost und private Adressen sind nicht zulässig.

11. Fehler

Fehler werden mit "success": false und einer lesbaren Meldung error zurückgegeben. Stützen Sie Ihre Logik auf den HTTP-Code: Die Meldungen können sich ändern.

Fehler nach Endpoint

Validierungsmeldungen bei der Erstellung (request, HTTP 400)

Die Meldung nennt das Feld oder das Problem; … steht für einen Wert Ihrer Anfrage. Stützen Sie Ihren Code auf den HTTP-Code und zeigen Sie die Meldung an, um die Anfrage zu korrigieren.

12. Aufbewahrung

Signierte Dokumente können 30 Tage nach Abschluss über getRequest oder den Callback request.completed heruntergeladen werden. Der Audit-Trail wird für den in unserem DPA festgelegten Zeitraum aufbewahrt. Archivieren Sie das signierte Dokument und den Audit-Trail innerhalb von 30 Tagen bei sich.

13. Changelog

API v3 — Unterschiede zur API v2

Die API v2 (https://api.e-signature.eu/v2/signature/) bleibt verfügbar und unverändert. Endpoints, Parameter und Authentifizierung sind in beiden Versionen identisch: Um auf die API v3 umzustellen, ersetzen Sie die Basis-URL durch https://api.e-signature.eu/v3/signature/. Sie können Endpoint für Endpoint umstellen.

Die bisherigen URLs (https://www.e-signature.eu/wp-json/signature/ für API v2 und https://www.e-signature.eu/wp-json/esig/v3/signature/ für API v3) bleiben gültig. Wir empfehlen, die URLs von api.e-signature.eu zu verwenden.

Callbacks folgen der Version, mit der die Anfrage erstellt wurde: Eine mit der API v2 erstellte Anfrage erhält weiterhin Callbacks der API v2.