Integration des Dokumenten-Viewers

Der Dokumenten-Viewer ist eine Web-Komponente, die es Nutzern ermöglicht, Vorlagen zu bearbeiten und Dokumente zum Unterschreiben vorzubereiten – direkt in Ihrer Anwendung. Dieser Leitfaden zeigt, wie man ihn mit der GraphQL-API verbindet, um einen vollständigen Signatur-Workflow zu erstellen.

Überblick

Eine typische Integration folgt diesen Schritten:

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

Authentifizierung

Der Viewer benötigt ein gültiges Token, das an das Attribut token übergeben wird. Siehe Authentifizierung mit der API, bevor Sie den Viewer in Ihre Anwendung integrieren.

Kompositionsmodus — Ein vorgefertigtes Dokument senden

Der Kompositionsmodus ist für Workflows gedacht, bei denen Ihr System die Empfänger bereits kennt. Der Nutzer platziert nur die Unterschriftsfelder und sendet das Dokument.

1. Den Viewer anzeigen

<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 überwachen

Während der Nutzer Felder hinzufügt, sendet der Viewer Ereignisse. Von diesen Ereignissen benötigen Sie zwei Dinge:

• validate — gibt an, ob die Vorlage alle erforderlichen Felder enthält (mindestens eine Unterschrift pro Empfänger)
• update — liefert den aktuellen Vorlagenstatus, einschließlich roleId für jeden Teilnehmer, wenn Sie die Zuordnung der Rollen benötigen

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-Ereignis ordnet jedem Empfänger dessen Felder in der Vorlage zu. Fügen Sie sie hinzu, wenn Ihr Sendefluss diese Zuordnung benötigt.

3. Das Dokument senden

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

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 Aufgaben-ID zurück. Befragen Sie die task-Abfrage und überwachen Sie task.report.status, bis dieser den Status COMPLETED oder FAILED erreicht, um zu bestätigen, dass die Dokumentenerstellung abgeschlossen ist.

Editor-Modus — Vorlage erstellen

Der Editor-Modus bietet Nutzern die vollständige Erfahrung zur Vorlagenbearbeitung — 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-Ereignis jedes Mal ausgelöst, wenn sich die Vorlage ändert. Sie können dies verwenden, um den Vorlagenstatus zu verfolgen oder einen Speicherindikator anzuzeigen:

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 vom Viewer automatisch gespeichert — Sie müssen keine GraphQL-Mutation aufrufen, um Änderungen zu sichern.

React-Integration

Der React-Wrapper bietet die gleiche Funktionalität mit ereignisgesteuerter Handhabung im React-Stil:

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 einen signerIndex, der dem Index des übergeordneten Unterzeichners plus 100 entspricht. Zum Beispiel 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>

Wichtige Konzepte

Konzept des Viewers	GraphQL-Typ	Beschreibung
templateid-Attribut	Template	Die bearbeitete oder komponierte Vorlage
recipients-Attribut	RecipientInput	Empfänger für den Kompositionsmodus
roleId aus dem update-Ereignis	Role	Verknüpft einen Empfänger mit seinen Feldern in der Vorlage
validate-Ereignis	—	Gibt an, ob die Vorlage alle erforderlichen Felder enthält
send-Mutation	send	Sendet das Dokument nach der Komposition
token-Attribut	—	Token aus der Authentifizierung
mode="compose"	—	Vereinfachter Modus zum Platzieren von Feldern und Senden
mode="editor"	—	Vollständiger Vorlagen-Editiermodus
experience im Sende-Input	Experience	Steuert Branding, E-Mails und Signaturseite — siehe Erklärungen zu Experiences

Verwandte Themen

• Dokumenten-Viewer-Referenz — vollständige Attribut- und Ereignisübersicht
• send-Mutation — ein Dokument senden
• DocumentSendSettingsInput — vollständige Struktur des Sendeinputs
• Erklärungen zu Versandmethoden — send vs sendBatch vs sendBulk
• Eine Datei als Vorlage hochladen — Vorlagen über die API hochladen
• Authentifizierung — einen Authentifizierungsmodus wählen