Dokumente erstellen und signieren mit der eSignBase REST API

Dokumente erstellen und signieren mit der eSignBase REST API

In diesem Guide zeigen wir Ihnen, wie Sie mit der eSignBase REST API eine Signaturanfrage auf Basis einer bestehenden Dokumentenvorlage erstellen und versenden.

Dieser Leitfaden konzentriert sich auf den End-to-End-Workflow:

  1. Vorbereiten einer Dokumentenvorlage
  2. Authentifizierung bei der REST API
  3. Erstellen einer Signaturanfrage aus der Vorlage

Die vollständige API-Referenz finden Sie hier: https://app.esignbase.com/api_documentation

Dokumenten-Credits & Sandbox-Modus

Das Erstellen einer Signaturanfrage in eSignBase erfordert normalerweise ein Dokumenten-Credit. Jedes Credit deckt einen vollständigen Signatur-Workflow ab, einschließlich der Versiegelung des Dokuments und der Erstellung des Prüfprotokolls (Audit Trail).

Sandbox-Modus (Kostenloses Testen)

Für die Entwicklung und Integrationstests bietet eSignBase einen Sandbox-Modus an, der keine Credits verbraucht. Dies ermöglicht es Ihnen:

  • die gesamte REST API zu testen
  • Signaturanfragen zu erstellen und zu versenden
  • End-to-End-Workflows zu validieren und Integrationen ohne Auswirkungen auf die Abrechnung zu debuggen.

Hinweis: Sandbox-Dokumente sind nicht für den rechtlichen Gebrauch bestimmt. Sie enthalten keine AES-Signatur und werden nur an die E-Mail-Adresse des eSignBase-Kontos gesendet.

Voraussetzungen: Vorbereiten einer Dokumentenvorlage

Bevor Sie eine Signaturanfrage über die REST API auslösen können, muss bereits eine Dokumentenvorlage in Ihrem eSignBase-Konto existieren.

PDF hochladen

Öffnen Sie die eSignBase Web-Anwendung und laden Sie eine PDF-Datei hoch, die als Vorlage für Signaturanfragen dienen soll. Profi-Tipp: Wenn Sie im Sandbox-Modus testen möchten, stellen Sie sicher, dass Sie vor dem Hochladen den Schalter auf „Sandbox“ umlegen.

Screenshot PDF hochladen

Signaturfelder hinzufügen

Öffnen Sie nach dem Hochladen den Vorlagen-Editor und fügen Sie mindestens ein Signaturfeld hinzu. Ziehen Sie das Feld per Drag-and-Drop aus der Palette auf das Dokument. Sie können auch weitere Formularfelder (Textfelder, Checkboxen, Daten usw.) hinzufügen, je nachdem, welche Informationen der Unterzeichner angeben soll.

Screenshot Drag-and-Drop Signaturfeld

Der Vorlagen-Editor speichert Ihre Änderungen automatisch. Die Vorlage kann für mehrere Signaturanfragen über die REST API wiederverwendet werden.

API-Authentifizierung

Um zu starten, benötigen Sie eine OAuth Client ID und ein Client Secret.

  1. Öffnen Sie die API-Konfigurationsseite
  2. Erstellen Sie einen neuen OAuth-Client
  3. Speichern Sie die generierte Client ID und das Client Secret sicher ab

Diese Anmeldedaten sind erforderlich, um ein Access Token anzufordern.

Erhalt eines Access Tokens

Um API-Anfragen zu authentifizieren, müssen Sie ein OAuth Access Token anfordern. Access Tokens sind zeitlich begrenzt und müssen nach Ablauf erneuert werden.

Senden Sie eine POST-Anfrage an: https://app.esignbase.com/oauth2/token

Erforderliche Header:

Authorization: Basic <basic_auth_credentials>
Content-Type: application/x-www-form-urlencoded

Wobei: basic_auth_credentials = base64(client_id + ":" + client_secret)

Unterstützte Grant Types Die eSignBase API unterstützt die folgenden OAuth 2.0 Grant Types:

  • client_credentials (empfohlen für Server-zu-Server-Kommunikation)
  • password (Resource Owner Password Credentials)

Beispiel: Password Grant (curl)

Das folgende Beispiel zeigt, wie Sie ein Access Token mit dem Grant Type password erhalten:

curl -X POST 'https://app.esignbase.com/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<IHRE_CLIENT_ID>' \
  -d 'client_secret=<IHRE_CLIENT_SECRET>' \
  -d 'grant_type=password' \
  -d 'scope=sandbox all' \
  -d 'username=user@example.com' \
  -d 'password=<IHR_PASSWORT>'

Ihre Token-Anfrage muss den Scope scope=sandbox all enthalten, wenn Sie den Sandbox-Modus nutzen möchten, andernfalls verwenden Sie scope=all.

Client Credentials Grant (Passwortlos)

Für die passwortlose Authentifizierung (empfohlen für Backend-Dienste) verwenden Sie: grant_type=client_credentials. In diesem Fall muss der Authorization-Header die Base64-kodierten Client-Zugangsdaten enthalten; Benutzer-Anmeldedaten sind nicht erforderlich.

Token-Antwort

Wenn die Anfrage erfolgreich ist, antwortet die API mit einem JSON-Payload, der das Access Token enthält:

{ "access_token": "<ihr_access_token>" }

Dieses access_token muss als Bearer-Token im Authorization-Header aller nachfolgenden API-Anfragen enthalten sein.

Erstellen einer Signaturanfrage aus einer Vorlage

Sobald Sie ein gültiges OAuth 2.0 Access Token und eine vorbereitete Vorlage haben, können Sie über die eSignBase REST API eine neue Signaturanfrage erstellen. Dieser Vorgang nutzt die vorhandene Vorlage, weist den darin definierten Rollen Empfänger zu und startet den Signatur-Workflow.

Die Vorlage verstehen

Vorlagen in eSignBase können eine oder mehrere Formular-Rollen enthalten (definiert in der Web-UI). Jeder Formular-Rolle (z. B. „signer_1“) muss ein entsprechendes Empfänger-Objekt in Ihrer Anfrage zugeordnet werden.

Sie können alle Vorlagen auflisten, um die gewünschte ID zu finden:

GET /api/templates
Authorization: Bearer <ihr_access_token>

Die Antwort enthält Felder wie id, filename und form_role_names. Sie benötigen die id der Vorlage im nächsten Schritt.

Die Dokumentenerstellungs-Anfrage ausführen

Um ein neues Dokument basierend auf einer Vorlage zu erstellen, senden Sie eine POST-Anfrage an den Endpunkt /api/document mit dem entsprechenden JSON-Body:

POST /api/document
Authorization: Bearer <ihr_access_token>
Content-Type: application/json

Beispiel für den Request-Body

Hier ist ein Beispiel-Payload, der:

  • die Vorlagen-ID referenziert
  • einen Empfänger der erforderlichen Rolle zuweist
  • optional Metadaten und Ablauf-Einstellungen enthält
{
  "name": "Arbeitsvertrag",
  "template_id": "ihre_template_id_hier",
  "recipients": [
    {
      "email": "signer@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "role_name": "signer_1",
      "locale": "de"
    }
  ],
  "user_defined_metadata": {
    "internal_id": "42",
    "purpose": "contract-signing-test"
  },
  "expiration_date": "2026-03-15T23:59:00+00:00"
}

Feld-Highlights:

  • name — Eine Bezeichnung für die Signaturanfrage. Dieser Name wird auch in der E-Mail an den Unterzeichner verwendet.
  • template_id — Die UUID der Vorlage, die Sie zuvor erstellt haben.
  • recipients — Ein Array von Empfänger-Definitionen, die mit den form_role_names der Vorlage übereinstimmen.
  • user_defined_metadata — (Optional) Key-Value-Daten für Ihr internes Tracking.
  • expiration_date — (Optional) Zeitpunkt, an dem die Anfrage abläuft.

Beispiel mit curl

Hier ist ein vollständiges Beispiel mit curl:

curl -X POST "https://app.esignbase.com/api/document" \
  -H "Authorization: Bearer <IHR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Arbeitsvertrag",
    "template_id": "<IHRE_TEMPLATE_ID>",
    "recipients": [
      {
        "email": "signer@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "role_name": "signer_1",
        "locale": "de"
      }
    ],
    "user_defined_metadata": {
      "internal_id": "42",
      "purpose": "contract-signing-test"
    },
    "expiration_date": "2026-03-15T23:59:00+00:00"
  }'

Was als Nächstes passiert

Eine erfolgreiche Anfrage gibt eine JSON-Antwort mit der neuen document_id und dem initialen Status zurück (normalerweise „DRAFT“):

{
  "document_id": "neue_doc_id",
  "status": "DRAFT"
}

An diesem Punkt:

  • Das Dokument existiert und ist bereit.
  • eSignBase versendet automatisch E-Mails zur Unterzeichnung an die Empfänger.
  • Sie können andere Endpunkte nutzen, um den Status abzufragen oder das final signierte PDF herunterzuladen, sobald es fertig ist.

Hinweise & Tipps

  • Sprachunterstützung (Locale): Das Feld locale bestimmt die Sprache der Benachrichtigungen. Unterstützte Codes sind u.a. en, de und es.
  • Ablauf (Expiration): Dokumente, deren expiration_date vor der Fertigstellung erreicht wird, wechseln automatisch in den Status VOIDED.
  • Metadaten: Nutzen Sie user_defined_metadata, um interne Geschäfts-IDs oder Tracking-Werte anzuhängen.

Ihre nächsten Schritte umfassen üblicherweise:

  • Den Dokumentenstatus prüfen (mit GET /api/document/<id>)
  • Webhooks für Abschluss-Benachrichtigungen verarbeiten
  • Das signierte PDF herunterladen, sobald es verfügbar ist