Zum Hauptinhalt springen

Integration des Dokumenten-Viewers

Der Document Viewer ist eine Webkomponente, mit der Nutzer Vorlagen bearbeiten und Dokumente zur Unterzeichnung vorbereiten können – direkt in Ihrer Anwendung. Diese Anleitung zeigt, wie man ihn mit der GraphQL-API verbindet, um einen vollständigen Signatur-Workflow zu erstellen.

Übersicht​

Eine typische Integration umfasst diese Schritte:

  1. Authentifizieren — ein Token für den Viewer erhalten
  2. Eine Vorlage hochladen — über die GraphQL-API
  3. Den Viewer rendern — Vorlage-ID und Token übergeben
  4. Events erfassen — der Viewer sendet update und validate Events während der Nutzer arbeitet
  5. Das Dokument senden — die send Mutation mit Empfänger- und Rollendaten aus dem Viewer aufrufen

Authentifizierung​

Der Viewer benötigt ein gültiges Token, das als token-Attribut übergeben wird. Ihr Backend stellt ein kurzlebiges Komponenten-Token über generateComponentToken bereit. Siehe Widget Authorization, bevor Sie den Viewer in Ihre Anwendung integrieren.

Compose-Modus — Ein vorgefertigtes Dokument senden​

Der Compose-Modus ist für Workflows gedacht, bei denen Ihr System die Empfänger bereits kennt. Der Nutzer platziert lediglich die Signaturfelder und sendet.

1. Den Viewer rendern​

<ls-document-viewer
id="viewer"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_ACCESS_TOKEN"
mode="compose"
recipients='[
{"email": "jane@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 1},
{"email": "john@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 2}
]'
filtertoolbox="signature|initials|date|text"
>
<span slot="right-button">
<button id="send-btn" disabled>Send</button>
</span>
</ls-document-viewer>

2. Validierung und Rollen-IDs verfolgen​

Während der Nutzer Felder hinzufügt, sendet der Viewer Events. Für diese Events benötigen Sie zwei Dinge:

  • validate — zeigt an, ob die Vorlage alle notwendigen Felder enthält (mindestens eine Signatur pro Empfänger)
  • update — liefert den aktuellen Vorlagenstatus, inklusive roleId für jeden Teilnehmer, wenn die Rollenzuordnung benötigt wird
const viewer = document.getElementById('viewer');
const sendBtn = document.getElementById('send-btn');

let isValid = false;
const recipientRoles = {};

viewer.addEventListener('validate', (e) => {
isValid = e.detail.valid;
sendBtn.disabled = !isValid;
});

viewer.addEventListener('update', (e) => {
const roles = e.detail.template.roles;
roles.forEach((role) => {
recipientRoles[role.signerIndex] = role.id;
});
});

Die roleId aus dem update Event ordnet jedem Empfänger seine Felder in der Vorlage zu. Nehmen Sie diese auf, wenn Ihr Sendevorgang diese Zuordnung benötigt.

3. Das Dokument senden​

Wenn der Nutzer auf Senden klickt, rufen Sie die send Mutation mit den Empfängerdaten und den aus dem Viewer erfassten Rollen-IDs auf:

sendBtn.addEventListener('click', async () => {
const token = '<token-from-authentication-guide>';

const recipients = [
{
firstName: 'Jane',
lastName: 'Smith',
email: 'jane@example.com',
role: 'Signer',
roleId: recipientRoles[1],
signerIndex: 1,
order: 1,
},
{
firstName: 'John',
lastName: 'Doe',
email: 'john@example.com',
role: 'Signer',
roleId: recipientRoles[2],
signerIndex: 2,
order: 2,
},
];

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
query: `mutation SendDocument {
send(input: {
groupId: "YOUR_GROUP_ID"
templateId: "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
title: "Contract - Jane Smith & John Doe"
recipients: ${JSON.stringify(recipients).replace(/"(\w+)":/g, '$1:')}
sequentialSigning: true
})
}`,
}),
});

const result = await response.json();
const taskId = result.data.send;

// Poll for completion
console.log('Task started:', taskId);
});

Die send Mutation gibt eine Task-ID zurück. Polling Sie die task Abfrage und überwachen Sie den Status task.report.status, bis dieser COMPLETED oder FAILED erreicht, um die Fertigstellung der Dokumentenerstellung zu bestätigen.

Editor-Modus — Vorlagenerstellung​

Der Editor-Modus bietet Nutzern die vollständige Bearbeitungserfahrung der Vorlage — Rollen hinzufügen, Felder platzieren, Optionen konfigurieren. Verwenden Sie diesen Modus, wenn Nutzer wiederverwendbare Vorlagen erstellen sollen.

<ls-document-viewer
id="editor"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_ACCESS_TOKEN"
mode="editor"
></ls-document-viewer>

Im Editor-Modus wird das update Event bei jeder Änderung der Vorlage ausgelöst. Sie können dies nutzen, um den Vorlagenstatus zu verfolgen oder eine Speicheranzeige einzublenden:

const editor = document.getElementById('editor');

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

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

Vorlagenänderungen werden automatisch vom Viewer gespeichert — Sie müssen keine GraphQL-Mutation aufrufen, um Änderungen zu sichern.

React-Integration​

Die React-Hülle bietet dieselbe Funktionalität mit React-typischer Ereignisbehandlung:

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

const DocumentCompose = ({ templateId, recipients, token }) => {
const [isValid, setIsValid] = useState(false);
const [roleMap, setRoleMap] = useState({});

const handleValidate = (e) => {
setIsValid(e.detail.valid);
};

const handleUpdate = (e) => {
const roles = e.detail.template.roles;
const map = {};
roles.forEach((role) => {
map[role.signerIndex] = role.id;
});
setRoleMap(map);
};

const handleSend = async () => {
const mappedRecipients = recipients.map((r, i) => ({
...r,
roleId: roleMap[r.signerIndex],
order: i + 1,
}));

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
query: `mutation SendDocument {
send(input: {
groupId: "YOUR_GROUP_ID"
templateId: "${templateId}"
title: "Document"
recipients: ${JSON.stringify(mappedRecipients).replace(/"(\w+)":/g, '$1:')}
})
}`,
}),
});

const result = await response.json();
console.log('Task ID:', result.data.send);
};

if (!token) return null;

return (
<LsDocumentViewer
templateid={templateId}
token={token}
mode="compose"
recipients={JSON.stringify(recipients)}
onValidate={handleValidate}
onUpdate={handleUpdate}
>
<div slot="right-button">
<button onClick={handleSend} disabled={!isValid}>
Send
</button>
</div>
</LsDocumentViewer>
);
};

Zeugen​

Um einen Zeugen für einen Unterzeichner hinzuzufügen, setzen Sie roleType: "WITNESS" und verwenden Sie einen signerIndex, der dem Index des übergeordneten Unterzeichners + 100 entspricht. Beispielsweise hat ein Zeuge für Unterzeichner 2 den signerIndex: 102:

<ls-document-viewer
mode="compose"
recipients='[
{"email": "signer@example.com", "firstname": "Alice", "lastname": "Jones", "signerIndex": 1},
{"email": "signer2@example.com", "firstname": "Bob", "lastname": "Brown", "signerIndex": 2},
{"email": "witness@example.com", "firstname": "Carol", "lastname": "White", "signerIndex": 102, "roleType": "WITNESS"}
]'
...
></ls-document-viewer>

Schlüsselbegriffe​

Viewer-KonzeptGraphQL-TypBeschreibung
templateid AttributTemplateDie bearbeitete oder zusammengesetzte Vorlage
recipients AttributRecipientInputEmpfänger, die im Compose-Modus übergeben werden
roleId aus update EventRoleVerknüpft einen Empfänger mit seinen Feldern in der Vorlage
validate Event—Ob die Vorlage alle erforderlichen Felder enthält
send MutationsendSendet das Dokument nach der Komposition
token Attribut—Token aus der Authentifizierung
mode="compose"—Vereinfachter Modus für das Platzieren von Feldern und Senden
mode="editor"—Vollständiger Bearbeitungsmodus für Vorlagen
experience im Send-InputExperienceSteuert Branding, E-Mails und Signierseite — siehe Erklärung der Experiences