REST-API von e-Signature.eu — elektronisches Einschreiben

1. Überblick

Mit der REST-API von e-Signature.eu sendet Ihre Anwendung elektronische Einschreiben, ohne unsere Website zu nutzen. Sie senden das PDF, eine verifizierte Absenderadresse und den Empfänger; das Dokument erhält einen qualifizierten elektronischen Zeitstempel, und der Empfänger signiert nach Prüfung seiner Identität eine Empfangsbestätigung. Sie erhalten das Ergebnis über die API oder einen Callback.

Die bisherige Basis-URL https://www.e-signature.eu/wp-json/esig/v3/regis/ bleibt gültig. Wir empfehlen, die URL von api.e-signature.eu zu verwenden.

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/regis/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 eines Einschreibens

1. Sie senden das PDF, eine verifizierte Absenderadresse und den Empfänger. Das Dokument erhält einen qualifizierten elektronischen Zeitstempel und das Guthaben wird belastet.
2. Der Empfänger erhält eine E-Mail mit zwei Links: einen, um die Empfangsbestätigung zu signieren und das Dokument zu öffnen, einen zum Ablehnen.
3. Zum Signieren bestätigt der Empfänger seine Identität mit einer der zugelassenen Methoden (itsme®, Evrotrust, OTP…).
4. Das Einschreiben wird finished (signiert), declined (abgelehnt) oder expired, wenn nach 14 Tagen nichts geschehen ist.

Ein Absender, ein Empfänger pro Einschreiben. Wie auf der Website wird alle 4 Tage automatisch eine Erinnerung gesendet (nicht einstellbar); es gibt weder manuelle Erinnerung noch Stornierung.

6. Absenderadresse

Wie auf der Website muss die Absenderadresse (sender_email) vor der Verwendung verifiziert sein:

1. Rufen Sie verifySender auf: Eine E-Mail mit einem Bestätigungslink wird an die Adresse gesendet (Antwort 202). Ist die Adresse bereits verifiziert, lautet die Antwort 200 mit "verified": true.
2. Der Inhaber der Adresse klickt auf den Link.
3. Die Adresse kann dann in request verwendet werden.

{ "email": "[email protected]", "lang": "en" }

{
  "success": true,
  "result": {
    "email": "[email protected]",
    "verified": false,
    "message": "A verification email has been sent to [email protected]. The address can be used as sender_email once the link in this email has been clicked."
  }
}

Listet die Absenderadressen Ihres Kontos mit ihrem Status auf.

{
  "success": true,
  "result": [
    {
      "email": "[email protected]",
      "verified": true
    },
    {
      "email": "[email protected]",
      "verified": false
    }
  ]
}

7. Ein Einschreiben senden

{
  "title": "Formal notice rent October",
  "lang": "en",
  "sender_email": "[email protected]",
  "recipient": {
    "firstname": "Ann",
    "lastname": "Peeters",
    "email": "[email protected]",
    "phone": "+32475111222"
  },
  "methods": [
    "itsme-qes-signature",
    "evrotrust-signature"
  ],
  "send_email": true,
  "note_html": "Please acknowledge receipt.",
  "signature_redirect": "https://www.example.com/thank-you",
  "external_reference": "INV-2026-0042",
  "metadata": {
    "customer_id": 311
  },
  "pdf_file_base64": "JVBERi0xLjcKJeLjz9MK..."
}

Kosten

Preis der teuersten Methode in methods für einen Empfänger. Wird beim Erstellen des Einschreibens belastet.

Antwort 201 Created

{
  "success": true,
  "result": {
    "type": "regis",
    "id_sign": 123,
    "doc_name": "Formal-notice-rent-October",
    "lang": "en",
    "sender_email": "[email protected]",
    "status_id": "pending",
    "date_added": "2026-10-20 11:50:00",
    "date_status": "2026-10-20 11:50:00",
    "date_expired": "2026-11-03 11:50:00",
    "timezone": "Europe/Brussels",
    "methods": [
      "itsme-qes-signature",
      "evrotrust-signature"
    ],
    "reminder": 4,
    "last_reminder": null,
    "send_email": true,
    "from_api": true,
    "credits": 1,
    "credits_balance": 41,
    "recipient": {
      "firstname": "Ann",
      "lastname": "Peeters",
      "email": "[email protected]",
      "phone": "+32475111222",
      "status": "pending",
      "signing_time": "",
      "signing_method": "",
      "verified_firstname": "",
      "verified_lastname": "",
      "signature_link": "https://www.e-signature.eu/en/sign-regis/?key=…",
      "declined_link": "https://www.e-signature.eu/en/sign-regis/?key=…"
    },
    "external_reference": "INV-2026-0042",
    "metadata": {
      "customer_id": 311
    }
  }
}

8. Das Objekt Einschreiben

Zurückgegeben von request, getRequest, modifyRecipient, delete und in den Callbacks gesendet. Das Feld "type": "regis" unterscheidet es von einer Signaturanfrage, wenn beide dieselbe Callback-URL nutzen.

9. Weitere Endpoints

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

Einschreiben auflisten

status_id (optional): pending, finished, declined oder expired. external_reference (optional): nur die Einschreiben mit dieser Referenz.

{
  "success": true,
  "result": [
    {
      "id_sign": 123,
      "status_id": "pending",
      "doc_name": "Formal-notice-rent-October",
      "date_added": "2026-10-20 11:50:00",
      "external_reference": "INV-2026-0042"
    }
  ]
}

Ein Einschreiben abrufen

Den Empfänger ändern

{ "email": "[email protected]", "phone": "+32475333444" }

Nur Einschreiben pending. Senden Sie nur die zu ändernden Felder aus firstname, lastname, email, phone. Ändert sich die E-Mail, wird der bisherige Empfänger über die Stornierung informiert und der neue Empfänger erhält das Einschreiben.

Ein Einschreiben löschen

Nur Status finished, declined oder expired. Löscht die Dateien und den Verlauf; die Antwort enthält das Einschreiben ein letztes Mal (status_id: deleted): Laden Sie die Dokumente vor dem Löschen herunter.

Den Audit-Trail herunterladen

Nicht verfügbar, solange offen. Liefert das Einschreiben mit audit_trail_base64: ein zeitgestempeltes PDF mit dem vollständigen Verlauf.

Das Guthaben abrufen

Methoden auflisten

Für Einschreiben in methods zugelassene Methoden mit dem Preis für Ihr Konto. Die Liste kann von der der Signatur-API abweichen.

{
  "success": true,
  "result": [
    {
      "id": "itsme-qes-signature",
      "label": "itsme® | QES",
      "credits": 1
    },
    {
      "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.

Nicht zugestellte E-Mails

Wird eine von e-Signature.eu an einen Unterzeichner (oder an den Empfänger eines Einschreibens) gesendete E-Mail von dessen Mailserver zurückgewiesen (unbekannte Adresse, volles Postfach, Server lehnt die Nachricht ab…), erhalten Sie den Callback signer.email_failed. Der Status der Anfrage und des Unterzeichners ändert sich nicht.

Korrigieren Sie die Adresse mit modifySigner (Signaturanfrage) oder modifyRecipient (Einschreiben): die Einladung wird an die neue Adresse gesendet, und an die fehlerhafte Adresse wird keine Stornierungs-E-Mail gesendet. Der Kontoinhaber wird zudem per E-Mail informiert, und der Unterzeichner wird im Online-Dashboard mit E-Mail nicht zugestellt markiert.

permanent: für diese Anfrage werden keine E-Mails mehr an diese Adresse gesendet (auch keine Erinnerungen), bis sie korrigiert ist. transient oder undetermined: E-Mails werden nicht blockiert; die nächste Erinnerung wird normal gesendet, und schlägt sie erneut fehl, erhalten Sie einen neuen Callback signer.email_failed.

Betroffen sind nur laufende Anfragen und Unterzeichner, die noch nicht unterschrieben haben. Mit send_email: false sendet e-Signature.eu keine E-Mails an die Unterzeichner, daher tritt dieses Ereignis nicht auf.

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.

Bei Einschreiben wird der Callback gesendet, wenn die Bestätigung signiert, abgelehnt oder abgelaufen ist, bei jeder automatischen Erinnerung und wenn der Empfänger geändert wird (auf der Website oder über die API). Der Empfänger ist signer_key 1 in changes.

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.

12. Aufbewahrung

Das zeitgestempelte Dokument und die signierte Empfangsbestätigung können 30 Tage lang über getRequest oder den Callback heruntergeladen werden. Der Audit-Trail wird für den in unserem DPA festgelegten Zeitraum aufbewahrt. Archivieren Sie die Dokumente innerhalb von 30 Tagen bei sich.