Zum Hauptinhalt springen

Schnellstart-Tutorial

Tipp

Verwenden Sie Cursor, Claude oder ein anderes KI-Codierwerkzeug? Verbinden Sie es mit den Legalesign-Dokumenten für kontextbezogene Hilfe, während Sie dieses Tutorial durchlaufen.

In diesem Tutorial führen Sie die wichtigsten API-Aufrufe durch, die die meisten Entwickler für eine eSignatur-Integration benötigen – ein Dokument hochladen und zum Unterschreiben versenden.

Die Legalesign-API ist skalierbar, vielseitig und seit vielen Jahren in den Systemen unserer Kunden im Produktionseinsatz getestet. Sie können sie für ein einfaches Dokument mit einem Unterzeichner nutzen oder Dokumente zum Beglaubigen oder zur Genehmigung versenden, optimiert für Stapel, mit Formularen und mehr. Sie können sie für einen einzigen Zweck integrieren oder in Ihre Software für Ihre Kunden einbetten – siehe Integrationen.

Die REST-API erledigt die meisten Funktionen und ist der einfachste Start. Wenn Sie mehr benötigen, sehen Sie sich die GraphQL-Schnittstelle an. Legalesign ist API-first mit GraphQL. Sie können je nach Vorliebe eine der beiden nutzen.

Wir folgen diesen Schritten:

  1. Konto + API-Schlüssel erstellen (siehe Erlangen der Verifizierung für API-Zugriff).
  2. Anmeldeinformationen prüfen und Ihre Team-ID erhalten.
  3. Ein Dokument über die Web-App hochladen.
  4. Dieses per API zum Unterschreiben senden.
  5. Nach dem Unterzeichnen herunterladen.
  6. Ein Dokument per API hochladen.

Die Legalesign REST API ist leicht zu verwenden. Das technische Referenzdokument enthält einen Code-Editor. Sie können Anfragen direkt aus dem technischen Referenzdokument mit Ihrem API-Schlüssel stellen, ansonsten einfach in Ihren Code kopieren und einfügen.

Code Generator Image Abbildung 1: Der Code-Editor der REST API.

Client-Bibliotheken

Oder für die GraphQL-Schnittstelle Node.js

Tipp

Wir empfehlen Entwicklern, direkt mit der API statt mit den SDKs zu arbeiten. Zur Unterstützung gibt es einen Code-Generator zum Kopieren und Einfügen in der technischen Spezifikation, und Ihre KI kann schnell Beispiele mit der OpenAPI-Spezifikation erzeugen. Warum? Die Quell-API bietet mehr Funktionalität als SDKs, Sie wollen sowieso die Endpunkte kennen, die Sie nutzen, vermeiden Abstraktions-Overhead und Abhängigkeiten und – basierend auf unserer Erfahrung – geht es schneller.

1. Konto erstellen

Gehen Sie zu legalesign sign up und folgen Sie dem Prozess zur Kontoerstellung.

Sie werden gebeten, ein Team zu erstellen. Teams sind die Bausteine von Legalesign. Alle Dokumentenprozesse finden in einem Team statt. Sie müssen in den meisten API-Aufrufen auf Ihr Team verweisen.

Info

Ein „Team“ und eine „Gruppe“ sind dasselbe. In der Web-App sprechen wir von „Teams“, im API-Schema von einer Gruppe.

API-Einstellungen

Gehen Sie zum API-Dashboard. Generieren Sie Ihre API-Zugangsdaten im Bereich API-Schlüssel.

Nehmen Sie sich einen Moment Zeit, um das Entwicklerportal zu erkunden.

Sandbox

Im Bereich Umgebung zeigt eine Warnung an, ob Sie sich im Sandbox- oder Produktionsmodus befinden.

Sandbox beschränkt, wohin Sie Ihre Dokumente senden können. Sie sehen ein Formular, um bis zu 5 genehmigte E-Mails hinzuzufügen – fügen Sie jetzt einige hinzu.

Wenn Ihre Integration bereit ist: in den Produktionsmodus wechseln.

Tipp

Erstellen Sie ein zweites Team. Verwenden Sie Ihr erstes Team für die Entwicklung und andere Teams für die Produktion. Teilen Sie dem Support den Namen Ihres Entwicklungsteams mit, um die Abrechnung auszuschließen.

API-Schlüssel

Im API-Schlüssel-Bereich sehen Sie die Details Ihrer API-Schlüssel. Der Schlüssel selbst wird nur beim Erstellen angezeigt.

Der Schnellstart-Bereich enthält Beispiele zum Kopieren und Einfügen, um Ihren Schlüssel zu testen.

API Key Section Screenshot

Webhooks & Protokolle

Fügen Sie Webhooks hinzu (Ihre Listener für Legalesign-Ereignisse) und überprüfen Sie Ihre Protokolle.

Webhooks Section Screenshot

2. Eine erfolgreiche GET-Anfrage

Die Root-URL ist immer: https://eu-api.legalesign.com/

Beginnen Sie mit einer GET-Anfrage, um Ihre Zugangsdaten zu bestätigen. Ersetzen Sie Benutzername und Geheimniswerte im untenstehenden Code.

Curl wird in den Beispielen verwendet, und Sie können unten zwischen cURL, Node.js, Python, C# und Go mittels Tabs wechseln.

curl -H "Authorization: ApiKey username:secret" -H "Content-Type: application/json" -X GET https://eu-api.legalesign.com/api/v1/group/

API-Dokumentation: GET group API Referenz.

Wenn Sie die obige Abfrage ausführen, sehen Sie Ihre Gruppen als JSON zurückgegeben. Erfolg. 👏

Die Antwortdaten enthalten die 'resource uri' für Ihre Gruppe im Format /api/v1/group/:groupId/. Merken Sie sich diese, Sie benötigen sie für die meisten API-Aufrufe.

Tipp

Eine resource uri hat immer dasselbe Format. Für ein PDF wäre es '/api/v1/templatepdf/:pdfId/', für ein gesendetes Dokument '/api/v1/document/:documentId/'. Beachten Sie, dass alle URIs mit einem Schrägstrich enden. Das gilt auch für Ihre API-Aufruf-URLs, diese immer mit einem Slash abschließen.

Wenn die GET-Anfrage fehlgeschlagen ist, überprüfen Sie:

  • ob Ihr ApiKey korrekt formatiert ist (beginnt mit 'ApiKey'),
  • ob Sie einen Content-Type Header für application/json haben, und
  • ob Ihre URL mit einem Schrägstrich endet.

Siehe auch Fehlerbehebung.

3. Dokument über die Web-App hochladen

Um zu starten, laden wir ein Dokument über die Web-App hoch und senden es dann per API. Später behandeln wir, wie man ein Dokument per API hochlädt.

Gehen Sie in die Web-App und laden Sie Ihr Dokument hoch. Fügen Sie eine einzelne Unterzeichnerrolle hinzu und ziehen Sie ein Unterschriftsfeld darauf. Die Editor-Seite zeigt an, ob das Dokument „gültig“ ist (ein Beispiel für „ungültig“ wäre eine Unterzeichnerrolle ohne zugehöriges Unterschriftsfeld).

Kopieren Sie im Formular-Editor die lange alphanumerische ID aus der URL, decodieren Sie sie base64 und entfernen Sie die ersten 3 Buchstaben (sollten 'tpl' sein). Der Rest ist eine UUID und Ihre ID.

In REST-API Sprache ist die resource uri dieses Dokuments /api/v1/templatepdf/UUID/.

Erfahren Sie mehr über Web- und API-IDs.

Unsere Nomenklatur besagt, dass ein hochgeladenes Dokument eine „Vorlage“ (template) ist und wenn Sie eine senden, erstellen Sie ein „Dokument“.

Tipp

Wenn Sie eine Vorlage archivieren möchten, sobald das Dokument versendet wird, setzen Sie 'archive_upon_send' als Attribut im Upload-Request. Wenn die Vorlage nie erscheinen und nach dem Versenden gelöscht werden soll, geben Sie ihr den Titel '[deleted]' – unsere Bereinigungssysteme erkennen das und löschen sie nach ein bis zwei Tagen. Sie können auch kurze Aufbewahrungszeiten auf Gruppenebene einstellen – mehr dazu.

4. Dokument zum Unterschreiben senden

Jetzt senden wir dies über die API. Denken Sie daran, eine E-Mail aus Ihren im Sandbox genehmigten E-Mails zu verwenden. Verwenden Sie die Tabs unten, um den Request in Ihrer bevorzugten Sprache zu übernehmen.

curl -H "Authorization: ApiKey [username]:[secret]" -H "Content-Type: application/json" -X POST --data '{ "group": "/api/v1/group/[:groupId]/", "name": "Name of doc", "templatepdf": "/api/v1/templatepdf/UUID/", "signers": [{"firstname": "Joe", "lastname": "Bloggs", "email": "[your@email.com]", "order": 0 }], "do_email": true }' https://eu-api.legalesign.com/api/v1/document/

Aktualisieren Sie alle eckigen Klammern. API-Referenz zum Senden eines Dokuments.

Tipp

Wenn Sie die Referenzdokumentation zum Senden eines Dokuments besuchen, sehen Sie sich alle möglichen Attribute genau an. Viele helfen beim praktischen Einsatz der Integration – Tags für Ihre eigenen Verweise und IDs (die Sie in Webhooks zurückerhalten), eine Umleitung für Unterzeichner, benutzerdefinierte Texte im PDF und mehr.

Ein erfolgreicher Aufruf liefert den Statuscode 201.

Neue gesendete Dokument-ID abrufen

Der wichtige Teil der Antwort ist der Location-Header. Dieser enthält Ihre neue Dokument-ID.

Tipp

Verwenden Sie die Dokument-„Tag“-Attribute und fügen Sie Ihre eigenen Referenzen hinzu, um die Verknüpfung mit Ihrer Datenbank zu erleichtern.

Der Location-Header sieht aus wie /api/v1/status/:documentId/.

Die 'Status'-URI gibt eine kurze (und schnell abfragbare) Menge von Dokumentattributen zurück.

Um alles von einem Dokument anzufordern, verwenden Sie /api/v1/document/:documentId/.

Info

Wenn eine Anfrage fehlschlägt, enthält der BODY der Antwort meist Fehlerinformationen. Wenn Sie keinen Erfolg erhalten, prüfen Sie den BODY auf erklärende Texte. Siehe auch Fehlerbehebung.

Mehr zur Send Document API.

5. Das unterschriebene Dokument herunterladen

Mit der oben erhaltenen gesendeten Dokument-ID führen Sie eine PDF-Download-Anfrage in Ihrer bevorzugten Sprache aus:

curl -H "Authorization: ApiKey [username]:[secret]" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/

PDF Download API Referenz.

Der PDF-Binärinhalt ist im Antwort-Body enthalten. Der curl-Befehl '-o' speichert den BODY direkt in eine Datei.

Viele REST- oder HTTP-Bibliotheken behandeln HTTP-Antwortobjekte wie Dateien, speichern Sie dann einfach Ihr Antwortobjekt normal als Datei.

Tipp

Verwenden Sie Webhooks, um über ein Unterschriftsereignis benachrichtigt zu werden und laden Sie dann das Dokument herunter. Siehe Webhooks.

6. PDF hochladen

Klicken Sie hier, um ein Beispiel für ein text-getaggtes PDF herunterzuladen, mehr zu PDF-Formularfeldern folgt.

Für diesen Aufruf konvertieren Sie Ihr PDF in einen base64-codierten String. Das wird in der Dokumentations-Code-Generator nicht richtig gemacht. Kopieren Sie stattdessen diesen Pseudocode, und Ihre freundliche KI konvertiert ihn in Ihre bevorzugte Sprache:

$data = (
'group': '/api/v1/group/:groupId/',
'title': 'title of pdf',
'pdf_file': base64encode(open('/path/to/file','rb')),
'process_tags': true
)
$headers = (
'Authorization': 'ApiKey username:secret',
'Content-Type': 'application/json'
)
response = httplibrary.post('https://eu-api.legalesign.com/api/v1/templatepdf/', jsonEncode($data), $headers)
assert response.status == 201

pdfId = response.headers['location']

PDF Upload API Referenz.

Wie üblich wird eine erfolgreiche POST-Antwort den Status 201 zurückgeben und die neue ID im 'location' Header der Antwort enthalten.

assert response.status == 201
pdfId = response.headers['location']

Ihre pdf resource URI sieht so aus: /api/v1/templatepdf/:pdfId/.

Das neue PDF senden

Gehen Sie zurück zu dem Code, mit dem Sie Ihr erstes Dokument gesendet haben, und ersetzen Sie den templatepdf-Wert.

Senden Sie die Anfrage erneut – und fertig, Sie haben Ihr PDF zum Unterschreiben versendet.

Bevor Sie mit dem Programmieren beginnen, lesen Sie jedoch weiter, um mehr über PDF-Felder zu erfahren.

Was ist mit PDF-Feldern?

Wie weiß Legalesign, wo die Person im PDF unterschreiben muss oder welche Bereiche sich beim Senden ändern? Die Antwort ist, dass unser PDF vorab mit Tags vorbereitet wurde: Wir haben ein Legalesign-Text-Tag ins PDF gesetzt und 'process_tags' im PDF-Upload-Aufruf auf true gesetzt.

Beispiel für ein text-getaggtes PDF herunterladen.

Text-Tags sind speziell formatiertem Text, der in ein PDF eingefügt wird. Legalesign erkennt den Text in Ihrer Datei und ersetzt die Tags durch Unterschrifts- und Formularfelder. Für einen Unterzeichner genügt es, <<t=signature>> hinzuzufügen. Legalesign identifiziert dies und positioniert die Unterschrift dort. Mehr zu Text-Tags.

Text-Tags haben eine Lernkurve und erfordern Ausprobieren. Andere Methoden sind unten aufgeführt, aber mit Tags erhalten Sie die volle Funktionalität des Legalesign-Formularsystems. Testen Sie Tags mit der Web-App. Kontaktieren Sie Support für Hilfe und Beispiele.

Hier sind 4 weitere Möglichkeiten, Felder einzurichten:

1. Einfachste/schnellste Variante. Richten Sie Ihr PDF in der Legalesign-Web-App ein.

Nachdem Sie ein PDF hochgeladen haben, gehen Sie zum Editor, wo Sie Formularfelder per Drag & Drop hinzufügen können.

Ziehen Sie eine Unterschrift hinzu und merken Sie sich die kodierte ID in der Webadresse. Diese sieht etwa so aus: 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.

Decodieren Sie diese ID base64, dann sehen Sie eine UUID mit dem Präfix 'tpl'. Der UUID-Teil (ohne 'tpl') ist Ihre pdfID. Mehr zu Legalesign-IDs.

Ihre API-PDF-Resource-URI ist /api/v1/templatepdf/:pdfId/.

Setzen Sie diese in das Attribut 'templatepdf' des Send Document-Aufrufs ein.

Info

Wenn Sie dieses PDF mehrmals senden möchten, stellen Sie sicher, dass „Auto-Archivierung“ ausgeschaltet ist. Hier erfahren Sie wie

2. Verwenden Sie x/y-Koordinaten für Felder.

Der einfachste Einstieg mit x/y-Koordinaten ist, ein PDF in der Web-App einzurichten und dann per API die Felder abzufragen (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).

Das JSON-Objekt, das Sie zurückbekommen, ist das gleiche JSON-Schema, das Sie zum Erstellen von Feldern verwenden.

Nutzen Sie es als Vorlage, ändern Sie Werte ab und schicken Sie es mittels POST zurück an denselben Endpunkt (mit passender PDF-ID). Create PDF Field Endpunkt.

3. Betten Sie unsere PDF-Bearbeitungsseite ein. NEU!

Nutzen Sie unsere Editor-Komponente, um unseren PDF-Editor direkt in Ihre eigene App einzubetten. Mehr zum Dokumenten-Editor.

4. PDF-Formularfelder NEU!

Wenn Ihr PDF normale PDF-Formularfelder enthält, kann Legalesign diese automatisch importieren.

Viel Erfolg beim Programmieren!

In diesem Tutorial haben Sie API-Zugangsdaten erhalten, erfolgreich nach Ihrer Gruppe(n) abgefragt, ein Dokument für das Unterschreiben mit HTML und PDF versendet und ein unterschriebenes Dokument heruntergeladen.

Viel Erfolg beim Programmieren! Wir sind hier, um zu helfen, kontaktieren Sie Support bei Fragen.

Tipp

Schön, dass Sie bis zum Ende gelesen haben – danke dafür. Unser letzter Tipp, basierend auf jahrelanger Erfahrung mit Entwicklern, die diese API integrieren, ist: Nehmen Sie sich einen Moment Zeit, um alle Attribute des Create Document-Endpunkts durchzusehen (und klicken Sie sich durch die Inhalte von ‚signers‘, ‚pdftext‘ und ‚signertext‘) – das ist der wichtigste Aufruf in Ihrer Integration. Ein Signaturdokument erstellen.

Nächste Schritte: