Zum Hauptinhalt springen

Schnellstart-Tutorial

Tipp

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

In diesem Tutorial werden Sie die wichtigsten API-Aufrufe abschließen, die die meisten Entwickler für eine eSignature-Integration benötigen – ein Dokument hochladen und zum Signieren versenden.

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

Die REST-API führt die meisten Funktionen aus und ist der einfachste Einstieg. Wenn Sie mehr benötigen, schauen Sie sich die GraphQL-Schnittstelle an. Legalesign ist API-first mit GraphQL. Sie können je nach Vorliebe eine der beiden verwenden.

Wir folgen diesen Schritten:

  1. Ein Konto + API-Schlüssel erstellen (siehe Für den API-Zugriff verifizieren lassen).
  2. Bestätigen, dass die Anmeldedaten funktionieren, und Ihre Team-ID erhalten.
  3. Ein Dokument über die Web-App hochladen.
  4. Dieses über die API zum Signieren versenden.
  5. Es nach dem Signieren herunterladen.
  6. Ein Dokument über die API hochladen.

Die Legalesign REST-API ist einfach zu verwenden. Das technische Referenzhandbuch enthält einen Code-Editor. Sie können Anfragen direkt aus der technischen Referenz mit Ihrem API-Schlüssel ausführen, ansonsten kopieren Sie den Code einfach und fügen ihn in Ihren Code ein.

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

Client-Bibliotheken​

Oder für die GraphQL-Schnittstelle Node.js

Tipp

Wir empfehlen Entwicklern, direkt mit der API zu arbeiten, anstatt mit den SDKs. Zur Unterstützung gibt es einen Cut-and-Paste-Codegenerator in der technischen Spezifikation, und Ihre KI kann schnell Beispiele mithilfe der OpenAPI-Spezifikation erzeugen. Warum? Die Quell-API bietet mehr Funktionen als die SDKs, Sie möchten die genutzten Endpunkte eh kennenlernen, Sie vermeiden Abstraktions-Overhead und Abhängigkeiten, und basierend auf unserer Erfahrung kommen Sie so auch schneller zum Ziel.

1. Konto erstellen​

Gehen Sie zu legalesign-Anmeldung und folgen Sie dem Prozess zur Kontoerstellung.

Sie werden aufgefordert, ein Team zu erstellen. Teams sind die Grundbausteine von Legalesign. Die gesamte Dokumentenverarbeitung erfolgt in einem Team. Sie müssen in den meisten API-Aufrufen auf Ihr Team verweisen.

Info

Ein „Team“ oder eine „Gruppe“ ist dasselbe. In der Web-App sprechen wir von „Teams“, im API-Schema heißt es „Gruppe“.

API-Einstellungen​

Gehen Sie zum API-Dashboard. Generieren Sie Ihre API-Anmeldedaten im Abschnitt API-Schlüssel.

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

Sandbox​

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

Der Sandbox-Modus begrenzt auf 100 Aufrufe pro Stunde. Es gibt keine Beschränkungen für Empfänger-E-Mail-Adressen.

Wenn Ihre Integration bereit ist: wechseln Sie in den Produktionsmodus.

Tipp

Erstellen Sie ein zweites Team. Verwenden Sie Ihr erstes Team für die Entwicklung und andere(n) Team(s) für die Produktion. Teilen Sie dem Support den Namen Ihres Dev-Teams mit, damit dieses von der Abrechnung ausgeschlossen wird.

API-Schlüssel​

Im Abschnitt API-Schlüssel sehen Sie Details zu Ihren API-Schlüsseln. Den Schlüssel selbst sehen Sie nur beim Erstellen.

Das Entwicklerportal enthält Cut-and-Paste-Beispiele, um Ihren Schlüssel zu testen.

API Key Section Screenshot

Webhooks & Protokolle​

Webhooks hinzufügen (Ihre Listener für Legalesign-Events) und Ihre Protokolle überprüfen.

Webhooks Section Screenshot

2. Eine erfolgreiche GET-Anfrage​

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

Starten Sie mit einer GET-Anfrage, um zu bestätigen, dass Ihre Anmeldedaten funktionieren. Ersetzen Sie your_api_key durch Ihren Schlüssel aus dem Entwicklerportal.

Curl wird in den Beispielen verwendet, und Sie können über die Reiter unten zwischen cURL, Node.js, Python, C# und Go wechseln.

curl -H "Authorization: Bearer your_api_key" -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 im JSON-Format zurückgegeben. Erfolg. 👏

Die Antwortdaten enthalten den 'resource uri' für Ihre Gruppe und sehen aus wie /api/v1/group/:groupId/. Notieren Sie sich dies, da Sie es für die meisten API-Aufrufe benötigen.

Tipp

Ein resource uri hat immer das gleiche 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 die URLs Ihrer API-Aufrufe, beenden Sie diese immer mit einem Schrägstrich.

Wenn die GET-Anfrage fehlschlägt, überprüfen Sie, ob:

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

Siehe auch Fehlerbehebung.

3. Ein Dokument über die Web-App hochladen​

Um loszulegen, laden wir ein Dokument über die Web-App hoch und senden es dann über die API. Wie man ein Dokument per API hochlädt behandeln wir später.

Gehen Sie zur 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“ könnte sein, wenn Sie eine Unterzeichnerrolle ohne zugehöriges Unterschriftsfeld hinzufügen).

Kopieren Sie im Formular-Editor die lange alphanumerische ID aus der URL, dekodieren Sie sie base64 und verwerfen Sie die ersten 3 Buchstaben (dies sollten 'tpl' sein). Der Rest ist eine UUID, die Ihre ID ist. Mehr zu Web- und API-IDs.

Die REST-API-ID für dieses Dokument ist /api/v1/templatepdf/UUID/.

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

Tipp

Wenn Sie eine Vorlage archivieren möchten, wenn das Dokument versendet wird, setzen Sie „archive_upon_send“ als Attribut im Upload-Request. Wenn die Vorlage niemals erscheinen und nach dem Versand gelöscht werden soll, geben Sie ihr den Titel '[deleted]' – unsere Aufräumsysteme erkennen das und löschen sie nach ein oder zwei Tagen. Sie können auch kurze Vorhaltezeiten auf Gruppenebene einstellen – mehr erfahren.

4. Ein Dokument zum Signieren senden​

Jetzt senden wir dies über die API. Verwenden Sie die Reiter unten, um die Anfrage in Ihrer bevorzugten Sprache zu erhalten.

curl -H "Authorization: Bearer your_api_key" -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, schauen Sie sich alle möglichen Attribute genau an. Viele helfen Ihnen bei den praktischen Details einer Integration – Tags für eigene Referenzen und IDs (die Ihnen in Webhooks zurückgegeben werden), ein Redirect für Unterzeichner, benutzerdefinierter Text im PDF und mehr.

Ein erfolgreicher Aufruf gibt den Statuscode 201 zurück. ✨

Die neue gesendete Dokument-ID erhalten​

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

Tipp

Verwenden Sie Dokument-‘Tag’-Attribute und fügen Sie eigene 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 alle Informationen eines Dokuments anzufordern, verwenden Sie /api/v1/document/:documentId/.

Info

Wenn eine Anfrage nicht erfolgreich ist, enthält der BODY der Antwort in der Regel Fehlermeldungen. Erhalten Sie keinen Erfolgsstatus, prüfen Sie den BODY auf erklärenden Text. Siehe auch Fehlerbehebung.

Mehr zum API-Aufruf Send Document.

5. Das signierte Dokument herunterladen​

Mit der oben erhaltenen gesendeten Dokument-ID machen Sie eine PDF-Download-Anfrage in der gewünschten Sprache:

curl -H "Authorization: Bearer your_api_key" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/

PDF-Download API-Referenz.

Das PDF-Binärformat ist im Body der Antwort enthalten. Der curl '-o' Befehl schreibt den BODY der Antwort direkt in eine Datei.

Viele REST- oder HTTP-Bibliotheken behandeln HTTP-Antwortobjekte wie Dateien, in diesem Fall speichern Sie Ihr Antwortobjekt ganz normal als Datei.

Tipp

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

6. Ein Dokument über die API hochladen​

Hier klicken zum Herunterladen eines Beispiel-PDFs mit Text-Tags, mehr zu PDF-Formularfeldern folgt.

Für diesen Aufruf konvertieren Sie Ihr PDF in eine base64-codierte Zeichenkette. Dies wird im Codegenerator der Dokumentation nicht korrekt durchgeführt. Kopieren Sie diesen Pseudocode und Ihre 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': 'Bearer your_api_key',
'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.

Eine erfolgreiche POST-Antwort gibt den Status 201 zurück und die neue ID steht im location-Antwortheader.

Ihre PDF-Ressourcen-URI sieht aus wie /api/v1/templatepdf/:pdfId/.

Andere Dateiformate​

Word, HTML, Klartext, XLSX und Bilddateien werden alle unterstützt. Laden Sie sie mit dem GraphQL-Datei-Uploader hoch, der das Format automatisch erkennt und in PDF konvertiert. Holen Sie sich die ID und senden Sie sie wie gewohnt über die REST-API. Siehe auch Verstehen von REST- und GraphQL-IDs. Text-Tags werden wie gewöhnlich erkannt.

Das neue PDF senden​

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

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

Bevor Sie mit der Programmierung beginnen, lesen Sie 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 beim Senden geändert werden sollen? Die Antwort ist, dass unser PDF mit Tags vorpräpariert ist: Wir setzen ein Legalesign Text-Tag im PDF und setzen 'process_tags' auf true im PDF-Upload-Request.

Downloaden Sie ein Beispiel-PDF mit Text-Tags.

Text-Tags sind speziell formatierter Text zum Einfügen in ein PDF. Legalesign analysiert den Text in Ihrer Datei und ersetzt die Tags durch Unterschrifts- und Formularfelder. Für einen Unterzeichner müssen Sie nur <<t=signature>> hinzufügen. Legalesign erkennt und platziert die Unterschrift genau dort. Mehr zu Text-Tags.

Andere Methoden zur Positionierung Ihrer Felder sind unten aufgeführt, aber mit Text-Tags erhalten Sie die volle Funktionalität des Legalesign-Formularsystems. Nutzen Sie die Web-App, um Ihre Tags zu testen. Kontaktieren Sie Support für Hilfe und Beispiele.

Hier sind 4 weitere Möglichkeiten, Felder einzurichten:

1. Einfachste/schnellste Version. Richten Sie Ihr PDF mit der Legalesign-Web-App ein.​

Nach dem Hochladen eines PDFs gelangen Sie zur Editor-Oberfläche, wo Sie Formularfelder per Drag & Drop hinzufügen können.

Ziehen Sie eine Unterschrift hinein und notieren Sie die codierte ID in der Webadresse. Diese sieht etwa so aus: 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.

Dekodieren Sie diese ID base64; Sie enthält eine UUID mit dem Präfix „tpl“. Der UUID-Teil (ohne „tpl“) ist Ihre PDF-ID. Mehr zu Legalesign-IDs.

Ihre API-PDF-Ressourcen-URI lautet - /api/v1/templatepdf/:pdfId/.

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

Info

Wenn Sie dieses PDF mehrmals senden möchten, stellen Sie sicher, dass "Auto-Archivierung" deaktiviert ist. Siehe wie

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

Der einfachste Weg, mit x/y-Koordinaten zu starten, ist das Einrichten eines PDFs in der Web-App und dann eine API-Abfrage für diese Felder (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).

Das zurückgegebene JSON-Objekt hat das gleiche JSON-Schema, mit dem Sie ebenso Felder anlegen können.

Verwenden Sie es als Vorlage, ändern Sie Werte und posten Sie es zurück an denselben Endpunkt (passen Sie die PDF-ID entsprechend an). Create PDF Field Endpoint.

3. Unsere PDF-Bearbeitungsseite einbetten. NEU!​

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

4. PDF-Formularfelder NEU!​

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

Viel Spaß beim Programmieren!​

In diesem Tutorial haben Sie API-Anmeldedaten erhalten, erfolgreich Ihre Gruppe(n) abgefragt, ein Dokument zum Signieren mit PDF versendet und ein signiertes Dokument heruntergeladen.

Wir sind gerne für Sie da, kontaktieren Sie den Support für Unterstützung.

Tipp

Überprüfen Sie die Ihnen offenen Versandoptionen. Nehmen Sie sich einen Moment, um alle Attribute auf dem create document endpoint durchzulesen, insbesondere die Attribute 'signers', 'pdftext' und 'signertext'. Ein Signaturdokument erstellen.

Nächste Schritte:​