Zum Hauptinhalt springen

Integrieren Sie den Legalesign-Dokumenten-Viewer in Ihre Website

Tipp

Sie können diese Komponente in Aktion als Quick Send in der Console sehen.

Aktuelle Version: v1.0.27 — Changelog

Der Legalesign Document Viewer ist eine plattformunabhängige Webkomponente, mit der Sie Vorlagen für die Dokumentenunterzeichnung bearbeiten, anzeigen und anpassen können. Sie funktioniert nahtlos in HTML mit JavaScript, React, Vue, Angular oder jedem Webframework.

Diese Plug-and-Play-Komponente ist so konzipiert, dass Sie wichtige Teile der Dokumentenerstellung in Ihre internen Systeme integrieren können, wie z. B. ein CRM oder eine Fachanwendung.

Solange Ihr System HTML-Komponenten rendern und unterstützen kann, können Sie den Document Viewer verwenden.

Wenn Sie zusätzliche Unterstützung bei der Integration des Document Viewer in Ihren technischen Stack benötigen, wenden Sie sich bitte an unseren Support.

Sie können diese größeren Widgets mit REST/GraphQL-API-Integrationen verwenden, um nahtlose Dokumentenunterzeichnungsprozesse für Ihre Mitarbeiter und Kunden zu ermöglichen.

Installation​

NPM Installation​

npm install legalesign-document-viewer
# or
pnpm add legalesign-document-viewer

Für React-Projekte​

npm install legalesign-document-viewer-react
# or
pnpm add legalesign-document-viewer-react

Grundlegende Integration​

HTML/JavaScript​

Die HTML/JavaScript-Version dieser Komponente kann mit jedem Entwicklungs-Stack, wie PHP, ASP .Net usw., verwendet werden. Sie können direkt von npm auf die Komponente verlinken, wenn Ihre Umgebung keine Installation zulässt. Eine Demonstrationsseite aus dem Beispiel-Repository finden Sie hier: [https://github.com/legalesign/ls-viewer-demo].

Fügen Sie die Komponentenskripte zu Ihrem HTML hinzu:

<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.css" />
<script type="module" src="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.esm.js"></script>
<script nomodule src="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.js"></script>
</head>
<body>
<ls-document-viewer
id="my-editor"
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
></ls-document-viewer>
</body>
</html>

Authentifizierung - Erhalten Sie ein Token​

Sie müssen serverseitigen Code verwenden, um YOUR_AUTH_TOKEN zu erhalten. Es gibt zwei Optionen, und beide verwenden Ihren API-Schlüssel:

  1. GraphQL generateComponentToken — Rufen Sie die Mutation mit Ihrem API-Schlüssel auf, um ein kurzlebiges, eingrenzbares Komponententoken zu erzeugen.
  2. REST API — Rufen Sie GET /templatepdf/{pdfId}/component-token/ mit Ihrem API-Schlüssel auf.

Option 1 (GraphQL):

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
},
body: JSON.stringify({
query: `mutation {
generateComponentToken(input: { component: LS_DOCUMENT_VIEWER }) {
token
expiresIn
expiresAt
}
}`,
}),
});

const { data } = await response.json();
const token = data.generateComponentToken.token;

Option 2 (REST):

const response = await fetch(
`https://eu-api.legalesign.com/api/v1/templatepdf/${pdfId}/component-token/`,
{
headers: {
Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
},
}
);

const { token } = await response.json();

Übergeben Sie das zurückgegebene token an das Widget. Weitere Details zu Tokenoptionen finden Sie unter Widget Authorization.

React-Integration​

Wir haben auch eine Version der Komponente erstellt, die sich direkt in React-Frameworks integrieren lässt.

import { LsDocumentViewer } from 'legalesign-document-viewer-react';

function App() {
return (
<LsDocumentViewer
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
mode="compose"
/>
);
}

Erforderliche Attribute​

token​

Ihr Sicherheitstoken zur Authentifizierung: ein kurzlebiges Komponententoken von generateComponentToken oder dem REST-Endpunkt component-token. Weitere Informationen zum sicheren Tokenfluss finden Sie unter Widget Authorization.

token="eyJraWQiOiJBTkJIeT..."

templateid​

Die API-ID der Vorlage, die Sie den Benutzern präsentieren möchten. Diese finden Sie in der URL, wenn Sie die Vorlage in der Webanwendung bearbeiten.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Widget-Modi​

Editor-Modus​

Voll ausgestattete Vorlagenerstellung und -bearbeitung mit allen verfügbaren Werkzeugen. Dieser Modus ist für Workflows gedacht, bei denen eine hochgradig wiederverwendbare Vorlage mit Rollen hilfreich ist. Wenn Sie das Dokument nur einmal verwenden möchten (vielleicht hat Ihr Dokumentengenerierungssystem bereits alle Kundeninformationen ausgefüllt), sollten Sie stattdessen den Compose-Modus in Betracht ziehen.

<ls-document-viewer mode="editor" ...></ls-document-viewer>

Compose-Modus​

Dieser Modus ist eine „Empfänger-zuerst“-Methode, um die Benutzererfahrung zu vereinfachen. In der Legalesign-Webanwendung ist dies die Funktion „Quick send“.

Fügen Sie Ihre Empfänger dem Attribut „recipient“ hinzu, und Ihr Benutzer kann schnell seine Unterschriften und Formularfelder platzieren, bevor er das Dokument sendet. Ideal für integrierte Kunden, bei denen Empfänger bereits definiert sind.

Der typische Workflow ist: PDF klonen oder hochladen, dann den Viewer einbetten, wo der Benutzer Unterschrifts- und Formularfelder hinzufügen kann, und dann eine Schaltfläche zum Senden des Dokuments anbieten.

Klonen​

Klonen Sie eine vorhandene Vorlage mit der Mutation copyTemplate:

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: `
mutation CopyTemplate {
copyTemplate(input: {
groupId: "yourGroupId",
templateId: "yourTemplateId",
newTitle: "new document title",
copyFields: true|false
})
}
`
})
});
const { data } = await response.json();
const templateId = data.copyTemplate;

Oder Hochladen​

Erstellen Sie eine Vorlage und laden Sie diese dann auf die bereitgestellte uploadUrl hoch. Verwenden Sie den Titel [deleted], wenn Sie das PDF nicht in Ihrer Bibliothek behalten möchten. Es wird in den nächsten 24 Stunden gelöscht. Andernfalls können Sie jeden gewünschten Titel verwenden:

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: `
mutation CreateTemplate {
createTemplate(input: {groupId: "yourGroupid", title: "[deleted]"}) {
id
uploadUrl
}
}
`
})
});
const { data } = await response.json();
const templateId = data.createTemplate.id;
const uploadUrl = data.createTemplate.uploadUrl;

Laden Sie nun Ihre Datei per PUT auf die uploadUrl hoch. Der Content-Type muss application/pdf sein.

Viewer einbetten​

Das Hauptattribut ist 'recipients'. Für Genehmiger oder Zeugen benötigen Sie zusätzliche Details – weitere Informationen finden Sie unter Recipients.

<ls-document-viewer 
mode="compose"
recipients='[
{"email": "user@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1},
{"email": "user2@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 2}
]'
...></ls-document-viewer>

Der Compose-Modus bewirkt automatisch:

  • Erkennung vorab generierter Empfänger
  • Verstecken des Absenders im Dropdown
  • Verstecken der Dokumentoptionen
  • Anzeigen der erforderlichen Felder standardmäßig
  • Entfernen des Absenders und der Absenderfelder aus dem Editor
  • Förderung der schnellen Auswahl der erforderlichen Felder für jeden Empfänger

Vorschau-Modus​

Eine hilfreiche Dokumentenvorschau, die das Dokument mit allen aktuellen Feldern anzeigt und dem Benutzer das Blättern durch die Seiten ermöglicht.

<ls-document-viewer mode="preview" ...></ls-document-viewer>

Der Vorschau-Modus bewirkt automatisch:

  • Verstecken der Symbolleiste
  • Verstecken der Dokumentoptionen
  • Verstecken der Toolbox
  • Teilnehmer und Felder werden schreibgeschützt

Erweiterte Konfiguration​

Filter-Toolbox​

Beschränken Sie verfügbare Feldtypen mit durch Pipes getrennten Werten. Wenn kein Wert angegeben ist, wird davon ausgegangen, dass die Toolbox ungefiltert ist und alle Optionen verfügbar sind.

<ls-document-viewer
filtertoolbox="signature|initials|date|text"
...
></ls-document-viewer>

Verfügbare Filterwerte:

WertBeschreibung
signatureUnterschriftsfeld (nur Unterzeichner)
auto signAuto-Unterschriftsfeld (nur Absender)
textFreier Texteingabe
signing dateDatum, das beim Unterschreiben automatisch ausgefüllt wird (nur Unterzeichner)
dateDatumsauswahlfeld
emailE-Mail-Eingabe
initialsInitialenfeld
numberNumerische Eingabe
dropdownDropdown-Auswahl
checkboxKontrollkästchen
regexRegex-validierte Eingabe (nur Unterzeichner)
imageBild-Upload (nur Unterzeichner)
fileDatei-Upload (nur Unterzeichner)
drawnZeichnungs-/Freihandfeld (nur Unterzeichner)

Empfänger​

Definieren Sie Dokumentempfänger im JSON-Format.

Die erforderlichen Elemente für jeden Empfänger sind firstname, lastname, email und signerIndex;

Optional können Sie für jeden Empfänger die Rolle und Telefonnummer übergeben. Wird keine Rolle angegeben, wird der Empfänger als Unterzeichner behandelt.

Sie können die Rolle "WITNESS" oder "APPROVER" angeben. Für die Rolle "WITNESS" addieren Sie 100 zur signerIndex-Nummer des jeweiligen Unterzeichners. Wenn Sie beispielsweise einen Zeugen für Unterzeichner 2 (signerIndex: 2) benötigen, geben Sie WITNESS signerIndex: 102 an.

<ls-document-viewer
recipients='[
{"email": "user@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1},
{"email": "user2@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 2}
{"email": "user3@example.com", "firstname": "Joan", "lastname": "Mitchell", "signerIndex": 102, roleType: "WITNESS"}
]'
...
></ls-document-viewer>

Benutzerdefinierte Schaltflächen mit Slots​

Fügen Sie der Symbolleiste benutzerdefinierte Schaltflächen mit Slots hinzu. Wahrscheinlich verwenden Sie diese, um entweder den Vorgang abzubrechen oder das Dokument zu senden.

<ls-document-viewer ...>
<style>
.custom-button {
padding: 2px 12px;
border-radius: 1rem;
background-color: #9df5d4;
color: #125241;
font-weight: 500;
}
</style>
<span slot="left-button">
<button class="custom-button">Cancel</button>
</span>
<span slot="right-button">
<button class="custom-button">Send Document</button>
</span>
</ls-document-viewer>

Ereignisverarbeitung​

Hören Sie auf Komponentenevents, um Änderungen zu verfolgen:

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('update', (event) => {
console.log('Template changed:', event.detail);
});

Sie können verfolgen, ob eine Vorlage gültig oder ungültig geworden ist, indem Sie das validate-Event verwenden.

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('validate', (event) => {
console.log('Template validation changed:', event.detail.valid);
});

Beispiel für Event-Handling in React​

In React werden Events mit dem bekannten Präfix on<EventName> benutzt.

<LsDocumentViewer
onUpdate={(event) => {
console.log('Template changed:', event.detail);
}}
...
/>

Event-Typen​

update-Event​

Wird ausgelöst, wenn die Dokumentvorlage geändert wird, z. B. durch Hinzufügen oder Entfernen von Feldern. Liefert nicht nur das auslösende Event, sondern auch den aktualisierten Zustand des Vorlagenobjekts als JSON.

validate-Event​

Wird ausgelöst, wenn die Dokumentvorlage geändert wird; die Eigenschaft valid im Detail zeigt an, ob die Vorlage gültig oder ungültig geworden ist.

selectFields-Event​

Wird ausgelöst, wenn ein Feld im Editor ausgewählt wird.

addParticipant-Event​

Wird ausgelöst, wenn eine Teilnehmerrolle zur Vorlage hinzugefügt wird.

Komplettes Beispiel​

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document Editor</title>
<link rel="stylesheet" href="https://unpkg.com/legalesign-document-viewer/ls-document-viewer.css" />
<script type="module" src="https://unpkg.com/legalesign-document-viewer"></script>
</head>
<body style="padding: 0; margin: 0">
<ls-document-viewer
id="my-editor"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_TOKEN_HERE"
mode="compose"
recipients='[
{"email": "signer@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1}
]'
filtertoolbox="signature|initials|date"
>
<span slot="left-button">
<button onclick="handleCancel()">Cancel</button>
</span>
<span slot="right-button">
<button onclick="handleSend()">Send</button>
</span>
</ls-document-viewer>

<script>
const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('update', (event) => {
// shows the change event and the template details
console.log('Document updated:', event.detail);
});

function handleCancel() {
// Implement the cancel logic, e.g. go to a home page
window.location.href = '/cancelpage';
}

function handleSend() {
// Implement send logic if required.
console.log('Sending document...');
}
</script>
</body>
</html>

Senden Sie das Dokument serverseitig mit Ihrem API-Schlüssel über die GraphQL- oder REST-Schnittstelle.

Fehlerbehebung

Wenn Sie Probleme mit der Komponente haben, stellen Sie sicher, dass:

  • Sie auf die Domain der Dokumentenspeicherung zugreifen können oder diese unter https://s3.amazonaws.com/* freigeschaltet haben

Browser-Unterstützung​

Die Komponente verwendet moderne Webstandards und unterstützt:

  • Chrome/Edge (neueste Version)
  • Firefox (neueste Version)
  • Safari (neueste Version)
  • Mobile Browser (iOS Safari, Chrome Mobile)

Changelog​

VersionDatumZusammenfassung
v1.0.2719. Okt 2026Verbesserungen bei der Feldpositionierung
v1.0.263. Sep 2026Scroll-Fixes; verzögertes Rendering beim Laden
v1.0.2112. Aug 2026Vorschau-Modus-Optionen; Verbesserungen beim update-Event
v1.0.1817. Jul 2026Regex-Feldpanel; erweiterte Eigenschaften für Mehrfachfelder; Dropdown-Verbesserungen; Umbenennung von Zeugen
v1.0.1210. Jul 2026excludeFromPdf-Feld-Eigenschaft
v1.0.99. Jul 2026Auto-Datum und Regex-Felder; erweiterte Eigenschaften; Feldreihenfolge
v1.0.62. Jul 2026Schriftarten-Fix zur Vermeidung von Signaturfehlern; Vorschau-Ränder
v1.0.529. Jun 2026Undo/Redo-Tastenkürzel
v1.0.426. Jun 2026Verbesserungen bei Events; optimistische Updates; Undo/Redo
v1.0.024. Jun 2026Erste stabile Version

Ressourcen​

Hilfe erhalten​

Für technischen Support oder Fragen zur Integration wenden Sie sich an das Legalesign-Supportteam oder besuchen Sie die API-Dokumentation.