Zum Hauptinhalt springen

Schnellstart-Tutorial

Tipp

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

In diesem Tutorial werden Sie die wichtigsten API-Aufrufe durchführen, die die meisten Entwickler für eine eSignature-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 produktiv getestet. Sie können sie für ein einfaches Dokument mit einem Unterzeichner verwenden oder Dokumente zum Beglaubigen oder für Genehmigungen versenden, optimiert für Stapelverarbeitung, mit Formularen und mehr. Sie können die Integration für einen Zweck nutzen 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 beides nutzen, je nach Präferenz.

Wir folgen diesen Schritten:

  1. Erstellen Sie ein Konto + API-Schlüssel (siehe API-Zugriff verifizieren).
  2. Bestätigen Sie, dass die Zugangsdaten funktionieren und holen Sie Ihre Team-ID.
  3. Laden Sie ein Dokument über die Web-App hoch.
  4. Versenden Sie dieses zur Unterschrift über die API.
  5. Laden Sie das Dokument nach der Unterzeichnung herunter.
  6. Laden Sie ein Dokument über die API hoch.

Die Legalesign REST API ist einfach zu verwenden. Die technische Referenz beinhaltet einen Code-Editor. Sie können Anfragen direkt aus der technischen Referenz mit Ihrem API-Schlüssel stellen, oder Sie kopieren und fügen den Code einfach 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 statt mit den SDKs zu arbeiten. Um zu helfen, gibt es einen Kopier-und-Einfügen-Codegenerator in der technischen Spezifikation, und Ihre KI kann schnell Beispiele mit der OpenAPI-Spezifikation erzeugen. Warum? Die Quell-API hat mehr Funktionen als die SDKs, Sie werden sowieso die Endpunkte kennenlernen wollen, die Sie verwenden, Sie vermeiden Abstraktionsaufwand und Abhängigkeiten, und – basierend auf unserer Erfahrung – geht es auch schneller.

1. Konto erstellen

Gehen Sie auf legalesign sign up und folgen Sie dem Prozess, um ein Konto zu erstellen.

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

Info

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

API-Einstellungen

Gehen Sie zum API Dashboard. Erzeugen Sie Ihre API-Anmeldeinformationen im Bereich API-Schlüssel.

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

Sandbox

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

Der Sandbox-Modus wendet eine Begrenzung von 100 Aufrufen pro Stunde an. Es gibt keine Einschrä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 Teams für Produktion. Informieren Sie den Support über den Namen Ihres Dev-Teams, um es von der Abrechnung auszuschließen.

API-Schlüssel

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

Der Schnellstart-Abschnitt enthält Kopierbeispiele, 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. Erfolgreiche GET-Anfrage

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

Beginnen Sie mit einer GET-Anfrage, um zu prüfen, ob Ihre Zugangsdaten funktionieren. Ersetzen Sie your_api_key durch Ihren Schlüssel aus dem Entwicklerportal.

Curl wird in den Beispielen verwendet, und Sie können zwischen cURL, Node.js, Python, C# und Go mittels Tabs unten 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 reference.

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

Die Antwort enthält die „resource uri“ für Ihre Gruppe und sieht aus wie /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 eine PDF wäre es '/api/v1/templatepdf/:pdfId/', für ein versendetes Dokument '/api/v1/document/:documentId/'. Beachten Sie, dass alle URIs mit einem Schrägstrich enden. Das gilt auch für URLs Ihrer API-Aufrufe – immer mit einem Schrägstrich enden.

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

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

Siehe auch Fehlerbehebung.

3. Dokument über die Web-App hochladen

Zum Start laden wir ein Dokument über die Web-App hoch und versenden es dann über die API. Wir behandeln später wie man ein Dokument über die API hochlädt.

Gehen Sie zur Web-App und laden Sie Ihr Dokument hoch. Fügen Sie eine einzelne Signiererrolle 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, wenn Sie eine Signiererrolle ohne ein dazugehörendes Unterschriftsfeld hinzufügen).

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

Im REST API-Jargon ist die resource uri für dieses Dokument /api/v1/templatepdf/UUID/.

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

Unsere Nomenklatur ist, 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 in der Upload-Anfrage. Wenn die Vorlage nie erscheinen soll und nach dem Versand gelöscht werden soll, geben Sie ihr den Titel '[deleted]' – unsere Bereinigungssysteme erkennen das und löschen es nach ein oder zwei Tagen. Sie können auch kurze Aufbewahrungszeiten auf Gruppenebene einstellen – mehr erfahren.

4. Dokument zum Unterschreiben versenden

Jetzt versenden wir dieses über die API. Nutzen Sie die Tabs 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/

Ersetzen Sie alle eckigen Klammern. API-Referenz zum Versenden eines Dokuments.

Tipp

Wenn Sie die Referenzdokumentation zum Versenden eines Dokuments besuchen, schauen Sie sich die möglichen Attribute genau an. Sie werden viele finden, die bei der praktischen Integration helfen – Tags für eigene Referenzen und IDs (die Sie in Webhooks zurückbekommen), eine Weiterleitung für Unterzeichner, benutzerdefinierten Text im PDF setzen und mehr.

Ein erfolgreicher Aufruf gibt den Statuscode 201 zurück.

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 ihre eigenen Referenzen hinzu, um die Verknüpfung mit Ihrer eigenen Datenbank zu erleichtern.

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

Die 'status' URI gibt eine kurze (und schnell abfragbare) Menge von Dokument-Attributen zurück.

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

Info

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

Erfahren Sie mehr über den Send Document API-Aufruf.

5. Das unterschriebene Dokument herunterladen

Mit der oben erhaltenen gesendeten Dokument-ID stellen Sie eine PDF-Download-Anfrage in der Sprache Ihrer Wahl:

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 befindet sich im Body der Antwort. Der curl-Befehl '-o' schreibt den BODY der Antwort direkt in eine Datei.

Viele REST- oder HTTP-Bibliotheken behandeln HTTP-Antwortobjekte wie Dateien, in diesem Fall speichern Sie das Antwortobjekt einfach wie eine normale Datei.

Tipp

Benutzen 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 eines mit Text-Tags versehenen PDFs herunterzuladen, mehr zu PDF-Formularfeldern folgt.

Für diesen Aufruf konvertieren Sie Ihr PDF in einen base64-codierten String. Das wird im Code-Generator der Dokumentation nicht korrekt durchgeführt. Kopieren Sie stattdessen diesen Pseudocode, 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': '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.

Wie üblich gibt eine erfolgreiche POST-Antwort den Status '201' zurück, und die neue ID befindet sich im 'Location'-Header der Antwort.

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

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

Das neue PDF versenden

Gehen Sie zurück zum Code, den Sie für das Versenden Ihres ersten Dokuments verwendet haben, und ersetzen Sie den templatepdf-Wert.

Führen Sie die Anfrage erneut aus – geschafft, Sie haben Ihr PDF zum Signieren versendet.

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

Was ist mit PDF-Feldern?

Wie weiß Legalesign, wo die Person auf dem PDF unterschreiben muss oder welche Abschnitte beim Versand geändert werden sollen? Die Antwort ist, dass unser PDF mit Tags vorgefertigt ist: Wir setzen eine Legalesign-Textmarke in das PDF und setzen in der PDF-Upload-Anfrage 'process_tags' auf true.

Download eines Beispiel-PDFs mit Text-Tags.

Texttags sind speziell formatierte Texte im PDF. Legalesign erkennt die Texte 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 dies und platziert dort die Unterschrift. Erfahren Sie mehr über Texttags.

Texttags erfordern etwas Übung. Weitere Methoden sind unten beschrieben, aber mit ihnen erhalten Sie die volle Leistungsfähigkeit des Legalesign-Formularsystems. Verwenden Sie die Web-App, um 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.

Nachdem Sie ein PDF hochgeladen haben, gelangen Sie zur Editor-Oberfläche, wo Sie Formularfelder per Drag-and-Drop hinzufügen können.

Ziehen Sie ein Unterschriftsfeld und notieren Sie die kodierte ID in der Webadresse. Diese sieht etwa so aus: 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.

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

Ihre API-PDF-Resource-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 wollen, stellen Sie sicher, dass 'Autoarchivierung' ausgeschaltet ist. So geht’s

2. Verwendung von x/y-Koordinaten für Felder.

Der einfachste Weg, mit x/y-Koordinaten zu starten, ist, ein PDF in der Web-App zu erstellen und dann die Felder via API abzufragen (GET PDF-Felder - /api/v1/templatepdf/:pdfId/fields/).

Das JSON-Objekt, das Sie erhalten, ist genau dasselbe JSON-Schema, mit dem Sie auch Felder erstellen können.

Verwenden Sie es als Vorlage. Ändern Sie Werte und senden Sie es per POST zurück an denselben Endpunkt (passen Sie die PDF-ID entsprechend an). Create PDF Field endpoint.

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

Nutzen Sie unsere Editor-Komponente, um unseren PDF-Editor direkt in Ihre eigene App einzubinden. 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 Coden!

In diesem Tutorial haben Sie API-Zugangsdaten erworben, erfolgreich nach Ihrer Gruppe(n) abgefragt, ein Dokument zum Signieren über HTML und PDF versendet und ein unterschriebenes Dokument heruntergeladen.

Viel Spaß beim Programmieren! Wir sind hier, um zu helfen, kontaktieren Sie Support für Unterstützung.

Tipp

Super, Sie sind bis hierher gekommen – danke fürs Lesen. Unser letzter Tipp, basierend auf jahrelanger Erfahrung mit Entwicklern, die diese API integrieren: Nehmen Sie sich einen Moment Zeit, alle Attribute des Endpunkts zum Erstellen eines Dokuments durchzusehen (und klicken Sie sich durch „signers“, „pdftext“ und „signertext“) – das ist der wichtigste Aufruf Ihrer Integration. Dokument zum Signieren erstellen.

Nächste Schritte: