Intégrer le Visionneur de Documents

Le Visionneur de Documents est un composant web qui permet aux utilisateurs de modifier des modèles et de préparer des documents pour la signature — directement dans votre application. Ce guide montre comment le connecter à l’API GraphQL pour construire un flux de travail complet de signature.

Vue d’ensemble

Une intégration typique suit ces étapes :

S’authentifier — obtenir un jeton pour le visionneur
Téléverser un modèle — via l’API GraphQL
Afficher le visionneur — passer l’ID du modèle et le jeton
Capturer les événements — le visionneur émet des événements update et validate pendant que l’utilisateur travaille
Envoyer le document — appeler la mutation send avec les données du destinataire et du rôle issues du visionneur

Authentification

Le visionneur a besoin d’un jeton valide passé à son attribut token. Voir S’authentifier avec l’API avant de connecter le visionneur à votre application.

Mode Composition — Envoyer un Document Pré-construit

Le mode composition est destiné aux flux où votre système connaît déjà les destinataires. L’utilisateur place simplement les champs de signature et envoie.

1. Afficher le visionneur

<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. Suivre la validation et les IDs de rôle

Lorsque l’utilisateur ajoute des champs, le visionneur émet des événements. Vous avez besoin de deux choses à partir de ces événements :

validate — indique si le modèle contient tous les champs requis (au minimum, une signature par destinataire)
update — fournit l’état actuel du modèle, y compris le roleId pour chaque participant lorsque vous avez besoin de mapper les rôles du modèle

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;
  });
});

Le roleId issu de l’événement update associe chaque destinataire à ses champs sur le modèle. Incluez-le lorsque votre flux d'envoi a besoin de ce mappage.

3. Envoyer le document

Lorsque l’utilisateur clique sur envoyer, appelez la mutation send avec les données des destinataires et les IDs de rôle récupérés depuis le visionneur :

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);
});

La mutation send retourne un ID de tâche. Interrogez la requête task et surveillez task.report.status jusqu’à ce qu’il atteigne COMPLETED ou FAILED pour confirmer la fin de la création du document.

Mode Éditeur — Création de Modèle

Le mode éditeur offre aux utilisateurs une expérience complète d’édition de modèle — ajout de rôles, placement de champs, configuration d’options. Utilisez-le lorsque vous souhaitez que les utilisateurs créent des modèles réutilisables.

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

En mode éditeur, l’événement update est déclenché à chaque modification du modèle. Vous pouvez l’utiliser pour suivre l’état du modèle ou afficher un indicateur de sauvegarde :

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);
});

Les modifications du modèle sont sauvegardées automatiquement par le visionneur — vous n’avez pas besoin d’appeler une mutation GraphQL pour persister les modifications.

Intégration React

Le composant React fournit la même fonctionnalité avec une gestion des événements à la manière React :

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>
  );
};

Témoins

Pour ajouter un témoin à un signataire, définissez roleType: "WITNESS" et utilisez un signerIndex égal à l’index du signataire parent + 100. Par exemple, un témoin pour le signataire 2 a 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>

Concepts clés

Concept du visionneur	Type GraphQL	Description
attribut `templateid`	`Template`	Le modèle en cours d’édition ou de composition
attribut `recipients`	`RecipientInput`	Destinataires passés en mode composition
`roleId` issu de l’événement `update`	`Role`	Lie un destinataire à ses champs sur le modèle
événement `validate`	—	Indique si le modèle contient tous les champs requis
mutation `send`	`send`	Envoie le document après composition
attribut `token`	—	Jeton issu de l’authentification
`mode="compose"`	—	Mode simplifié pour placer des champs et envoyer
`mode="editor"`	—	Mode complet d’édition de modèle
`experience` dans l’entrée send	`Experience`	Contrôle la marque, les e-mails et la page de signature — voir Explications sur les expériences

Liens connexes

Référence du Visionneur de Documents — référence complète des attributs et événements
mutation send — envoyer un document
DocumentSendSettingsInput — structure complète des entrées send
Explications des méthodes d’envoi — send vs sendBatch vs sendBulk
Téléverser un fichier en tant que modèle — téléverser des modèles via l’API
Authentification — choisir un mode d’authentification

Vue d’ensemble​

Authentification​

Mode Composition — Envoyer un Document Pré-construit​

1. Afficher le visionneur​

2. Suivre la validation et les IDs de rôle​

3. Envoyer le document​

Mode Éditeur — Création de Modèle​

Intégration React​

Témoins​

Concepts clés​

Liens connexes​

Export This Article